« back to all changes in this revision
Viewing changes to doc/dc.texi
- browse files at revision 1
- compare with another revision
- download diff
- download tarball
- view history from revision 1
- Committer: Bazaar Package Importer
- Author(s): Dirk Eddelbuettel
- Date: 2002-04-13 11:33:49 UTC
- Revision ID: james.westby@ubuntu.com-20020413113349-hl2r1t730b91ov68
Tags: upstream-1.06
Import upstream version 1.06
- files added:
- Examples
- Test
- bc
- dc
- doc
- h
- lib
added
removed
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
Loggerhead is a web-based interface for Breezy
Version: 2.0.1