diff options
Diffstat (limited to 'doc/dc.info')
| -rw-r--r-- | doc/dc.info | 255 |
1 files changed, 156 insertions, 99 deletions
diff --git a/doc/dc.info b/doc/dc.info index 050a6b3..c2a6532 100644 --- a/doc/dc.info +++ b/doc/dc.info @@ -1,32 +1,41 @@ -This is dc.info, produced by makeinfo version 4.0 from dc.texi. +This is ../../doc/dc.info, produced by makeinfo version 4.8 from +../../doc/dc.texi. START-INFO-DIR-ENTRY -* dc: (dc). Arbritrary precision RPN "Desktop Calculator". +* dc: (dc). Arbitrary precision RPN "Desktop Calculator". END-INFO-DIR-ENTRY - This file documents DC, an arbitrary precision calculator. - Published by the Free Software Foundation, Inc. 59 Temple Place, -Suite 330 Boston, MA 02111 USA + This manual documents version 1.4.1 of GNU `dc', an arbitrary +precision calculator. - Copyright (C) 1984, 1994, 1997, 1998, 2000 Free Software Foundation, -Inc. + Copyright (C) 1984, 1994, 1997, 1998, 2000, 2005, 2006, 2008, 2013, +2016 Free Software Foundation, Inc. - Permission is granted to make and distribute verbatim copies of this -manual provided the copyright notice and this permission notice are -preserved on all copies. + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.2 or any later version published by the Free Software + Foundation; with no Invariant Sections, with no Front-Cover Texts, + and with no Back-Cover Texts. A copy of the license can be found + at `http://www.gnu.org/licenses/fdl.html' . - Permission is granted to copy and distribute modified versions of -this manual under the conditions for verbatim copying, provided that -the entire resulting derived work is distributed under the terms of a -permission notice identical to this one. + +File: dc.info, Node: Top, Next: Introduction, Up: (dir) - Permission is granted to copy and distribute translations of this -manual into another language, under the above conditions for modified -versions, except that this permission notice may be stated in a -translation approved by the Foundation. +GNU dc +****** - -File: dc.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) +This manual documents version 1.4.1 of GNU `dc', an arbitrary precision +calculator. + + Copyright (C) 1984, 1994, 1997, 1998, 2000, 2005, 2006, 2008, 2013, +2016 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.2 or any later version published by the Free Software + Foundation; with no Invariant Sections, with no Front-Cover Texts, + and with no Back-Cover Texts. A copy of the license can be found + at `http://www.gnu.org/licenses/fdl.html' . * Menu: @@ -45,46 +54,49 @@ File: dc.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) File: dc.info, Node: Introduction, Next: Invocation, Prev: Top, Up: Top -Introduction -************ +1 Introduction +************** - DC is a reverse-polish desk calculator which supports unlimited +`dc' is a reverse-polish desk calculator which supports unlimited precision arithmetic. It also allows you to define and call macros. -Normally DC reads from the standard input; if any command arguments are -given to it, they are filenames, and DC reads and executes the contents -of the files instead of reading from standard input. All normal output -is to standard output; all error messages are written to standard error. +Normally `dc' reads from the standard input; if any command arguments +are given to it, they are filenames, and `dc' reads and executes the +contents of the files instead of reading from standard input. All +normal output is to standard output; all error messages are written to +standard error. - To exit, use `q'. `C-c' does not exit; it is used to abort macros -that are looping, etc. (Currently this is not true; `C-c' does exit.) + To exit, use `q'. `C-c' (or whatever other keystroke your system +uses to generate a `SIGINT') does not exit; it is used to abort macros +that are looping, etc. A reverse-polish calculator stores numbers on a stack. Entering a number pushes it on the stack. Arithmetic operations pop arguments off the stack and push the results. - To enter a number in DC, type the digits, with an optional decimal -point. Exponential notation is not supported. To enter a negative -number, begin the number with `_'. `-' cannot be used for this, as it -is a binary operator for subtraction instead. To enter two numbers in -succession, separate them with spaces or newlines. These have no -meaning as commands. + To enter a number in `dc', type the digits (using upper case letters +`A' through `F' as "digits" when working with input bases greater than +ten), with an optional decimal point. Exponential notation is not +supported. To enter a negative number, begin the number with `_'. `-' +cannot be used for this, as it is a binary operator for subtraction +instead. To enter two numbers in succession, separate them with spaces +or newlines; these have no meaning as commands. File: dc.info, Node: Invocation, Next: Printing Commands, Prev: Introduction, Up: Top -Invocation -********** +2 Invocation +************ - DC may be invoked with the following command-line options: +`dc' may be invoked with the following command-line options: `-e EXPR' `--expression=EXPR' - Evaluate EXPR as DC commands. + Evaluate EXPR as `dc' commands. `-f FILE' `--file=FILE' - Read and evaluate DC commands from FILE. + Read and evaluate `dc' commands from FILE. `-h' @@ -106,8 +118,8 @@ then the standard input will be read for commands to evaluate. File: dc.info, Node: Printing Commands, Next: Arithmetic, Prev: Invocation, Up: Top -Printing Commands -***************** +3 Printing Commands +******************* `p' Prints the value on the top of the stack, without altering the @@ -123,21 +135,35 @@ Printing Commands number, and the integer portion of its absolute value is printed out as a "base (UCHAR_MAX+1)" byte stream. Assuming that (UCHAR_MAX+1) is 256 (as it is on most machines with 8-bit bytes), - the sequence `KSK 0k1/ [_1*]sx d0>x [256~aPd0<x]dsxx sxLKk' could - also accomplish this function, except for the side-effect of - clobbering the x register. (Details of the behavior with a number - are a GNU extension.) + the sequence `KSK0k1/ _1Ss[ls*]Sxd0>x [256~Ssd0<x]dsxx + sx[q]Sq[Lsd0>qaPlxx]dsxx sx0sqLqsxLxLK+k' could also accomplish + this function. (Much of the complexity of the above native-dc + code is due to the ~ computing the characters backwards, and the + desire to ensure that all registers wind up back in their original + states.) (Details of the behavior with a number are a GNU + extension. Traditional `dc' happened to "support" similar + functionality for a limited range of inputs as an accidental + side-effect of its internal representation of numbers.) `f' Prints the entire contents of the stack without altering anything. This is a good command to use if you are lost or want to figure out what the effect of some command has been. + All numeric output is split to fit within 70 columns, by default. +When a number is broken up in this way, the split is indicated by a "\" +at the end of the to-be-continued output lines. The column width at +which output is split can be overridden by setting the DC_LINE_LENGTH +environment variable to the desired width. A DC_LINE_LENGTH of 0 +(zero) disables the line-split feature altogether. Invalid values of +DC_LINE_LENGTH are silently ignored. (The DC_LINE_LENGTH variable is a +GNU extension.) + File: dc.info, Node: Arithmetic, Next: Stack Control, Prev: Printing Commands, Up: Top -Arithmetic -********** +4 Arithmetic +************ `+' Pops two values off the stack, adds them, and pushes the result. @@ -188,13 +214,13 @@ Arithmetic fractional part of this exponent will be ignored. The third value popped is the base which gets exponentiated, which should be an integer. For small integers this is like the sequence `Sm^Lm%', - but, unlike `^', this command will work with arbritrarily large + but, unlike `^', this command will work with arbitrarily large exponents. (This command is a GNU extension.) `v' Pops one value, computes its square root, and pushes that. The - precision value specifies the number of fraction digits in the - result. + maximum of the precision value and the precision of the argument + is used to determine the number of fraction digits in the result. Most arithmetic operations are affected by the _precision value_, which you can set with the `k' command. The default precision value is @@ -204,8 +230,8 @@ subtraction produces integer results. File: dc.info, Node: Stack Control, Next: Registers, Prev: Arithmetic, Up: Top -Stack Control -************* +5 Stack Control +*************** `c' Clears the stack, rendering it empty. @@ -216,15 +242,26 @@ Stack Control `r' Reverses the order of (swaps) the top two values on the stack. + (This can also be accomplished with the sequence `SaSbLaLb'.) (This command is a GNU extension.) +`R' + Pops the top-of-stack as an integer N. Cyclically rotates the top + N items on the updated stack. If N is positive, then the rotation + direction will make the topmost element the second-from top; if N + is negative, then the rotation will make the topmost element the + N-th element from the top. If the stack depth is less than N then + the entire stack is rotated (in the appropriate direction), + without any error being reported. (This command is a GNU + extension.) + File: dc.info, Node: Registers, Next: Parameters, Prev: Stack Control, Up: Top -Registers -********* +6 Registers +*********** - DC provides at least 256 memory registers, each named by a single +`dc' provides at least 256 memory registers(1), each named by a single character. You can store a number in a register and retrieve it later. `sR' @@ -232,8 +269,9 @@ character. You can store a number in a register and retrieve it later. R. `lR' - Copy the value in register R, and push it onto the stack. This - does not alter the contents of R. + Copy the value in register R, and push it onto the stack. The + value `0' is retrieved if the register is uninitialized or its + stack has become empty. This does not alter the contents of R. Each register also contains its own stack. The current register value is the top of the register's stack. @@ -248,13 +286,19 @@ character. You can store a number in a register and retrieve it later. the main stack. The previous value in register R's stack, if any, is now accessible via the `lR' command. + ---------- Footnotes ---------- + + (1) The exact number of registers provided by `dc' depends on the +range of an `unsigned char' in the C compiler used to create the `dc' +executable. + File: dc.info, Node: Parameters, Next: Strings, Prev: Registers, Up: Top -Parameters -********** +7 Parameters +************ - DC has three parameters that control its operation: the precision, +`dc' has three parameters that control its operation: the precision, the input radix, and the output radix. The precision specifies the number of fraction digits to keep in the result of most arithmetic operations. The input radix controls the interpretation of numbers @@ -289,34 +333,37 @@ radix. `K' Pushes the current precision on the stack. + File: dc.info, Node: Strings, Next: Status Inquiry, Prev: Parameters, Up: Top -Strings -******* +8 Strings +********* - DC can 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 contents of the string are processed as DC -commands). Both registers and the 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 +`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 contents of the string are processed as +`dc' commands). Both registers and the 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 and pushes it on the stack. For example, `[foo]P' prints the characters `foo' (with no - newline). + newline). Note that all square brackets (`['s and `]'s) must be + balanced; there is no mechanism provided for handling unbalanced + square brackets. `a' The mnemonic for this is somewhat erroneous: asciify. The top-of-stack is popped. If it was a number, then the low-order - byte of this number is converted into a string and pushed onto the - stack. Otherwise the top-of-stack was a string, and the first - character of that string is pushed back. (This command is a GNU - extension.) + byte of this number is converted into a 1-character string and + pushed onto the stack. Otherwise the top-of-stack was a string, + and the first character of that string is pushed back. (This + command is a GNU extension.) `x' Pops a value off the stack and executes it as a macro. Normally @@ -359,7 +406,7 @@ prints the object according to its type. During the execution of a macro, this command exits from the macro and also from the macro which invoked it. If called from the top level, or from a macro which was called directly from the top - level, the `q' command will cause DC to exit. + level, the `q' command will cause `dc' to exit. `Q' Pops a value off the stack and uses it as a count of levels of @@ -368,13 +415,22 @@ prints the object according to its type. File: dc.info, Node: Status Inquiry, Next: Miscellaneous, Prev: Strings, Up: Top -Status Inquiry -************** +9 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. + Pops a value off the stack, calculates the number of decimal + digits it has (or number of characters, if it is a string) and + pushes that number. + + Note that the digit count for a number does _not_ include any + leading zeros, even if those appear to the right of the radix + point. This may seem a bit strange at first, but it is compatible + with historical implementations of `dc', and can be argued to be + useful for computing the magnitude of a value: `dSaXLaZ-' will + compute the power-of-ten multiplier which would be needed to shift + the decimal point to be immediately before the leftmost non-zero + digit. `X' Pops a value off the stack, calculates the number of fraction @@ -388,12 +444,12 @@ Status Inquiry File: dc.info, Node: Miscellaneous, Next: Reporting bugs, Prev: Status Inquiry, Up: Top -Miscellaneous -************* +10 Miscellaneous +**************** `!' Will run the rest of the line as a system command. Note that - parsing of the !<, !=, and !> commands take precidence, so if you + parsing of the !<, !=, and !> commands take precedence, so if you want to run a command starting with <, =, or > you will need to add a space after the !. @@ -417,25 +473,26 @@ because the 2 was stored in an instance of 0:A that was later popped. File: dc.info, Node: Reporting bugs, Prev: Miscellaneous, Up: Top -Reporting bugs -************** +11 Reporting bugs +***************** - Email bug reports to <bug-dc@gnu.org>. +Email bug reports to <bug-dc@gnu.org>. Tag Table: -Node: Top1084 -Node: Introduction1663 -Node: Invocation2880 -Node: Printing Commands3724 -Node: Arithmetic4902 -Node: Stack Control7815 -Node: Registers8228 -Node: Parameters9154 -Node: Strings10415 -Node: Status Inquiry13385 -Node: Miscellaneous13942 -Node: Reporting bugs14909 +Node: Top795 +Node: Introduction1965 +Node: Invocation3314 +Node: Printing Commands4165 +Node: Arithmetic6210 +Node: Stack Control9186 +Node: Registers10177 +Ref: Registers-Footnote-111242 +Node: Parameters11394 +Node: Strings12659 +Node: Status Inquiry15816 +Node: Miscellaneous16884 +Node: Reporting bugs17857 End Tag Table |