Blame doc/dc.1

Packit 70b277
.\"
Packit 70b277
.\" dc.1 - the *roff document processor source for the dc manual
Packit 70b277
.\"
Packit 70b277
.\" This file is part of GNU dc.
Packit 70b277
.\" Copyright (C) 1994, 1997, 1998, 2000, 2001, 2005, 2006, 2008, 2013, 2016
Packit 70b277
.\" Free Software Foundation, Inc.
Packit 70b277
.\"
Packit 70b277
.\" Permission is granted to copy, distribute and/or modify this document
Packit 70b277
.\" under the terms of the GNU Free Documentation License, Version 1.2 or
Packit 70b277
.\" any later version published by the Free Software Foundation; with no
Packit 70b277
.\" Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Packit 70b277
.\" Texts.
Packit 70b277
.\"
Packit 70b277
.TH dc 1 "2008-05-22" "GNU Project"
Packit 70b277
.ds dc \fIdc\fP
Packit 70b277
.ds Dc \fIdc\fP
Packit 70b277
.SH NAME
Packit 70b277
dc \- an arbitrary precision calculator
Packit 70b277
.SH SYNOPSIS
Packit 70b277
dc [-V] [--version] [-h] [--help]
Packit 70b277
   [-e scriptexpression] [--expression=scriptexpression]
Packit 70b277
   [-f scriptfile] [--file=scriptfile]
Packit 70b277
   [file ...]
