marco/dc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity
6d41159e36
dc/man.md

14 KiB
Raw Blame History

title section header footer date
dc 1 General Commands Manual Marco Cetica November 07, 2023

NAME

dc − RPN desktop calculator with macro support

SYNOPSIS

RPN desktop calculator with macro support. Usage: 
-e, --expression <EXPRESSION> | Evaluate an expression
-f, --file <FILE>             | Evaluate a file
-h, --help                    | Show this helper
-V, --version                 | Show version

DESCRIPTION

dc is an advanced, scientific and programmable RPN desktop calculator with macro support (re)written in C++. By default, dc supports a wide range of arithmetical, trigonometrical and numerical functions. Its capabilities can be further extended by writing user-defined programs using the embedded, turing-complete, macro system.

dc uses the reverse polish notation(RPN) to parse mathematical expressions. Unlike the infix notation, where operators are placed between operands, the polish notation(also called prefix notation) places operators before the operands. The reverse polish notation takes this concept even further by placing the operators after the operands. As an example, consider the following infix expression:

    (((5 + 4) * (3 - 2)) / 2)

In RPN, this would be:

    2 5 4 + 3 2 - * r / p

Operands are pushed onto the stack following the LIFO policy; operators, on the other hand, pop one or more values from the stack and push back the result. By default dc is very quiet, in order to inquiry the stack you need to use one of the supported options(see below).

dc reads from the standard input, but it can also work with text files using the -f flag. Futhermore, you can decide to evaluate an expression without opening the REPL by using the -e flag.

ARCHITECTURE

As an advanced scientific calculator, dc has a complex architecture defined by the following two data structures:

  1. The main stack
  2. The register ADT

Which can be graphically represented as follows:

+------------------+         +----+----+----+-----
|    MAIN STACK    +-------->|    |    |    |    ... STACK
+------------------+         +----+----+----+-----
|   REGISTER ADT   |
+---------------+--+
                |                                +----+----+----+-----
                |               HASH MAP         |    |    |    |    ...  STACK
                |            +-------+---+------>+----+----+----+-----
                |            | REG A |   |
                +----------->+-------+---+------>+----+----+----+-----
                             |           |       |    |    |    |    ...  ARRAY
                             |           |       +----+----+----+-----
                             |           |         0    1    2    3
                             |    ....   |
                             |           |
                             |           |
                             |           |       +----+----+----+-----
                             |           |       |    |    |    |    ...  STACK
                             +-------+---+------>+----+----+----+-----
                             | REG G |   |
                             +-------+---+------>+----+----+----+-----
                                                 |    |    |    |    ...  ARRAY
                                                 +----+----+----+-----
                                                   0    1    2    3

The main stack is the primary form of memory available in this program. Every time you enter a number or execute a command, you are operating within the main stack. The main stack is virtually infinite and grows as much as needed; the main stack is public, i.e. it is shared between any dc command.

The register is an hash map-like abstract data type that allows users to operate on an isolated environment formed by a stack and an array. Each instance of the register is an ordered pair (key, value) where the key is a character representing the name of the register and the value is a private instance of a stack and a private instance of an array. dc commands - exception made for registers, macro and array commands - cannot operate directly on the auxiliary stacks or on the auxiliary arrays. In order to use a value stored on an auxiliary stack, you need to pop it and push it onto the main stack(see the register section).

Both the main stack and the auxiliary stack implement the same abstract data type, therefore any kind of data type supported by the main stack - as well as any other property or feature supported by the main stack - is also supported by the register's stack.

Arrays are dynamic, homogeneous and private abstract data type associated with a register. The underlying data type of a dc array is a hashmap where the index is represented by the map's key and the associated value is represented by the map's value.

TYPE SYSTEM

By default each value of any kind of stack is represented by a string. Each operation is in charge to type convert the value before and after their invocation. The user can store both numerical and alphanumerical values on the stack. The latter using the macro syntax(see below).

Arrays are homogeneous, thus the only supported data type is the string(the internal string type and not the dc one).

COMMANDS

Below, there is a list of supported dc commands.

Printing Commands

p

Prints the value on the top of the stack, without altering the stack. A newline is printed after the value.

P

Pops off the value on top of the stack, without altering the stack.

f

Prints the entire contents of the stack without altering anything.

Arithmetic

+

Pops two values off the stack, adds them, and pushes the result.

-

Pops two values, subtracts the first one popped from the second one popped, and pushes the result.

*

Pops two values, multiplies them, and pushes the result.

/

Pops two values, divides the second one popped from the first one popped, and pushes the result.

%

Pops two values, computes the remainder of the division between the second one popped and the first one popped. Pushes back the result.

~

Pops two values, divides the second one popped from the first one popped. The quotient is pushed first, and the remainder is pushed next.

^

Pops two values and computes their exponentiated, using the first value popped as the exponent and the second popped as the base.

|

Pops three values and computes a modular exponentiation. The first value popped is used as the reduction modulus; this value must be a non-zero integer. The second popped is used as the exponent; this value must be a non-negative number. The third value popped is the base which gets exponentiated, which should also be an integer. This function computes the following modular equivalence: c ≡ b^e (mod n)

v

Pops one value, computes its square root, and pushes that.

!

Pops one value, computes its factorial, and pushes that.

pi

Pushes pi approximation

e

Pushes e approximation

Trigonometrical

sin

Pops one value, computes its sin, and pushes that.

cos

Pops one value, computes its cos, and pushes that.

tan

Pops one value, computes its tan, and pushes that.

Base Conversion

pb

Prints the value on the top of the stack in base 2, without altering the stack. A newline is printed after the value.

po

Prints the value on the top of the stack in base 8, without altering the stack. A newline is printed after the value.

ph

