1dc(1) General Commands Manual dc(1)
2
6 dc - an arbitrary precision calculator
7
9 dc [-V] [--version] [-h] [--help]
10 [-e scriptexpression] [--expression=scriptexpression]
11 [-f scriptfile] [--file=scriptfile]
12 [file ...]
13
15 dc is a reverse-polish desk calculator which supports unlimited preci‐
16 sion arithmetic. It also allows you to define and call macros. Nor‐
17 mally dc reads from the standard input; if any command arguments are
18 given to it, they are filenames, and dc reads and executes the contents
19 of the files before reading from standard input. All normal output is
20 to standard output; all error output is to standard error.
21 A reverse-polish calculator stores numbers on a stack. Entering a num‐
23 ber pushes it on the stack. Arithmetic operations pop arguments off
24 the stack and push the results.
25 To enter a number in dc, type the digits (using upper case letters A
27 through F as "digits" when working with input bases greater than ten),
28 with an optional decimal point. Exponential notation is not supported.
29 To enter a negative number, begin the number with ``_''. ``-'' cannot
30 be used for this, as it is a binary operator for subtraction instead.
31 To enter two numbers in succession, separate them with spaces or new‐
32 lines. These have no meaning as commands.
33
35 dc may be invoked with the following command-line options:
36 -V
38 --version
40 Print out the version of dc that is being run and a copyright
41 notice, then exit.
42 -h
44 --help Print a usage message briefly summarizing these command-line
46 options and the bug-reporting address, then exit.
47 -e script
49 --expression=script
51 Add the commands in script to the set of commands to be run
52 while processing the input.
53 -f script-file
55 --file=script-file
57 Add the commands contained in the file script-file to the set of
58 commands to be run while processing the input.
59 If any command-line parameters remain after processing the above, these
61 parameters are interpreted as the names of input files to be processed.
62 A file name of - refers to the standard input stream. The standard
63 input will processed if no script files or expressions are specified.
64
66 p Prints the value on the top of the stack, without altering the
67 stack. A newline is printed after the value.
68 n Prints the value on the top of the stack, popping it off, and
70 does not print a newline after.
71 P Pops off the value on top of the stack. If it it a string, it
73 is simply printed without a trailing newline. Otherwise it is a
74 number, and the integer portion of its absolute value is printed
75 out as a "base (UCHAR_MAX+1)" byte stream. Assuming that
76 (UCHAR_MAX+1) is 256 (as it is on most machines with 8-bit
77 bytes), the sequence KSK0k1/_1Ss [ls*]Sxd0>x
78 [256~Ssd0<x]dsxxsx[q]Sq[Lsd0>qaPlxx] dsxxsx0sqLqsxLxLK+k could
79 also accomplish this function. (Much of the complexity of the
80 above native-dc code is due to the ~ computing the characters
81 backwards, and the desire to ensure that all registers wind up
82 back in their original states.)
83 f Prints the entire contents of the stack without altering any‐
85 thing. This is a good command to use if you are lost or want to
86 figure out what the effect of some command has been.
87
89 + Pops two values off the stack, adds them, and pushes the result.
90 The precision of the result is determined only by the values of
91 the arguments, and is enough to be exact.
92 - Pops two values, subtracts the first one popped from the second
94 one popped, and pushes the result.
95 * Pops two values, multiplies them, and pushes the result. The
97 number of fraction digits in the result depends on the current
98 precision value and the number of fraction digits in the two
99 arguments.
100 / Pops two values, divides the second one popped from the first
102 one popped, and pushes the result. The number of fraction dig‐
103 its is specified by the precision value.
104 % Pops two values, computes the remainder of the division that the
106 / command would do, and pushes that. The value computed is the
107 same as that computed by the sequence Sd dld/ Ld*- .
108 ~ Pops two values, divides the second one popped from the first
110 one popped. The quotient is pushed first, and the remainder is
111 pushed next. The number of fraction digits used in the division
112 is specified by the precision value. (The sequence SdSn lnld/
113 LnLd% could also accomplish this function, with slightly differ‐
114 ent error checking.)
115 ^ Pops two values and exponentiates, using the first value popped
117 as the exponent and the second popped as the base. The fraction
118 part of the exponent is ignored. The precision value specifies
119 the number of fraction digits in the result.
120 | Pops three values and computes a modular exponentiation. The
122 first value popped is used as the reduction modulus; this value
123 must be a non-zero number, and should be an integer. The second
124 popped is used as the exponent; this value must be a non-nega‐
125 tive number, and any fractional part of this exponent will be
126 ignored. The third value popped is the base which gets exponen‐
127 tiated, which should be an integer. For small integers this is
128 like the sequence Sm^Lm%, but, unlike ^, this command will work
129 with arbitrarily large exponents.
130 v Pops one value, computes its square root, and pushes that. The
132 maximum of the precision value and the precision of the argument
133 is used to determine the number of fraction digits in the
134 result.
135 Most arithmetic operations are affected by the ``precision value'',
137 which you can set with the k command. The default precision value is
138 zero, which means that all arithmetic except for addition and subtrac‐
139 tion produces integer results.
140
142 c Clears the stack, rendering it empty.
143 d Duplicates the value on the top of the stack, pushing another
145 copy of it. Thus, ``4d*p'' computes 4 squared and prints it.
146 r Reverses the order of (swaps) the top two values on the stack.
148 (This can also be accomplished with the sequence SaSbLaLb.)
149 R Pops the top-of-stack as an integer n. Cyclically rotates the
151 top n items on the updated stack. If n is positive, then the
152 rotation direction will make the topmost element the second-from
153 top; if n is negative, then the rotation will make the topmost
154 element the n-th element from the top. If the stack depth is
155 less than n, then the entire stack is rotated (in the appropri‐
156 ate direction), without any error being reported.
157
159 dc provides at least 256 memory registers, each named by a single char‐
160 acter. You can store a number or a string in a register and retrieve
161 it later.
162 sr Pop the value off the top of the stack and store it into regis‐
164 ter r.
165 lr Copy the value in register r and push it onto the stack. The
167 value 0 is retrieved if the register is uninitialized. This
168 does not alter the contents of r.
169 Each register also contains its own stack. The current register value
171 is the top of the register's stack.
172 Sr Pop the value off the top of the (main) stack and push it onto
174 the stack of register r. The previous value of the register
175 becomes inaccessible.
176 Lr Pop the value off the top of register r's stack and push it onto
178 the main stack. The previous value in register r's stack, if
179 any, is now accessible via the lr command.
180
182 dc has three parameters that control its operation: the precision, the
183 input radix, and the output radix. The precision specifies the number
184 of fraction digits to keep in the result of most arithmetic operations.
185 The input radix controls the interpretation of numbers typed in; all
186 numbers typed in use this radix. The output radix is used for printing
187 numbers.
188 The input and output radices are separate parameters; you can make them
190 unequal, which can be useful or confusing. The input radix must be
191 between 2 and 16 inclusive. The output radix must be at least 2. The
192 precision must be zero or greater. The precision is always measured in
193 decimal digits, regardless of the current input or output radix.
194 i Pops the value off the top of the stack and uses it to set the
196 input radix.
197 o Pops the value off the top of the stack and uses it to set the
199 output radix.
200 k Pops the value off the top of the stack and uses it to set the
202 precision.
203 I Pushes the current input radix on the stack.
205 O Pushes the current output radix on the stack.
207 K Pushes the current precision on the stack.
209
211 dc has a limited ability to operate on strings as well as on numbers;
212 the only things you can do with strings are print them and execute them
213 as macros (which means that the contents of the string are processed as
214 dc commands). All registers and the stack can hold strings, and dc
215 always knows whether any given object is a string or a number. Some
216 commands such as arithmetic operations demand numbers as arguments and
217 print errors if given strings. Other commands can accept either a num‐
218 ber or a string; for example, the p command can accept either and
219 prints the object according to its type.
220 [characters]
222 Makes a string containing characters (contained between balanced
223 [ and ] characters), and pushes it on the stack. For example,
224 [foo]P prints the characters foo (with no newline).
225 a The top-of-stack is popped. If it was a number, then the low-
227 order byte of this number is converted into a string and pushed
228 onto the stack. Otherwise the top-of-stack was a string, and
229 the first character of that string is pushed back.
230 x Pops a value off the stack and executes it as a macro. Normally
232 it should be a string; if it is a number, it is simply pushed
233 back onto the stack. For example, [1p]x executes the macro 1p
234 which pushes 1 on the stack and prints 1 on a separate line.
235 Macros are most often stored in registers; [1p]sa stores a macro to
237 print 1 into register a, and lax invokes this macro.
238 >r Pops two values off the stack and compares them assuming they
240 are numbers, executing the contents of register r as a macro if
241 the original top-of-stack is greater. Thus, 1 2>a will invoke
242 register a's contents and 2 1>a will not.
243 !>r Similar but invokes the macro if the original top-of-stack is
245 not greater than (less than or equal to) what was the second-to-
246 top.
247 <r Similar but invokes the macro if the original top-of-stack is
249 less.
250 !<r Similar but invokes the macro if the original top-of-stack is
252 not less than (greater than or equal to) what was the second-to-
253 top.
254 =r Similar but invokes the macro if the two numbers popped are
256 equal.
257 !=r Similar but invokes the macro if the two numbers popped are not
259 equal.
260 ? Reads a line from the terminal and executes it. This command
262 allows a macro to request input from the user.
263 q exits from a macro and also from the macro which invoked it. If
265 called from the top level, or from a macro which was called
266 directly from the top level, the q command will cause dc to
267 exit.
268 Q Pops a value off the stack and uses it as a count of levels of
270 macro execution to be exited. Thus, 3Q exits three levels. The
271 Q command will never cause dc to exit.
272
274 Z Pops a value off the stack, calculates the number of decimal
275 digits it has (or number of characters, if it is a string) and
276 pushes that number. The digit count for a number does not
277 include any leading zeros, even if those appear to the right of
278 the radix point.
279 X Pops a value off the stack, calculates the number of fraction
281 digits it has, and pushes that number. For a string, the value
282 pushed is 0.
283 z Pushes the current stack depth: the number of objects on the
285 stack before the execution of the z command.
286
288 ! Will run the rest of the line as a system command. Note that
289 parsing of the !<, !=, and !> commands take precedence, so if
290 you want to run a command starting with <, =, or > you will need
291 to add a space after the !.
292 # Will interpret the rest of the line as a comment.
294 :r Will pop the top two values off of the stack. The old second-
296 to-top value will be stored in the array r, indexed by the old
297 top-of-stack value.
298 ;r Pops the top-of-stack and uses it as an index into the array r.
300 The selected value is then pushed onto the stack.
301 Note that each stacked instance of a register has its own array associ‐
303 ated with it. Thus 1 0:a 0Sa 2 0:a La 0;ap will print 1, because the 2
304 was stored in an instance of 0:a that was later popped.
305
307 Email bug reports to bug-dc@gnu.org.
308GNU Project 2008-05-22 dc(1)