Packit 70b277
.SH DESCRIPTION
Packit 70b277
.PP
Packit 70b277
\*(Dc is a reverse-polish desk calculator which supports
Packit 70b277
unlimited precision arithmetic.
Packit 70b277
It also allows you to define and call macros.
Packit 70b277
Normally \*(dc reads from the standard input;
Packit 70b277
if any command arguments are given to it, they are filenames,
Packit 70b277
and \*(dc reads and executes the contents of the files before reading
Packit 70b277
from standard input.
Packit 70b277
All normal output is to standard output;
Packit 70b277
all error output is to standard error.
Packit 70b277
.PP
Packit 70b277
A reverse-polish calculator stores numbers on a stack.
Packit 70b277
Entering a number pushes it on the stack.
Packit 70b277
Arithmetic operations pop arguments off the stack and push the results.
Packit 70b277
.PP
Packit 70b277
To enter a number in
Packit 70b277
.IR dc ,
Packit 70b277
type the digits
Packit 70b277
(using upper case letters
Packit 70b277
.I A
Packit 70b277
through
Packit 70b277
.I F
Packit 70b277
as "digits" when working
Packit 70b277
with input bases greater than ten),
Packit 70b277
with an optional decimal point.
Packit 70b277
Exponential notation is not supported.
Packit 70b277
To enter a negative number,
Packit 70b277
begin the number with ``_''.
Packit 70b277
``-'' cannot be used for this,
Packit 70b277
as it is a binary operator for subtraction instead.
Packit 70b277
To enter two numbers in succession,
Packit 70b277
separate them with spaces or newlines.
Packit 70b277
These have no meaning as commands.
Packit 70b277
.SH OPTIONS
Packit 70b277
\*(Dc may be invoked with the following command-line options:
Packit 70b277
.TP
Packit 70b277
.B -V
Packit 70b277
.TP
Packit 70b277
.B --version
Packit 70b277
Print out the version of \*(dc that is being run and a copyright notice,
Packit 70b277
then exit.
Packit 70b277
.TP
Packit 70b277
.B -h
Packit 70b277
.TP
Packit 70b277
.B --help
Packit 70b277
Print a usage message briefly summarizing these command-line options
Packit 70b277
and the bug-reporting address,
Packit 70b277
then exit.
Packit 70b277
.TP
Packit 70b277
.B -e \fIscript\fP
Packit 70b277
.TP
Packit 70b277
.BI --expression= script
Packit 70b277
Add the commands in
Packit 70b277
.I script
Packit 70b277
to the set of commands to be run while processing the input.
Packit 70b277
.TP
Packit 70b277
.B -f \fIscript-file\fP
Packit 70b277
.TP
Packit 70b277
.BI --file= script-file
Packit 70b277
Add the commands contained in the file
Packit 70b277
.I script-file
Packit 70b277
to the set of commands to be run while processing the input.
Packit 70b277
.PP
Packit 70b277
If any command-line parameters remain after processing the above,
Packit 70b277
these parameters are interpreted as the names of input files to
Packit 70b277
be processed.
Packit 70b277
A file name of
Packit 70b277
.B -
Packit 70b277
refers to the standard input stream.
Packit 70b277
The standard input will processed if no script files or
Packit 70b277
expressions are specified.
Packit 70b277
.PD
Packit 70b277
.SH
Packit 70b277
Printing Commands
Packit 70b277
.TP
Packit 70b277
.B p
Packit 70b277
Prints the value on the top of the stack,
Packit 70b277
without altering the stack.
Packit 70b277
A newline is printed after the value.
Packit 70b277
.TP
Packit 70b277
.B n
Packit 70b277
Prints the value on the top of the stack, popping it off,
Packit 70b277
and does not print a newline after.
Packit 70b277
.TP
Packit 70b277
.B P
Packit 70b277
Pops off the value on top of the stack.
Packit 70b277
If it it a string, it is simply printed without a trailing newline.
Packit 70b277
Otherwise it is a number, and the integer portion of its absolute
Packit 70b277
value is printed out as a "base (UCHAR_MAX+1)" byte stream.
Packit 70b277
Assuming that (UCHAR_MAX+1) is 256
Packit 70b277
(as it is on most machines with 8-bit bytes),
Packit 70b277
the sequence \fBKSK0k1/_1Ss [ls*]Sxd0>x
Packit 70b277
[256~Ssd0<x]dsxxsx[q]Sq[Lsd0>qaPlxx]
Packit 70b277
dsxxsx0sqLqsxLxLK+k\fP
Packit 70b277
could also accomplish this function.
Packit 70b277
(Much of the complexity of the above native-dc code is due
Packit 70b277
to the ~ computing the characters backwards,
Packit 70b277
and the desire to ensure that all registers wind up back
Packit 70b277
in their original states.)
Packit 70b277
.TP
Packit 70b277
.B f
Packit 70b277
Prints the entire contents of the stack
Packit 70b277
.ig
Packit 70b277
and the contents of all of the registers,
Packit 70b277
..
Packit 70b277
without altering anything.
Packit 70b277
This is a good command to use if you are lost or want
Packit 70b277
to figure out what the effect of some command has been.
Packit 70b277
.PD
Packit 70b277
.SH
Packit 70b277
Arithmetic
Packit 70b277
.TP
Packit 70b277
.B +
Packit 70b277
Pops two values off the stack, adds them,
Packit 70b277
and pushes the result.
Packit 70b277
The precision of the result is determined only
Packit 70b277
by the values of the arguments,
Packit 70b277
and is enough to be exact.
Packit 70b277
.TP
Packit 70b277
.B -
Packit 70b277
Pops two values,
Packit 70b277
subtracts the first one popped from the second one popped,
Packit 70b277
and pushes the result.
Packit 70b277
.TP
Packit 70b277
.B *
Packit 70b277
Pops two values, multiplies them, and pushes the result.
Packit 70b277
The number of fraction digits in the result depends on
Packit 70b277
the current precision value and the number of fraction
Packit 70b277
digits in the two arguments.
Packit 70b277
.TP
Packit 70b277
.B /
Packit 70b277
Pops two values,
Packit 70b277
divides the second one popped from the first one popped,
Packit 70b277
and pushes the result.
Packit 70b277
The number of fraction digits is specified by the precision value.
Packit 70b277
.TP
Packit 70b277
.B %
Packit 70b277
Pops two values,
Packit 70b277
computes the remainder of the division that the
Packit 70b277
.B /
Packit 70b277
command would do,
Packit 70b277
and pushes that.
Packit 70b277
The value computed is the same as that computed by
Packit 70b277
the sequence \fBSd dld/ Ld*-\fP .
Packit 70b277
.TP
Packit 70b277
.B ~
Packit 70b277
Pops two values,
Packit 70b277
divides the second one popped from the first one popped.
Packit 70b277
The quotient is pushed first, and the remainder is pushed next.
Packit 70b277
The number of fraction digits used in the division
Packit 70b277
is specified by the precision value.
Packit 70b277
(The sequence \fBSdSn lnld/ LnLd%\fP could also accomplish
Packit 70b277
this function, with slightly different error checking.)
Packit 70b277
.TP
Packit 70b277
.B ^
Packit 70b277
Pops two values and exponentiates,
Packit 70b277
using the first value popped as the exponent
Packit 70b277
and the second popped as the base.
Packit 70b277
The fraction part of the exponent is ignored.
Packit 70b277
The precision value specifies the number of fraction
Packit 70b277
digits in the result.
Packit 70b277
.TP
Packit 70b277
.B |
Packit 70b277
Pops three values and computes a modular exponentiation.
Packit 70b277
The first value popped is used as the reduction modulus;
Packit 70b277
this value must be a non-zero number,
Packit 70b277
and should be an integer.
Packit 70b277
The second popped is used as the exponent;
Packit 70b277
this value must be a non-negative number,
Packit 70b277
and any fractional part of this exponent will be ignored.
Packit 70b277
The third value popped is the base which gets exponentiated,
Packit 70b277
which should be an integer.
Packit 70b277
For small integers this is like the sequence \fBSm^Lm%\fP,
Packit 70b277
but, unlike \fB^\fP, this command will work with arbitrarily large exponents.
Packit 70b277
.TP
Packit 70b277
.B v
Packit 70b277
Pops one value,
Packit 70b277
computes its square root,
Packit 70b277
and pushes that.
Packit 70b277
The maximum of the precision value and the precision of the argument
Packit 70b277
is used to determine the number of fraction digits in the result.
Packit 70b277
.PP
Packit 70b277
Most arithmetic operations are affected by the ``precision value'',
Packit 70b277
which you can set with the
Packit 70b277
.B k
Packit 70b277
command.
Packit 70b277
The default precision value is zero,
Packit 70b277
which means that all arithmetic except for
Packit 70b277
addition and subtraction produces integer results.
Packit 70b277
.SH
Packit 70b277
Stack Control
Packit 70b277
.TP
Packit 70b277
.B c
Packit 70b277
Clears the stack, rendering it empty.
Packit 70b277
.TP
Packit 70b277
.B d
Packit 70b277
Duplicates the value on the top of the stack,
Packit 70b277
pushing another copy of it.
Packit 70b277
Thus, ``4d*p'' computes 4 squared and prints it.
Packit 70b277
.TP
Packit 70b277
.B r
Packit 70b277
Reverses the order of (swaps) the top two values on the stack.
Packit 70b277
(This can also be accomplished with the sequence \fBSaSbLaLb\fP.)
Packit 70b277
.TP
Packit 70b277
.B R
Packit 70b277
Pops the top-of-stack as an integer
Packit 70b277
.IR n .
Packit 70b277
Cyclically rotates the top
Packit 70b277
.I n
Packit 70b277
items on the updated stack.
Packit 70b277
If
Packit 70b277
.I n
Packit 70b277
is positive, then the rotation direction will make the topmost
Packit 70b277
element the second-from top;
Packit 70b277
if
Packit 70b277
.I n
Packit 70b277
is negative, then the rotation will make the topmost element the
Packit 70b277
.IR n -th
Packit 70b277
element from the top.
Packit 70b277
If the stack depth is less than
Packit 70b277
.IR n ,
Packit 70b277
then the entire stack is rotated (in the appropriate direction),
Packit 70b277
without any error being reported.
Packit 70b277
.SH
Packit 70b277
Registers
Packit 70b277
.PP
Packit 70b277
\*(Dc provides at least 256 memory registers,
Packit 70b277
each named by a single character.
Packit 70b277
You can store a number or a string in a register and retrieve it later.
Packit 70b277
.TP
Packit 70b277
.BI s r
Packit 70b277
Pop the value off the top of the stack and store
Packit 70b277
it into register
Packit 70b277
.IR r .
Packit 70b277
.TP
Packit 70b277
.BI l r
Packit 70b277
Copy the value in register
Packit 70b277
.I r
Packit 70b277
and push it onto the stack.
Packit 70b277
The value 0 is retrieved if the register is uninitialized.
Packit 70b277
This does not alter the contents of
Packit 70b277
.IR r .
Packit 70b277
.PP
Packit 70b277
Each register also contains its own stack.
Packit 70b277
The current register value is the top of the register's stack.
Packit 70b277
.TP
Packit 70b277
.BI S r
Packit 70b277
Pop the value off the top of the (main) stack and
Packit 70b277
push it onto the stack of register
Packit 70b277
.IR r .
Packit 70b277
The previous value of the register becomes inaccessible.
Packit 70b277
.TP
Packit 70b277
.BI L r
Packit 70b277
Pop the value off the top of register
Packit 70b277
.IR r 's
Packit 70b277
stack and push it onto the main stack.
Packit 70b277
The previous value
Packit 70b277
in register
Packit 70b277
.IR r 's
Packit 70b277
stack, if any,
Packit 70b277
is now accessible via the
Packit 70b277
.BI l r
Packit 70b277
command.
Packit 70b277
.ig
Packit 70b277
.PP
Packit 70b277
The
Packit 70b277
.B f
Packit 70b277
command prints a list of all registers that have contents stored in them,
Packit 70b277
together with their contents.
Packit 70b277
Only the current contents of each register
Packit 70b277
(the top of its stack)
Packit 70b277
is printed.
Packit 70b277
..
Packit 70b277
.SH
Packit 70b277
Parameters
Packit 70b277
.PP
Packit 70b277
\*(Dc has three parameters that control its operation:
Packit 70b277
the precision, the input radix, and the output radix.
Packit 70b277
The precision specifies the number
Packit 70b277
of fraction digits to keep in the result of most arithmetic operations.
Packit 70b277
The input radix controls the interpretation of numbers typed in;
Packit 70b277
all numbers typed in use this radix.
Packit 70b277
The output radix is used for printing numbers.
Packit 70b277
.PP
Packit 70b277
The input and output radices are separate parameters;
Packit 70b277
you can make them unequal,
Packit 70b277
which can be useful or confusing.
Packit 70b277
The input radix must be between 2 and 16 inclusive.
Packit 70b277
The output radix must be at least 2.
Packit 70b277
The precision must be zero or greater.
Packit 70b277
The precision is always measured in decimal digits,
Packit 70b277
regardless of the current input or output radix.
Packit 70b277
.TP
Packit 70b277
.B i
Packit 70b277
Pops the value off the top of the stack
Packit 70b277
and uses it to set the input radix.
Packit 70b277
.TP
Packit 70b277
.B o
Packit 70b277
Pops the value off the top of the stack
Packit 70b277
and uses it to set the output radix.
Packit 70b277
.TP
Packit 70b277
.B k
Packit 70b277
Pops the value off the top of the stack
Packit 70b277
and uses it to set the precision.
Packit 70b277
.TP
Packit 70b277
.B I
Packit 70b277
Pushes the current input radix on the stack.
Packit 70b277
.TP
Packit 70b277
.B O
Packit 70b277
Pushes the current output radix on the stack.
Packit 70b277
.TP
Packit 70b277
.B K
Packit 70b277
Pushes the current precision on the stack.
Packit 70b277
.SH
Packit 70b277
Strings
Packit 70b277
.PP
Packit 70b277
\*(Dc has a limited ability to operate on strings
Packit 70b277
as well as on numbers;
Packit 70b277
the only things you can do with strings are
Packit 70b277
print them and execute them as macros
Packit 70b277
(which means that the contents of the string are processed as
Packit 70b277
\*(dc commands).
Packit 70b277
All registers and the stack can hold strings,
Packit 70b277
and \*(dc always knows whether any given object is a string or a number.
Packit 70b277
Some commands such as arithmetic operations demand numbers
Packit 70b277
as arguments and print errors if given strings.
Packit 70b277
Other commands can accept either a number or a string;
Packit 70b277
for example, the
Packit 70b277
.B p
Packit 70b277
command can accept either and prints the object
Packit 70b277
according to its type.
Packit 70b277
.TP
Packit 70b277
.BI [ characters ]
Packit 70b277
Makes a string containing
Packit 70b277
.I characters
Packit 70b277
(contained between balanced
Packit 70b277
.B [
Packit 70b277
and
Packit 70b277
.B ]
Packit 70b277
characters),
Packit 70b277
and pushes it on the stack.
Packit 70b277
For example,
Packit 70b277
.B [foo]P
Packit 70b277
prints the characters
Packit 70b277
.B foo
Packit 70b277
(with no newline).
Packit 70b277
.TP
Packit 70b277
.B a
Packit 70b277
The top-of-stack is popped.
Packit 70b277
If it was a number, then the low-order byte of this number
Packit 70b277
is converted into a string and pushed onto the stack.
Packit 70b277
Otherwise the top-of-stack was a string,
Packit 70b277
and the first character of that string is pushed back.
Packit 70b277
.TP
Packit 70b277
.B x
Packit 70b277
Pops a value off the stack and executes it as a macro.
Packit 70b277
Normally it should be a string;
Packit 70b277
if it is a number,
Packit 70b277
it is simply pushed back onto the stack.
Packit 70b277
For example,
Packit 70b277
.B [1p]x
Packit 70b277
executes the macro
Packit 70b277
.B 1p
Packit 70b277
which pushes
Packit 70b277
.B 1
Packit 70b277
on the stack and prints
Packit 70b277
.B 1
Packit 70b277
on a separate line.
Packit 70b277
.PP
Packit 70b277
Macros are most often stored in registers;
Packit 70b277
.B [1p]sa
Packit 70b277
stores a macro to print
Packit 70b277
.B 1
Packit 70b277
into register
Packit 70b277
.BR a ,
Packit 70b277
and
Packit 70b277
.B lax
Packit 70b277
invokes this macro.
Packit 70b277
.TP
Packit 70b277
.BI > r
Packit 70b277
Pops two values off the stack and compares them
Packit 70b277
assuming they are numbers,
Packit 70b277
executing the contents of register
Packit 70b277
.I r
Packit 70b277
as a macro if the original top-of-stack
Packit 70b277
is greater.
Packit 70b277
Thus,
Packit 70b277
.B 1 2>a
Packit 70b277
will invoke register
Packit 70b277
.BR a 's
Packit 70b277
contents and
Packit 70b277
.B 2 1>a
Packit 70b277
will not.
Packit 70b277
.TP
Packit 70b277
.BI !> r
Packit 70b277
Similar but invokes the macro if the original top-of-stack is
Packit 70b277
not greater than (less than or equal to) what was the second-to-top.
Packit 70b277
.TP
Packit 70b277
.BI < r
Packit 70b277
Similar but invokes the macro if the original top-of-stack is less.
Packit 70b277
.TP
Packit 70b277
.BI !< r
Packit 70b277
Similar but invokes the macro if the original top-of-stack is
Packit 70b277
not less than (greater than or equal to) what was the second-to-top.
Packit 70b277
.TP
Packit 70b277
.BI = r
Packit 70b277
Similar but invokes the macro if the two numbers popped are equal.
Packit 70b277
.TP
Packit 70b277
.BI != r
Packit 70b277
Similar but invokes the macro if the two numbers popped are not equal.
Packit 70b277
.ig
Packit 70b277
This can also be validly used to compare two strings for equality.
Packit 70b277
..
Packit 70b277
.TP
Packit 70b277
.B ?
Packit 70b277
Reads a line from the terminal and executes it.
Packit 70b277
This command allows a macro to request input from the user.
Packit 70b277
.TP
Packit 70b277
.B q
Packit 70b277
exits from a macro and also from the macro which invoked it.
Packit 70b277
If called from the top level,
Packit 70b277
or from a macro which was called directly from the top level,
Packit 70b277
the
Packit 70b277
.B q
Packit 70b277
command will cause \*(dc to exit.
Packit 70b277
.TP
Packit 70b277
.B Q
Packit 70b277
Pops a value off the stack and uses it as a count
Packit 70b277
of levels of macro execution to be exited.
Packit 70b277
Thus,
Packit 70b277
.B 3Q
Packit 70b277
exits three levels.
Packit 70b277
The
Packit 70b277
.B Q
Packit 70b277
command will never cause \*(dc to exit.
Packit 70b277
.SH
Packit 70b277
Status Inquiry
Packit 70b277
.TP
Packit 70b277
.B Z
Packit 70b277
Pops a value off the stack,
Packit 70b277
calculates the number of decimal digits it has
Packit 70b277
(or number of characters, if it is a string)
Packit 70b277
and pushes that number.
Packit 70b277
The digit count for a number does
Packit 70b277
.I not
Packit 70b277
include any leading zeros,
Packit 70b277
even if those appear to the right of the radix point.
Packit 70b277
.TP
Packit 70b277
.B X
Packit 70b277
Pops a value off the stack,
Packit 70b277
calculates the number of fraction digits it has,
Packit 70b277
and pushes that number.
Packit 70b277
For a string,
Packit 70b277
the value pushed is
Packit 70b277
.\" -1.
Packit 70b277
0.
Packit 70b277
.TP
Packit 70b277
.B z
Packit 70b277
Pushes the current stack depth:
Packit 70b277
the number of objects on the stack before the execution of the
Packit 70b277
.B z
Packit 70b277
command.
Packit 70b277
.SH
Packit 70b277
Miscellaneous
Packit 70b277
.TP
Packit 70b277
.B !
Packit 70b277
Will run the rest of the line as a system command.
Packit 70b277
Note that parsing of the !<, !=, and !> commands take precedence,
Packit 70b277
so if you want to run a command starting with <, =, or > you will
Packit 70b277
need to add a space after the !.
Packit 70b277
.TP
Packit 70b277
.B #
Packit 70b277
Will interpret the rest of the line as a comment.
Packit 70b277
.TP
Packit 70b277
.BI : r
Packit 70b277
Will pop the top two values off of the stack.
Packit 70b277
The old second-to-top value will be stored in the array
Packit 70b277
.IR r ,
Packit 70b277
indexed by the old top-of-stack value.
Packit 70b277
.TP
Packit 70b277
.BI ; r
Packit 70b277
Pops the top-of-stack and uses it as an index into
Packit 70b277
the array
Packit 70b277
.IR r .
Packit 70b277
The selected value is then pushed onto the stack.
Packit 70b277
.P
Packit 70b277
Note that each stacked instance of a register has its own
Packit 70b277
array associated with it.
Packit 70b277
Thus \fB1 0:a 0Sa 2 0:a La 0;ap\fP will print 1,
Packit 70b277
because the 2 was stored in an instance of 0:a that
Packit 70b277
was later popped.
Packit 70b277
.SH
Packit 70b277
BUGS
Packit 70b277
.PP
Packit 70b277
Email bug reports to
Packit 70b277
.BR bug-dc@gnu.org .