* Sync comment with code's reality.
[dragonfly.git] / contrib / bc / doc / dc.texi
1 \input texinfo  @c -*-texinfo-*-
2 @c %**start of header
3 @setfilename dc.info
4 @settitle dc, an arbitrary precision calculator
5 @c %**end of header
6
7 @c This file has the new style title page commands.
8 @c Run `makeinfo' rather than `texinfo-format-buffer'.
9
10 @c smallbook
11
12 @c tex
13 @c \overfullrule=0pt
14 @c end tex
15
16 @c Combine indices.
17 @synindex cp fn
18 @syncodeindex vr fn
19 @syncodeindex ky fn
20 @syncodeindex pg fn
21 @syncodeindex tp fn
22
23 @ifinfo
24 @direntry
25 * dc: (dc).                   Arbritrary precision RPN ``Desktop Calculator''.
26 @end direntry
27 This file documents @sc{dc}, an arbitrary precision calculator.
28
29 Published by the Free Software Foundation, Inc.
30 59 Temple Place, Suite 330
31 Boston, MA 02111 USA
32
33 Copyright (C) 1984, 1994, 1997, 1998, 2000 Free Software Foundation, Inc.
34
35 Permission is granted to make and distribute verbatim copies of
36 this manual provided the copyright notice and this permission notice
37 are preserved on all copies.
38
39 @ignore
40 Permission is granted to process this file through TeX and print the
41 results, provided the printed document carries copying permission
42 notice identical to this one except for the removal of this paragraph
43 (this paragraph not being relevant to the printed manual).
44
45 @end ignore
46 Permission is granted to copy and distribute modified versions of this
47 manual under the conditions for verbatim copying, provided that the entire
48 resulting derived work is distributed under the terms of a permission
49 notice identical to this one.
50
51 Permission is granted to copy and distribute translations of this manual
52 into another language, under the above conditions for modified versions,
53 except that this permission notice may be stated in a translation approved
54 by the Foundation.
55 @end ifinfo
56
57 @setchapternewpage off
58
59 @titlepage
60 @title dc, an arbitrary precision calculator
61
62 @author by Ken Pizzini
63 @author original manual by Richard Stallman
64 @page
65 @vskip 0pt plus 1filll
66 Copyright @copyright{} 1994, 1997, 1998 Free Software Foundation, Inc.
67
68 @sp 2
69 Published by the Free Software Foundation, @*
70 59 Temple Place, Suite 330 @*
71 Boston, MA 02111 USA
72
73 Permission is granted to make and distribute verbatim copies of
74 this manual provided the copyright notice and this permission notice
75 are preserved on all copies.
76
77 Permission is granted to copy and distribute modified versions of this
78 manual under the conditions for verbatim copying, provided that the entire
79 resulting derived work is distributed under the terms of a permission
80 notice identical to this one.
81
82 Permission is granted to copy and distribute translations of this manual
83 into another language, under the above conditions for modified versions,
84 except that this permission notice may be stated in a translation approved
85 by the Foundation.
86
87 @end titlepage
88 @page
89
90 @node Top, Introduction, (dir), (dir)
91
92 @menu
93 * Introduction::                Introduction
94 * Invocation::                  Invocation
95 * Printing Commands::           Printing Commands
96 * Arithmetic::                  Arithmetic
97 * Stack Control::               Stack Control
98 * Registers::                   Registers
99 * Parameters::                  Parameters
100 * Strings::                     Strings
101 * Status Inquiry::              Status Inquiry
102 * Miscellaneous::               Other commands
103 * Reporting bugs::              Reporting bugs
104 @end menu
105
106 @node Introduction, Invocation, Top, Top
107 @comment  node-name,  next,  previous,  up
108 @chapter Introduction
109
110 @sc{dc} is a reverse-polish desk calculator
111 which supports unlimited precision arithmetic.
112 It also allows you to define and call macros.
113 Normally @sc{dc} reads from the standard input;
114 if any command arguments are given to it, they are filenames,
115 and @sc{dc} reads and executes the contents of the files
116 instead of reading from standard input.
117 All normal output is to standard output;
118 all error messages are written to standard error.
119
120 To exit, use @samp{q}.
121 @kbd{C-c} does not exit;
122 it is used to abort macros that are looping, etc.
123 (Currently this is not true; @kbd{C-c} does exit.)
124
125 A reverse-polish calculator stores numbers on a stack.
126 Entering a number pushes it on the stack.
127 Arithmetic operations pop arguments off the stack and push the results.
128
129 To enter a number in @sc{dc}, type the digits,
130 with an optional decimal point.
131 Exponential notation is not supported.
132 To enter a negative number, begin the number with @samp{_}.
133 @samp{-} cannot be used for this, as it is a binary operator
134 for subtraction instead.
135 To enter two numbers in succession,
136 separate them with spaces or newlines.
137 These have no meaning as commands.
138
139 @node Invocation, Printing Commands, Introduction, Top
140 @chapter Invocation
141
142 @sc{dc} may be invoked with the following command-line options:
143 @table @samp
144
145 @item -e @var{expr}
146 @item --expression=@var{expr}
147 Evaluate @var{expr} as @sc{dc} commands.
148
149 @item -f @var{file}
150 @item --file=@var{file}
151 Read and evaluate @sc{dc} commands from @var{file}.
152
153 @item -h
154 @item --help
155 Print a usage message summarizing the command-line options, then exit.
156
157 @item -V
158 @item --version
159 Print the version information for this program, then exit.
160 @end table
161
162 If any command-line parameters remain after processing the options,
163 these parameters are interpreted as additional @var{file}s whose
164 contents are read and evaluated.
165 A file name of @code{-} refers to the standard input stream.
166 If no @code{-e} option was specified, and no files were specified,
167 then the standard input will be read for commands to evaluate.
168
169 @node Printing Commands, Arithmetic, Invocation, Top
170 @chapter Printing Commands
171
172 @table @samp
173 @item p
174 Prints the value on the top of the stack,
175 without altering the stack.
176 A newline is printed after the value.
177
178 @item n
179 Prints the value on the top of the stack, popping it off,
180 and does not print a newline after.
181 (This command is a GNU extension.)
182
183 @item P
184 Pops off the value on top of the stack.
185 If it it a string, it is simply printed without a trailing newline.
186 Otherwise it is a number, and the integer portion of its absolute
187 value is printed out as a "base (UCHAR_MAX+1)" byte stream.
188 Assuming that (UCHAR_MAX+1) is 256
189 (as it is on most machines with 8-bit bytes),
190 the sequence
191 @code{KSK 0k1/ [_1*]sx d0>x [256~aPd0<x]dsxx sxLKk}
192 could also accomplish this function,
193 except for the side-effect of clobbering the x register.
194 (Details of the behavior with a number are a GNU extension.)
195
196 @item f
197 Prints the entire contents of the stack
198 @c and the contents of all of the registers,
199 without altering anything.
200 This is a good command to use if you are lost or want
201 to figure out what the effect of some command has been.
202 @end table
203
204 @node Arithmetic, Stack Control, Printing Commands, Top
205 @chapter Arithmetic
206
207 @table @samp
208 @item +
209 Pops two values off the stack, adds them, and pushes the result.
210 The precision of the result is determined only
211 by the values of the arguments, and is enough to be exact.
212
213 @item -
214 Pops two values, subtracts the first one popped
215 from the second one popped, and pushes the result.
216
217 @item *
218 Pops two values, multiplies them, and pushes the result.
219 The number of fraction digits in the result is the largest of
220 the precision value,
221 the number of fraction digits in the multiplier,
222 or the number of fraction digits in the multiplicand;
223 but in no event exceeding the number of digits required for
224 an exact result.
225
226 @item /
227 Pops two values, divides the second one popped
228 from the first one popped, and pushes the result.
229 The number of fraction digits is specified by the precision value.
230
231 @item %
232 Pops two values,
233 computes the remainder of the division that
234 the @samp{/} command would do,
235 and pushes that.
236 The value computed is the same as that computed by
237 the sequence @code{Sd dld/ Ld*-} .
238
239 @item ~
240 Pops two values,
241 divides the second one popped from the first one popped.
242 The quotient is pushed first, and the remainder is pushed next.
243 The number of fraction digits used in the division
244 is specified by the precision value.
245 (The sequence @code{SdSn lnld/ LnLd%} could also accomplish
246 this function, with slightly different error checking.)
247 (This command is a GNU extension.)
248
249 @item ^
250 Pops two values and exponentiates,
251 using the first value popped as the exponent
252 and the second popped as the base.
253 The fraction part of the exponent is ignored.
254 The precision value specifies the number of fraction
255 digits in the result.
256
257 @item |
258 Pops three values and computes a modular exponentiation.
259 The first value popped is used as the reduction modulus;
260 this value must be a non-zero number,
261 and the result may not be accurate if the modulus
262 is not an integer.
263 The second popped is used as the exponent;
264 this value must be a non-negative number,
265 and any fractional part of this exponent will be ignored.
266 The third value popped is the base which gets exponentiated,
267 which should be an integer.
268 For small integers this is like the sequence @code{Sm^Lm%},
269 but, unlike @code{^}, this command will work with arbritrarily large exponents.
270 (This command is a GNU extension.)
271
272 @item v
273 Pops one value, computes its square root, and pushes that.
274 The precision value specifies the number of fraction digits
275 in the result.
276 @end table
277
278 Most arithmetic operations are affected by the @emph{precision value},
279 which you can set with the @samp{k} command.
280 The default precision value is zero,
281 which means that all arithmetic except for
282 addition and subtraction produces integer results.
283
284 @node Stack Control, Registers, Arithmetic, Top
285 @chapter Stack Control
286
287 @table @samp
288 @item c
289 Clears the stack, rendering it empty.
290
291 @item d
292 Duplicates the value on the top of the stack,
293 pushing another copy of it.
294 Thus, @samp{4d*p} computes 4 squared and prints it.
295
296 @item r
297 Reverses the order of (swaps) the top two values on the stack.
298 (This command is a GNU extension.)
299 @end table
300
301 @node Registers, Parameters, Stack Control, Top
302 @chapter Registers
303
304 @sc{dc} provides at least 256 memory registers,
305 each named by a single character.
306 You can store a number in a register and retrieve it later.
307
308 @table @samp
309 @item s@var{r}
310 Pop the value off the top of the stack and
311 store it into register @var{r}.
312
313 @item l@var{r}
314 Copy the value in register @var{r},
315 and push it onto the stack.
316 This does not alter the contents of @var{r}.
317
318 Each register also contains its own stack.
319 The current register value is the top of the register's stack.
320
321 @item S@var{r}
322 Pop the value off the top of the (main) stack and
323 push it onto the stack of register @var{r}.
324 The previous value of the register becomes inaccessible.
325
326 @item L@var{r}
327 Pop the value off the top of register @var{r}'s stack
328 and push it onto the main stack.
329 The previous value in register @var{r}'s stack, if any,
330 is now accessible via the @samp{l@var{r}} command.
331 @end table
332 @c 
333 @c The @samp{f} command prints a list of all registers that have contents
334 @c stored in them, together with their contents.
335 @c Only the current contents of each register (the top of its stack)
336 @c is printed.
337
338 @node Parameters, Strings, Registers, Top
339 @chapter Parameters
340
341 @sc{dc} has three parameters that control its operation:
342 the precision, the input radix, and the output radix.
343 The precision specifies the number of fraction digits
344 to keep in the result of most arithmetic operations.
345 The input radix controls the interpretation of numbers typed in;
346 @emph{all} numbers typed in use this radix.
347 The output radix is used for printing numbers.
348
349 The input and output radices are separate parameters;
350 you can make them unequal, which can be useful or confusing.
351 The input radix must be between 2 and 16 inclusive.
352 The output radix must be at least 2.
353 The precision must be zero or greater.
354 The precision is always measured in decimal digits,
355 regardless of the current input or output radix.
356
357 @table @samp
358 @item i
359 Pops the value off the top of the stack
360 and uses it to set the input radix.
361
362 @item o
363 Pops the value off the top of the stack
364 and uses it to set the output radix.
365
366 @item k
367 Pops the value off the top of the stack
368 and uses it to set the precision.
369
370 @item I
371 Pushes the current input radix on the stack.
372
373 @item O
374 Pushes the current output radix on the stack.
375
376 @item K
377 Pushes the current precision on the stack.
378
379 @end table
380
381 @node Strings, Status Inquiry, Parameters, Top
382 @chapter Strings
383
384 @sc{dc} can operate on strings as well as on numbers.
385 The only things you can do with strings are print them
386 and execute them as macros
387 (which means that the contents of the string are processed as @sc{dc} commands).
388 Both registers and the stack can hold strings,
389 and @sc{dc} always knows whether any given object is a string or a number.
390 Some commands such as arithmetic operations demand numbers
391 as arguments and print errors if given strings.
392 Other commands can accept either a number or a string;
393 for example, the @samp{p} command can accept either and prints the object
394 according to its type.
395
396 @table @samp
397 @item [@var{characters}]
398 Makes a string containing @var{characters} and pushes it on the stack.
399 For example, @samp{[foo]P} prints the characters @samp{foo}
400 (with no newline).
401
402 @item a
403 The mnemonic for this is somewhat erroneous: asciify.
404 The top-of-stack is popped.
405 If it was a number, then the low-order byte of this number
406 is converted into a string and pushed onto the stack.
407 Otherwise the top-of-stack was a string,
408 and the first character of that string is pushed back.
409 (This command is a GNU extension.)
410
411 @item x
412 Pops a value off the stack and executes it as a macro.
413 Normally it should be a string;
414 if it is a number, it is simply pushed back onto the stack.
415 For example, @samp{[1p]x} executes the macro @samp{1p},
416 which pushes 1 on the stack and prints @samp{1} on a separate line.
417
418 Macros are most often stored in registers;
419 @samp{[1p]sa} stores a macro to print @samp{1} into register @samp{a},
420 and @samp{lax} invokes the macro.
421
422 @item >@var{r}
423 Pops two values off the stack and compares them
424 assuming they are numbers,
425 executing the contents of register @var{r} as a macro
426 if the original top-of-stack is greater.
427 Thus, @samp{1 2>a} will invoke register @samp{a}'s contents
428 and @samp{2 1>a} will not.
429
430 @item !>@var{r}
431 Similar but invokes the macro if the original top-of-stack is not greater
432 (is less than or equal to) what was the second-to-top.
433
434 @item <@var{r}
435 Similar but invokes the macro if the original top-of-stack is less.
436
437 @item !<@var{r}
438 Similar but invokes the macro if the original top-of-stack is not less
439 (is greater than or equal to) what was the second-to-top.
440
441 @item =@var{r}
442 Similar but invokes the macro if the two numbers popped are equal.
443 @c This can also be validly used to compare two strings for equality.
444
445 @item !=@var{r}
446 Similar but invokes the macro if the two numbers popped are not equal.
447 @c This can also be validly used to compare two strings for equality.
448
449 @item ?
450 Reads a line from the terminal and executes it.
451 This command allows a macro to request input from the user.
452
453 @item q
454 During the execution of a macro,
455 this command exits from the macro and also from the macro which invoked it.
456 If called from the top level,
457 or from a macro which was called directly from the top level,
458 the @samp{q} command will cause @sc{dc} to exit.
459
460 @item Q
461 Pops a value off the stack and uses it as a count
462 of levels of macro execution to be exited.
463 Thus, @samp{3Q} exits three levels.
464 @end table
465
466 @node Status Inquiry, Miscellaneous, Strings, Top
467 @chapter Status Inquiry
468
469 @table @samp
470 @item Z
471 Pops a value off the stack,
472 calculates the number of digits it has
473 (or number of characters, if it is a string)
474 and pushes that number.
475
476 @item X
477 Pops a value off the stack,
478 calculates the number of fraction digits it has,
479 and pushes that number.
480 For a string, the value pushed is
481 @c -1.
482 0.
483
484 @item z
485 Pushes the current stack depth:
486 the number of objects on the stack
487 before the execution of the @samp{z} command.
488 @end table
489
490 @node Miscellaneous, Reporting bugs, Status Inquiry, Top
491 @chapter Miscellaneous
492
493 @table @samp
494 @item !
495 Will run the rest of the line as a system command.
496 Note that parsing of the !<, !=, and !> commands take precidence,
497 so if you want to run a command starting with <, =, or > you will
498 need to add a space after the !.
499
500 @item #
501 Will interpret the rest of the line as a comment.
502 (This command is a GNU extension.)
503
504 @item :@var{r}
505 Will pop the top two values off of the stack.
506 The old second-to-top value will be stored in the array @var{r},
507 indexed by the old top-of-stack value.
508
509 @item ;@var{r}
510 Pops the top-of-stack and uses it as an index into
511 the array @var{r}.
512 The selected value is then pushed onto the stack.
513 @end table
514
515 Note that each stacked instance of a register has its own
516 array associated with it.
517 Thus @samp{1 @var{0:a} 0S@var{a} 2 @var{0:a} L@var{a} @var{0;a}p}
518 will print 1, because the 2 was stored in an instance of @var{0:a}
519 that was later popped.
520
521 @node Reporting bugs,  , Miscellaneous, Top
522 @chapter Reporting bugs
523
524 Email bug reports to @email{bug-dc@@gnu.org}.
525 @contents
526 @bye