Prints the value on the top of the stack in base 16, without altering the stack. A newline is printed after the value.

Stack Control

c

Clears the stack, rendering it empty.

d

Duplicates the value on the top of the stack, pushing another copy of it. Thus, 4 d * p computes 4 squared and prints it.

r

Reverses the order of the top two values of the stack. This can also be accomplished with the sequence Sa Sb La Lb.

R

Pops the top-of-stack without printing it

Register(Stack)

As mentioned before, dc supports an hashmap ADT called register represented by an ordered pair (key, value). A register maps the key(represented by a single character) with a value(represented by an auxiliary stack and a private array). At least 256 registers are available. Below, you can see the supported operations on register's stack.

sr

Pop the value off the top of the (main) stack and store it into top of the stack of register r. This overwrite the top of the stack and does NOT follow the LIFO policy.

lr

Copy the value in top of the stack of register r and push it onto the main stack. The value 0 is retrieved if the register is uninitialized. This does not alter the contents of r.

Sr

Pop the value off the top of the (main) stack and push it onto the stack of register r. The previous of the register becomes inaccessible, thus it follows the LIFO policy.

Lr

Pop the value off the top of register r's stack and push it onto the main stack. The previous value in register r's stack, if any, is now accessible via the br command.

Register(Array)

Arrays support random access through an index. You can store a value in an array and retrieve it later.

:r

Will pop the top two values off the stack. The second-to-top value will be stored in the array r, indexed by the top-of-stack value.

;r

Pops the top-of-stack and uses it as an index into array r. The selected value is then pushed onto the stack.

Strings

dc has a limited ability to operate on strings as well as on numbers; the only things you can do with strings are print them and execute them as macros (which means that the content of a string can executed as a dc program). Any kind of stack can hold strings, and dc always knows whether any given object is a string or a number. Some commands such as arithmetic operations demand numbers as arguments and print errors if given strings. Other commands can accept either a number or a string; for example, the p command can accept either and prints the object according to its type.

[ characters ]

Makes a string containing characters (contained between balanced [ and ] characters), and pushes it on the stack. For example, [ Hello World ] P prints the string Hello World (with no newline).

x

Pops a value off the stack and executes it as a macro. Normally it should be a string; if it is a number, it is simply pushed back onto the stack. For example, [ 1 p ] x executes the macro 1 p which pushes 1 on the stack and prints 1 on a separate line.

Macros are most often stored in register's stacks; [ 1 p ] sa stores a macro to print 1 into register's stack a, and la x invokes this macro.

>r

Pops two values off the stack and compares them assuming they are numbers, executing the contents of register r as a macro if the original top-of-stack is greater. Thus, 1 2>a will invoke register a’s contents and 2 1>a will not.

=>r

Similar but invokes the macro if the original top-of-stack is greater or equal to the second-to-top.

<r

Similar but invokes the macro if the original top-of-stack is less.

<=r

Similar but invokes the macro if the original top-of-stack is less or equal to the second-to-top.

=r

Similar but invokes the macro if the two numbers popped are equal.

!=r

Similar but invokes the macro if the two numbers popped are not equal.

Status Inquiry

Z

Pops a value off the stack, calculates the number of digits it has (or number of characters, if it is a string) and pushes that number.

z

Pushes the current stack depth: the number of objects on the stack before the execution of the z command.

Miscellaneous

q

Exit with return code 0.

?

Reads a line from the terminal and executes it. This command allows a macro to request input from the user.

EXAMPLES

Below, there are some practical problems solved using dc.

  1. Evaluate (-5 + sqrt(25 - 16)) / 2:
-5 25 16 - v + 2 / p
  1. Evaluate sin(2pi)+cos(2pi):
2 pi * sin 2 pi * cos + p
  1. Loop from 1 to n, where n is a user-defined value:
[ p 1 + d lN >L ] sL # Print numbers from 1 through 'N'

[ Enter limit: ] P # Ask user for limit 'N'
? 1 + sN # Read from stdin
c 1 lL x # Clear the stack, add lower bound, load and execute macro
  1. Sum the first n natural numbers, where n is a user-defined value:
[ Enter bound: ] P ?
[ d 1 - d 1 <F + ] d sF x p
  1. Prints the first 20 values of n!:
[ la 1 + d sa * p la 20 >y ] sy
0 sa 1
ly x
  1. Computes the factorial of a given number:
[ ln 1 - sn ln la * sa ln 1 !=f ] sf
[ Enter value: ] P ? sn
ln sa
lf x
la p
  1. Computes the Greatest Common Divisor(GCD) between two user-defined numbers A and B:
[ Enter A: ] P R ?
[ Enter B: ] P R ?
[ d Sa r La % d 0 <a ] d sa x +
[ GCD(A,B)= ] P R p
  1. Computes the Least Common Multiple(LCM) between two user-defined numbers A and B:
[ Enter A: ] P R ? d sA
[ Enter B: ] P R ? d SA
[ d Sa r La % d 0 <a ] d sa x +
LA lA * r /
[ LCM(A,B)= ] P R p
  1. Find the roots of a quadratic equation
[ Enter A: ] P ? sA
[ Enter B: ] P ? sB
[ Enter C: ] P ? sC
lB 2 ^ 4 lA lC * * - v sD
lB -1 * lD - lA # NEGATIVE DELTA
2 * / sS # FIRST SOLUTION
lB -1 * lD + lA # POSITIVE DELTA
2 * / SS # SECOND SOLUTION
[ X: ] P R lS p
[ Y: ] P R LS lS p

AUTHORS

The original version of the dc command was written by Robert Morris and Lorinda Cherry. This version of dc is developed by Marco Cetica.

BUGS

If you encounter any kind of problem, email me at email@marcocetica.com or open an issue at https://github.com/ice-bit/dc.