Commit | Line | Data |
---|---|---|
d3f89168 JH |
1 | .TH DC 1 "03 Aug 1993" "GNU Project" |
2 | .SH NAME | |
3 | dc, An Arbitrary Precision Calculator | |
4 | .SH SYNOPSIS | |
5 | .B dc | |
6 | .SH DESCRIPTION | |
7 | .PP | |
8 | DC is a reverse-polish desk calculator which supports unlimited | |
9 | precision arithmetic. It also allows you to define and call macros. | |
10 | Normally DC reads from the standard input; if any command arguments | |
11 | are given to it, they are filenames, and DC reads and executes the | |
12 | contents of the files before reading from standard input. All output | |
13 | is to standard output. | |
14 | ||
15 | A reverse-polish calculator stores numbers on a stack. Entering a | |
16 | number pushes it on the stack. Arithmetic operations pop arguments off | |
17 | the stack and push the results. | |
18 | ||
19 | To enter a number in DC, type the digits, with an optional decimal | |
20 | point. Exponential notation is not supported. To enter a negative | |
21 | number, begin the number with `_'. `-' cannot be used for this, as it | |
22 | is a binary operator for subtraction instead. To enter two numbers in | |
23 | succession, separate them with spaces or newlines. These have no | |
24 | meaning as commands. | |
25 | .PD | |
26 | .SH "Printing Commands" | |
27 | .PP | |
28 | .B p | |
29 | Prints the value on the top of the stack, | |
30 | without altering the stack. A newline is printed | |
31 | after the value. | |
32 | .PP | |
33 | .B P | |
34 | Prints the value on the top of the stack, | |
35 | popping it off, and does not print a newline after. | |
36 | .PP | |
37 | .B f | |
38 | Prints the entire contents of the stack | |
39 | and the contents of all of the registers, | |
40 | without altering anything. This is a good command | |
41 | to use if you are lost or want to figure out | |
42 | what the effect of some command has been. | |
43 | .PD | |
44 | .SH "Arithmetic" | |
45 | .PP | |
46 | .B + | |
47 | Pops two values off the stack, adds them, | |
48 | and pushes the result. The precision of the result | |
49 | is determined only by the values of the arguments, | |
50 | and is enough to be exact. | |
51 | .PP | |
52 | .B - | |
53 | Pops two values, subtracts the first one popped | |
54 | from the second one popped, and pushes the result. | |
55 | .PP | |
56 | .B * | |
57 | Pops two values, multiplies them, and pushes the result. | |
58 | The number of fraction digits in the result is controlled | |
59 | by the current precision flag (see below) and does not | |
60 | depend on the values being multiplied. | |
61 | .PP | |
62 | .B / | |
63 | Pops two values, divides the second one popped from | |
64 | the first one popped, and pushes the result. | |
65 | The number of fraction digits is specified by the precision flag. | |
66 | .PP | |
67 | .B % | |
68 | Pops two values, computes the remainder of the division | |
69 | that the \fB/\fR command would do, and pushes that. | |
70 | The division is done with as many fraction digits | |
71 | as the precision flag specifies, and the remainder | |
72 | is also computed with that many fraction digits. | |
73 | .PP | |
74 | .B ^ | |
75 | Pops two values and exponentiates, using the first | |
76 | value popped as the exponent and the second popped as the base. | |
77 | The fraction part of the exponent is ignored. | |
78 | The precision flag specifies the number of fraction | |
79 | digits in the result. | |
80 | .PP | |
81 | .B v | |
82 | Pops one value, computes its square root, and pushes that. | |
83 | The precision flag specifies the number of fraction digits | |
84 | in the result. | |
85 | .PP | |
86 | Most arithmetic operations are affected by the "precision flag", | |
87 | which you can set with the | |
88 | .BR k | |
89 | command. The default precision | |
90 | value is zero, which means that all arithmetic except for | |
91 | addition and subtraction produces integer results. | |
92 | .PP | |
93 | The remainder operation | |
94 | .BR % | |
95 | requires some explanation: applied to | |
96 | arguments `a' and `b' it produces `a - (b * (a / b))', | |
97 | where `a / b' is computed in the current precision. | |
98 | .PP | |
99 | .SH "Stack Control" | |
100 | .PP | |
101 | .B c | |
102 | Clears the stack, rendering it empty. | |
103 | .PP | |
104 | .B d | |
105 | Duplicates the value on the top of the stack, | |
106 | pushing another copy of it. Thus, | |
107 | `4d*p' computes 4 squared and prints it. | |
108 | .SH "Registers" | |
109 | .PP | |
110 | DC provides 128 memory registers, each named by a single | |
111 | ASCII character. You can store a number in a register | |
112 | and retrieve it later. | |
113 | .PP | |
114 | .B s\fIr\fR | |
115 | Pop the value off the top of the stack and store | |
116 | it into register \fIr\fR. | |
117 | .PP | |
118 | .B l\fIr\fR | |
119 | Copy the value in register \fIr\fR and push it onto the stack. This | |
120 | does not alter the contents of \fIr\fR. | |
121 | .PP | |
122 | Each register also contains its own stack. The current | |
123 | register value is the top of the register's stack. | |
124 | .PP | |
125 | .B S\fIr\fR | |
126 | Pop the value off the top of the (main) stack and | |
127 | push it onto the stack of register \fIr\fR. | |
128 | The previous value of the register becomes inaccessible. | |
129 | .PP | |
130 | .B L\fIr\fR | |
131 | Pop the value off the top of register \fIr\fR's stack | |
132 | and push it onto the main stack. The previous value | |
133 | in register \fIr\fR's stack, if any, is now accessible | |
134 | via the | |
135 | .BR Ir | |
136 | command. | |
137 | .PP | |
138 | The | |
139 | .BR f | |
140 | command prints a list of all registers that have contents | |
141 | stored in them, together with their contents. Only the | |
142 | current contents of each register (the top of its stack) | |
143 | is printed. | |
144 | .PP | |
145 | .SH "Parameters" | |
146 | .PP | |
147 | DC has three parameters that control its operation: the precision, the | |
148 | input radix, and the output radix. The precision specifies the number | |
149 | of fraction digits to keep in the result of most arithmetic operations. | |
150 | The input radix controls the interpretation of numbers typed in; | |
151 | allnumbers typed in use this radix. The output radix is used | |
152 | for printing numbers. | |
153 | .PP | |
154 | The input and output radices are separate parameters; you can make them | |
155 | unequal, which can be useful or confusing. Each radix must be between 2 | |
156 | and 36 inclusive. The precision must be zero or greater. The precision | |
157 | is always measured in decimal digits, regardless of the current input or | |
158 | output radix. | |
159 | .PP | |
160 | .B i | |
161 | Pops the value off the top of the stack | |
162 | and uses it to set the input radix. | |
163 | .PP | |
164 | .B o | |
165 | .PP | |
166 | .B k | |
167 | Similarly set the output radix and the precision. | |
168 | .PP | |
169 | .B I | |
170 | Pushes the current input radix on the stack. | |
171 | .PP | |
172 | .B O | |
173 | .PP | |
174 | .B K | |
175 | Similarly push the current output radix and the current precision. | |
176 | .PP | |
177 | .SH "Strings" | |
178 | .PP | |
179 | DC can operate on strings as well as on numbers. The only things you | |
180 | can do with strings are print them and execute them as macros (which | |
181 | means that the contents of the string are processed as DC commands). | |
182 | Both registers and the stack can hold strings, and DC always knows | |
183 | whether any given object is a string or a number. Some commands such as | |
184 | arithmetic operations demand numbers as arguments and print errors if | |
185 | given strings. Other commands can accept either a number or a string; | |
186 | for example, the | |
187 | .BR p | |
188 | command can accept either and prints the object | |
189 | according to its type. | |
190 | .PP | |
191 | .B [characters] | |
192 | Makes a string containing | |
193 | .BR characters | |
194 | and pushes it | |
195 | on the stack. For example, | |
196 | .BR [foo]p | |
197 | prints the | |
198 | characters \fBfoo\fR (with no newline). | |
199 | .PP | |
200 | .B x | |
201 | Pops a value off the stack and executes it as a macro. | |
202 | Normally it should be a string; if it is a number, | |
203 | it is simply pushed back onto the stack. | |
204 | For example, | |
205 | .BR [1p]x | |
206 | executes the macro | |
207 | .BR 1p | |
208 | which pushes \fB1\fR on the stack and prints \fB1\fR | |
209 | on a separate line. | |
210 | .PP | |
211 | Macros are most often stored in registers; | |
212 | \fB[1p]sa\fR stores a macro to print \fB1\fR into register \fBa\fR, | |
213 | and \fBlax\fR invokes the macro. | |
214 | .PP | |
215 | .B >\fIr\fR | |
216 | Pops two values off the stack and compares them | |
217 | assuming they are numbers, executing the contents | |
218 | of register \fIr\fR as a macro if the original top-of-stack | |
219 | is greater. Thus, \fB1 2>a\fR will invoke register \fBa\fR's contents | |
220 | and \fB2 1>a\fR will not. | |
221 | .PP | |
222 | .B <\fIr\fB | |
223 | Similar but invokes the macro if the original top-of-stack | |
224 | is less. | |
225 | .PP | |
226 | .B =\fIr\fR | |
227 | Similar but invokes the macro if the two numbers popped | |
228 | are equal. This can also be validly used to compare two | |
229 | strings for equality. | |
230 | .PP | |
231 | .B ? | |
232 | Reads a line from the terminal and executes it. | |
233 | This command allows a macro to request input from the user. | |
234 | .PP | |
235 | .B q | |
236 | During the execution of a macro, this comand | |
237 | does not exit DC. Instead, it exits from that | |
238 | macro and also from the macro which invoked it (if any). | |
239 | .PP | |
240 | .B Q | |
241 | Pops a value off the stack and uses it as a count | |
242 | of levels of macro execution to be exited. Thus, | |
243 | \fB3Q\fR exits three levels. | |
244 | .SH "Status Inquiry" | |
245 | .PP | |
246 | .B Z | |
247 | Pops a value off the stack, calculates the number of | |
248 | digits it has (or number of characters, if it is a string) | |
249 | and pushes that number. | |
250 | .PP | |
251 | .B X | |
252 | Pops a value off the stack, calculates the number of | |
253 | fraction digits it has, and pushes that number. | |
254 | For a string, the value pushed is -1. | |
255 | .PP | |
256 | .B z | |
257 | Pushes the current stack depth; the number of | |
258 | objects on the stack before the execution of the \fBz\fR command. | |
259 | .PP | |
260 | .B I | |
261 | Pushes the current value of the input radix. | |
262 | .PP | |
263 | .B O | |
264 | Pushes the current value of the output radix. | |
265 | .PP | |
266 | .B K | |
267 | Pushes the current value of the precision. | |
268 | .SH "Notes" | |
269 | .PP | |
270 | The \fB:\fR and \fB;\fR commands of the Unix DC program are | |
271 | not supported, as the documentation does not say what they do. | |
272 | The \fB!\fR command is not supported, but will be supported | |
273 | as soon as a library for executing a line as a command exists. | |
274 | .SH BUGS | |
275 | .PP | |
276 | Email bug reports to | |
277 | .BR bug-gnu-utils@prep.ai.mit.edu . | |
278 | Be sure to include the word ``dc'' somewhere in the ``Subject:'' field. |