Usenet 1994 January/usenetsourcesnewsgroupsinfomagicjanuary1994.iso/sources/misc/volume24/gnucalc/part37

Text File | 1991-10-31 | 57KB | 1,240 lines

Newsgroups: comp.sources.misc
From: [e-mail] (David Gillespie)
Subject:  v24i085:  gnucalc - GNU Emacs Calculator, v2.00, Part37/56
Message-ID: <[e-mail]>
X-Md4-Signature: be1b39282f2d976b087f6ed2ed1affbf
Date: Thu, 31 Oct 1991 21:46:33 GMT
Approved: [e-mail]

Submitted-by: [e-mail] (David Gillespie)
Posting-number: Volume 24, Issue 85
Archive-name: gnucalc/part37
Environment: Emacs
Supersedes: gmcalc: Volume 13, Issue 27-45

---- Cut Here and unpack ----
#!/bin/sh
# do not concatenate these parts, unpack them in order with /bin/sh
# file calc.texinfo continued
#
if test ! -r _shar_seq_.tmp; then
    echo 'Please unpack part 1 first!'
    exit 1
fi
(read Scheck
 if test "$Scheck" != 37; then
    echo Please unpack part "$Scheck" next!
    exit 1
 else
    exit 0
 fi
) < _shar_seq_.tmp || exit 1
if test ! -f _shar_wnt_.tmp; then
    echo 'x - still skipping calc.texinfo'
else
echo 'x - continuing file calc.texinfo'
sed 's/^X//' << 'SHAR_EOF' >> 'calc.texinfo' &&
X
@kindex h c
@pindex calc-describe-key-briefly
The @kbd{h c} (@code{calc-describe-key-briefly}) command reads a
key sequence and displays a brief one-line description of it at
the bottom of the screen.  It looks for the key sequence in the
Summary node of the Calc manual; if it doesn't find the sequence
there, it acts just like its regular Emacs counterpart @kbd{C-h c}
(@code{describe-key-briefly}).  For example, @kbd{h c H a S}
gives the description:
X
@smallexample
H a S runs calc-solve-for:  a `H a S' v  => fsolve(a,v)  (?=notes)
@end smallexample
X
@noindent
which means the command @kbd{H a S} or @kbd{H M-x calc-solve-for}
takes a value @cite{a} from the stack, prompts for a value @cite{v},
then applies the algebraic function @code{fsolve} to these values.
The @samp{?=notes} message means you can now type @kbd{?} to see
additional notes from the summary that apply to this command.
X
@kindex h f
@pindex calc-describe-function
The @kbd{h f} (@code{calc-describe-function}) command looks up an
algebraic function or a command name in the Calc manual.  The
prompt initially contains @samp{calcFunc-}; follow this with an
algebraic function name to look up that function in the
@samp{Function Index}.  Or, backspace and enter a command name
beginning with @samp{calc-} to look it up in the @samp{Command Index}.
This command will also look up operator symbols that can appear
in algebraic formulas, like @samp{%} and @samp{=>}.
X
@kindex h v
@pindex calc-describe-variable
The @kbd{h v} (@code{calc-describe-variable}) command looks up a
variable in the Calc manual.  The prompt initially contains the
@samp{var-} prefix; just add a variable name like @code{pi} or
@code{PlotRejects}.
X
@kindex h b
@pindex describe-bindings
The @kbd{h b} (@code{calc-describe-bindings}) command is just like
@kbd{C-h b}, except that only local (Calc-related) key bindings are
listed.
X
@kindex h n
The @kbd{h n} or @kbd{h C-n} (@code{calc-view-news}) command displays
the ``news'' or change history of Calc.  This is kept in the file
@file{README}, which Calc looks for in the same directory as the Calc
source files.
X
@kindex h C-c
@kindex h C-d
@kindex h C-w
The @kbd{h C-c}, @kbd{h C-d}, and @kbd{h C-w} keys display copying,
distribution, and warranty information about Calc.  These work by
pulling up the appropriate parts of the @samp{Copying} or
@samp{Reporting Bugs} sections of the manual.
X
@node Stack Basics, Numeric Entry, Help Commands, Introduction
@section Stack Basics
X
@noindent
@cindex Stack basics
@c [fix-tut RPN Calculations and the Stack]
Calc uses RPN notation.  If you are not familar with RPN, @pxref{RPN
Tutorial}.
X
To add the numbers 1 and 2 in Calc you would type the keys:
@kbd{1 @key{RET} 2 +}.
(@key{RET} corresponds to the @key{ENTER} key on most calculators.)
The first three keystrokes ``push'' the numbers 1 and 2 onto the stack.  The
@kbd{+} key always ``pops'' the top two numbers from the stack, adds them,
and pushes the result (3) back onto the stack.  This number is ready for
further calculations:  @kbd{5 -} pushes 5 onto the stack, then pops the
3 and 5, subtracts them, and pushes the result (@i{-2}).@refill
X
Note that the ``top'' of the stack actually appears at the @emph{bottom}
of the buffer.  A line containing a single @samp{.} character signifies
the end of the buffer; Calculator commands operate on the number(s)
directly above this line.  The @kbd{d t} (@code{calc-truncate-stack})
command allows you to move the @samp{.} marker up and down in the stack;
@pxref{Truncating the Stack}.
X
@kindex d l
@pindex calc-line-numbering
Stack elements are numbered consecutively, with number 1 being the top of
the stack.  These line numbers are ordinarily displayed on the lefthand side
of the window.  The @kbd{d l} (@code{calc-line-numbering}) command controls
whether these numbers appear.  (Line numbers may be turned off since they
slow the Calculator down a bit and also clutter the display.)
X
@kindex o
@kindex d `
@pindex calc-realign
The unshifted letter @kbd{o} (@code{calc-realign}) command (also on the
@w{@kbd{d `}} key) repositions the cursor to its top-of-stack ``home''
position.  It also undoes any horizontal scrolling in the window.
If you give it a numeric prefix argument, it instead moves the cursor
to the specified stack element.
X
The @key{RET} (or equivalent @key{SPC}) key is only required to separate
two consecutive numbers.
(After all, if you typed @kbd{1 2} by themselves the Calculator
would enter the number 12.)  If you press @kbd{RET} or @kbd{SPC} @emph{not}
right after typing a number, the key duplicates the number on the top of
the stack.  @kbd{@key{RET} *} is thus a handy way to square a number.@refill
X
The @key{DEL} key pops and throws away the top number on the stack.
The @key{TAB} key swaps the top two objects on the stack.
@xref{Stack and Trail}, for descriptions of these and other stack-related
commands.@refill
X
@node Numeric Entry, Algebraic Entry, Stack Basics, Introduction
@section Numeric Entry
X
@noindent
@kindex 0-9
@kindex .
@kindex e
@cindex Numeric entry
@cindex Entering numbers
Pressing a digit or other numeric key begins numeric entry using the
minibuffer.  The number is pushed on the stack when you press the @key{RET}
or @key{SPC} keys.  If you press any other non-numeric key, the number is
pushed onto the stack and the appropriate operation is performed.  If
you press a numeric key which is not valid (say, a second decimal point),
the key is ignored.
X
@cindex Minus signs
@cindex Negative numbers, entering
@kindex _
There are three different concepts corresponding to the word ``minus,''
typified by @cite{a-b} (subtraction), @cite{-x}
(change-sign), and @cite{-5} (negative number).  Calc uses three
different keys for these operations, respectively:
@kbd{-}, @kbd{n}, and @kbd{_} (the underscore).  The @kbd{-} key subtracts
the two numbers on the top of the stack.  The @kbd{n} key changes the sign
of the number on the top of the stack or the number currently being entered.
The @kbd{_} key begins entry of a negative number or changes the sign of
the number currently being entered.  The following sequences all enter the
number @i{-5} onto the stack:  @kbd{0 @key{RET} 5 -}, @kbd{5 n @key{RET}},
@kbd{5 @key{RET} n}, @kbd{_ 5 @key{RET}}, @kbd{5 _ @key{RET}}.@refill
X
The @kbd{#}, @kbd{@@}, @kbd{'}, @kbd{"}, @kbd{p}, and @kbd{M} keys are
also active during numeric entry.  They are used for entering
non-decimal numbers, HMS forms, and so on; these notations are
described later in this manual with the corresponding data types.
@xref{Data Types}.
X
During numeric entry, the only editing key available is @kbd{DEL}.
X
@node Algebraic Entry, Quick Calculator, Numeric Entry, Introduction
@section Algebraic Entry
X
@noindent
@kindex '
@pindex calc-algebraic-entry
@cindex Algebraic notation
@cindex Formulas, entering
Calculations can also be entered in algebraic form.  This is accomplished
by typing the apostrophe key, @kbd{'}, followed by the expression in
standard format:  @kbd{@key{'} 2+3*4 @key{RET}} computes
@c{$2+(3\times4) = 14$}
@cite{2+(3*4) = 14} and pushes that on the stack.  If you wish you can
ignore the RPN aspect of Calc altogether and simply enter algebraic
expressions in this way.  You may want to use @key{DEL} every so often to
clear previous results off the stack.@refill
X
You can press the apostrophe key during normal numeric entry to switch
the half-entered number into algebraic entry mode.  One reason to do this
would be to use the full Emacs cursor motion and editing keys, which are
available during algebraic entry but not during numeric entry.
X
In the same vein, during either numeric or algebraic entry you can
press @kbd{`} to switch to @code{calc-edit} mode, where you complete
your half-finished entry in a separate buffer.  @xref{Editing Stack Entries}.
X
@kindex m a
@pindex calc-algebraic-mode
@cindex Algebraic mode
If you prefer algebraic entry, you can use the command @kbd{m a}
(@code{calc-algebraic-mode}) to set Algebraic mode.  In this mode,
digits and other keys that would normally start numeric entry instead
start full algebraic entry; as long as your formula begins with a digit
you can omit the apostrophe.  Open parentheses and square brackets also
begin algebraic entry.  You can still do RPN calculations in this mode,
but you will have to press @key{RET} to terminate every number:
@kbd{2 @key{RET} 3 @key{RET} * 4 @key{RET} +} would accomplish the same
thing as @kbd{2*3+4 @key{RET}}.@refill
X
@cindex Incomplete algebraic mode
If you give a numeric prefix argument like @kbd{C-u} to the @kbd{m a}
command, it enables Incomplete Algebraic mode; this is like regular
Algebraic mode except that it applies to the @kbd{(} and @kbd{[} keys
only.  Numeric keys still begin a numeric entry in this mode.
X
@kindex m t
@pindex calc-total-algebraic-mode
@cindex Total algebraic mode
The @kbd{m t} (@code{calc-total-algebraic-mode}) gives you an even
stronger algebraic-entry mode, in which @emph{all} regular letter and
punctuation keys begin algebraic entry.  Use this if you prefer typing
@w{@kbd{sqrt( )}} instead of @kbd{Q}, @w{@kbd{factor( )}} instead of
@kbd{a f}, and so on.  To type regular Calc commands when you are in
``total'' algebraic mode, hold down the @key{META} key.  Thus @kbd{M-q}
is the command to quit Calc, @kbd{M-p} sets the precision, and
@kbd{M-m t} (or @kbd{M-m M-t}, if you prefer) turns total algebraic
mode back off again.  Meta keys also terminate algebraic entry, so
that @kbd{2+3 M-S} is equivalent to @kbd{2+3 RET M-S}.  The symbol
@samp{Alg*} will appear in the mode line whenever you are in this mode.
X
Pressing @kbd{'} (the apostrophe) a second time re-enters the previous
algebraic formula.  You can then use the normal Emacs editing keys to
modify this formula to your liking before pressing @key{RET}.
X
@kindex $
@cindex Formulas, referring to stack
Within a formula entered from the keyboard, the symbol @kbd{$}
represents the number on the top of the stack.  If an entered formula
contains any @kbd{$} characters, the Calculator replaces the top of
stack with that formula rather than simply pushing the formula onto the
stack.  Thus, @kbd{' 1+2 @key{RET}} pushes 3 on the stack, and @kbd{$*2
@key{RET}} replaces it with 6.  Note that the @kbd{$} key always
initiates algebraic entry; the @kbd{'} is unnecessary if @kbd{$} is the
first character in the new formula.@refill
X
Higher stack elements can be accessed from an entered formula with the
symbols @kbd{$$}, @kbd{$$$}, and so on.  The number of stack elements
removed (to be replaced by the entered values) equals the number of dollar
signs in the longest such symbol in the formula.  For example, @samp{$$+$$$}
adds the second and third stack elements, replacing the top three elements
with the answer.  (All information about the top stack element is thus lost
since no single @samp{$} appears in this formula.)@refill
X
A slightly different way to refer to stack elements is with a dollar
sign followed by a number:  @samp{$1}, @samp{$2}, and so on are much
like @samp{$}, @samp{$$}, etc., except that stack entries referred
to numerically are not replaced by the algebraic entry.  That is, while
@samp{$+1} replaces 5 on the stack with 6, @samp{$1+1} leaves the 5
on the stack and pushes an additional 6.
X
If a sequence of formulas are entered separated by commas, each formula
is pushed onto the stack in turn.  For example, @samp{1,2,3} pushes
those three numbers onto the stack (leaving the 3 at the top), and
@samp{$+1,$-1} replaces a 5 on the stack with 4 followed by 6.  Also,
@samp{$,$$} exchanges the top two elements of the stack, just like the
@key{TAB} key.
X
If you finish your algebraic entry by pressing @kbd{LFD} (or @kbd{C-j})
instead of @key{RET}, Calc disables the default simplifications
(as if by @kbd{m O}; @pxref{Simplification Modes}) while the entry
is being pushed on the stack.  Thus @kbd{' 1+2 @key{RET}} pushes 3
on the stack, but @kbd{' 1+2 @key{LFD}} pushes the formula @cite{1+2};
you might then press @kbd{=} when it is time to evaluate this formula.
X
@node Quick Calculator, Prefix Arguments, Algebraic Entry, Introduction
@section ``Quick Calculator'' Mode
X
@noindent
@kindex M-# q
@pindex quick-calc
@cindex Quick Calculator
There is another way to invoke the Calculator if all you need to do
is make one or two quick calculations.  Type @kbd{M-# q} (or
@kbd{M-x quick-calc}), then type any formula as an algebraic entry.
The Calculator will compute the result and display it in the echo
area, without ever actually putting up a Calculator window.
X
You can use the @kbd{$} character in a Quick Calculator formula to
refer to the previous Quick Calculator result.  Older results are
not retained; the Quick Calculator has no effect on the full
Calculator's stack or trail.  If you compute a result and then
forget what it was, just run @code{M-# q} again and enter
@samp{$} as the formula.
X
If this is the first time you have used the Calculator in this Emacs
session, the @kbd{M-# q} command will create the @code{*Calculator*}
buffer and perform all the usual initializations; it simply will
refrain from putting that buffer up in a new window.  The Quick
Calculator refers to the @code{*Calculator*} buffer for all mode
settings.  Thus, for example, to set the precision that the Quick
Calculator uses, simply run the full Calculator momentarily and use
the regular @kbd{p} command.
X
If you use @code{M-# q} from inside the Calculator buffer, the
effect is the same as pressing the apostrophe key (algebraic entry).
X
The result of a Quick calculation is placed in the Emacs ``kill ring''
as well as being displayed.  A subsequent @kbd{C-y} command will
yank the result into the editing buffer.  You can also use this
to yank the result into the next @kbd{M-# q} input line as a more
explicit alternative to @kbd{$} notation, or to yank the result
into the Calculator stack after typing @kbd{M-# c}.
X
If you finish your formula by typing @key{LFD} (or @kbd{C-j}) instead
of @key{RET}, the result is inserted immediately into the buffer
rather than going into the kill ring.
X
Quick Calculator results are actually evaluated as if by the @kbd{=}
key (which replaces variable names by their stored values, if any).
If the formula you enter is an assignment to a variable using the
@samp{:=} operator, say, @samp{foo := 2 + 3} or @samp{foo := foo + 1},
then the result of the evaluation is stored in that Calc variable.
@xref{Store and Recall}.
X
If the result is an integer and the current display radix is decimal,
the number will also be displayed in hex and octal formats.  If the
integer is in the range from 1 to 126, it will also be displayed as
an ASCII character.
X
For example, the quoted character @samp{"x"} produces the vector
result @samp{[120]} (because 120 is the ASCII code of the lower-case
`x'; @pxref{Strings}).  Since this is a vector, not an integer, it
is displayed only according to the current mode settings.  But
running Quick Calc again and entering @samp{120} will produce the
result @samp{120 (16#78, 8#170, x)} which shows the number in its
decimal, hexadecimal, octal, and ASCII forms.
X
Please note that the Quick Calculator is not any faster at loading
or computing the answer than the full Calculator; the name ``quick''
merely refers to the fact that it's much less hassle to use for
small calculations.
X
@node Prefix Arguments, Undo, Quick Calculator, Introduction
@section Numeric Prefix Arguments
X
@noindent
Many Calculator commands use numeric prefix arguments.  Some, such as
@kbd{d s} (@code{calc-sci-notation}), set a parameter to the value of
the prefix argument or use a default if you don't use a prefix.
Others (like @kbd{d f} (@code{calc-fix-notation}) require an argument
and prompt for a number if you don't give one as a prefix.@refill
X
As a rule, stack-manipulation commands accept a numeric prefix argument
which is interpreted as an index into the stack.  A positive argument
operates on the top @var{n} stack entries; a negative argument operates
on the @var{n}th stack entry in isolation; and a zero argument operates
on the entire stack.
X
Most commands that perform computations (such as the arithmetic and
scientific functions) accept a numeric prefix argument that allows the
operation to be applied across many stack elements.  For unary operations
(that is, functions of one argument like absolute value or complex
conjugate), a prefix argument applies that function to the top @var{n}
stack entries simultaneously.  For binary operations (functions of two
arguments like addition, GCD, and vector concatenation), a positive
prefix argument ``reduces'' the function across the top @var{n}
stack elements (for example, @kbd{C-u 5 +} sums the top 5 stack entries;
@pxref{Reducing and Mapping}), and a negative argument maps the next-to-top
@var{n} stack elements with the top stack element as a second argument
(for example, @kbd{7 c-u -5 +} adds 7 to the top 5 stack elements).
This feature is not available for operations which use the numeric prefix
argument for some other purpose.
X
Numeric prefixes are specified the same way as always in Emacs:  Press
a sequence of @key{META}-digits, or press @key{ESC} followed by digits,
or press @kbd{C-u} followed by digits.@refill
X
@kindex ~
@pindex calc-num-prefix
You can type @kbd{~} (@code{calc-num-prefix}) to pop an integer from the
top of the stack and enter it as the numeric prefix for the next command.
For example, @kbd{C-u 16 p} sets the precision to 16 digits; an alternate
(silly) way to do this would be @kbd{2 @key{RET} 4 ^ ~ p}, i.e., compute 2
to the fourth power and set the precision to that value.@refill
X
Conversely, if you have typed a numeric prefix argument the @kbd{~} key
pushes it onto the stack in the form of an integer.
X
@node Undo, Error Messages, Prefix Arguments, Introduction
@section Undoing Mistakes
X
@noindent
@kindex U
@kindex C-_
@pindex calc-undo
@cindex Mistakes, undoing
@cindex Undoing mistakes
@cindex Errors, undoing
The shift-@kbd{U} key (@code{calc-undo}) undoes the most recent operation.
If that operation added or dropped objects from the stack, those objects
are removed or restored.  If it was a @code{store} operation, you are
queried whether or not to restore the variable to its original value.
The @kbd{U} key may be pressed any number of times to undo successively
farther back in time; with a numeric prefix argument it undoes a
specified number of operations.  The undo history is cleared only by the
@kbd{q} (@code{calc-quit}) command.  (Recall that @kbd{M-# c} is usually
made synonymous with @code{calc-quit} while inside the Calculator; this
also clears the undo history.)
X
Currently the mode-setting commands (like @code{calc-precision}) are not
undoable.  You can undo past a point where you changed a mode, but you
will need to reset the mode yourself.
X
@kindex D
@pindex calc-redo
@cindex Redoing after an Undo
The shift-@kbd{D} key (@code{calc-redo}) redoes an operation that was
mistakenly undone.  Pressing @kbd{U} with a negative prefix argument is
equivalent to executing @code{calc-redo}.  You can redo any number of
times, up to the number of recent consecutive undo commands.  Redo
information is cleared whenever you give any command that adds new undo
information, i.e., if you undo, then enter a number on the stack or make
any other change, then it will be too late to redo.
X
@kindex M-RET
@pindex calc-last-args
@cindex Last-arguments feature
@cindex Arguments, restoring
The @kbd{M-@key{RET}} key (@code{calc-last-args}) is like undo in that
it restores the arguments of the most recent command onto the stack;
however, it does not remove the result of that command.  Given a numeric
prefix argument, this command applies to the @cite{n}th most recent
command which removed items from the stack; it pushes those items back
onto the stack.
X
The @kbd{K} (@code{calc-keep-args}) command provides a related function
to @kbd{M-@key{RET}}.  @xref{Stack and Trail}.
X
It is also possible to recall previous results or inputs using the trail.
@xref{Trail Commands}.
X
The standard Emacs @kbd{C-_} undo key is recognized as a synonym for @kbd{U}.
X
@node Error Messages, Multiple Calculators, Undo, Introduction
@section Error Messages
X
@noindent
@kindex w
@pindex calc-why
@cindex Errors, messages
@cindex Why did an error occur?
Many situations that would produce an error message in other calculators
simply create unsimplified formulas in the Emacs Calculator.  For example,
@kbd{1 @key{RET} 0 /} pushes the formula @cite{1 / 0}; @w{@kbd{0 L}} pushes
the formula @samp{ln(0)}.  Floating-point overflow and underflow are also
reasons for this to happen.
X
When a function call must be left in symbolic form, Calc usually
produces a message explaining why.  Messages that are probably
surprising or indicative of user errors are displayed automatically.
Other messages are simply kept in Calc's memory and are displayed only
if you type @kbd{w} (@code{calc-why}).  You can also press @kbd{w} if
the same computation results in several messages.  (The first message
will end with @samp{[w=more]} in this case.)
X
@kindex d w
@pindex calc-auto-why
The @kbd{d w} (@code{calc-auto-why}) command controls when error messages
are displayed automatically (Calc effectively presses @kbd{w} for you
after your computation finishes).  By default, this occurs only for
``important'' messages.  The other modes are to report @emph{all} messages
automatically, or to report none automatically (so that you must press
@kbd{w} yourself to see the messages).
X
@node Multiple Calculators, Troubleshooting Commands, Error Messages, Introduction
@section Multiple Calculators
X
@noindent
@pindex another-calc
It is possible to have any number of Calc Mode buffers at once.
Usually this is done by executing @kbd{M-x another-calc}, which
is similar to @kbd{M-# c} except that if a @samp{*Calculator*}
buffer already exists, a new, independent one with a name of the
form @samp{*Calculator*<@var{n}>} is created.  You can also use the
command @code{calc-mode} to put any buffer into Calculator mode, but
this would ordinarily never be done.
X
The @kbd{q} (@code{calc-quit}) command does not destroy a Calculator buffer;
it only closes its window.  Use @kbd{M-x kill-buffer} to destroy a
Calculator buffer.
X
Each Calculator buffer keeps its own stack, undo list, and mode settings
such as precision, angular mode, and display formats.  In Emacs terms,
variables such as @code{calc-stack} are buffer-local variables.  The
global default values of these variables are used only when a new
Calculator buffer is created.  The @code{calc-quit} command saves
the stack and mode settings of the buffer being quit as the new defaults.
X
There is only one trail buffer, @samp{*Calc Trail*}, used by all
Calculator buffers.
X
@node Troubleshooting Commands, , Multiple Calculators, Introduction
@section Troubleshooting Commands
X
@noindent
This section describes commands you can use in case a computation
incorrectly fails or gives the wrong answer.
X
@xref{Reporting Bugs}, if you find a problem that appears to be due
to a bug or deficiency in Calc.
X
@menu
* Recursion Depth::
* Caches::
* Debugging Calc::
@end menu
X
@node Recursion Depth, Caches, Troubleshooting Commands, Troubleshooting Commands
@subsection Recursion Depth
X
@noindent
@kindex M
@kindex I M
@pindex calc-more-recursion-depth
@pindex calc-less-recursion-depth
@cindex Recursion depth
@cindex ``Computation got stuck'' message
@cindex @code{max-lisp-eval-depth}
@cindex @code{max-specpdl-size}
Calc uses recursion in many of its calculations.  Emacs Lisp keeps a
variable @code{max-lisp-eval-depth} which limits the amount of recursion
possible in an attempt to recover from program bugs.  If a calculation
ever halts incorrectly with the message ``Computation got stuck or
ran too long,'' use the @kbd{M} command (@code{calc-more-recursion-depth})
to increase this limit.@refill
X
The limit is always increased (multiplied) by a factor of two.  There
is also an @kbd{I M} (@code{calc-less-recursion-depth}) command which
decreases this limit by a factor of two, down to a minimum value of 200.
The default value is 1000.
X
These commands also double or halve @code{max-specpdl-size}, another
internal Lisp recursion limit.  The minimum value for this limit is 600.
X
@node Caches, Debugging Calc, Recursion Depth, Troubleshooting Commands
@subsection Caches
X
@noindent
@cindex Caches
@cindex Flushing caches
Calc saves certain values after they have been computed once.  For
example, the @kbd{P} (@code{calc-pi}) command initially ``knows'' the
constant @c{$\pi$}
@cite{pi} to about 20 decimal places; if the current precision
is greater than this, it will recompute @c{$\pi$}
@cite{pi} using a series
approximation.  This value will not need to be recomputed ever again
unless you raise the precision still further.  Many operations such as
logarithms and sines make use of similarly cached values such as
@c{$\pi \over 4$}
@cite{pi/4} and @c{$\ln 2$}
@cite{ln(2)}.  The visible effect of caching is that
high-precision computations may be especially slow the first time.
Other things cached include powers of two (for the binary arithmetic
functions), matrix inverses and determinants, symbolic integrals, and
data computed by the graphing commands.
X
@pindex calc-flush-caches
If you suspect a Calculator cache has become corrupt, you can use the
@code{calc-flush-caches} command to reset all caches to the empty state.
(This should only be necessary in event of bugs in the Calculator.)
The @kbd{M-# 0} (with the zero key) command also resets caches along
with all other aspects of the Calculator's state.
X
@node Debugging Calc, , Caches, Troubleshooting Commands
@subsection Debugging Calc
X
@noindent
A few commands exist to help in the debugging of Calc commands.
@xref{Programming}, to see the various ways that you can write
your own Calc commands.
X
@kindex Z T
@pindex calc-timing
The @kbd{Z T} (@code{calc-timing}) command turns on and off a mode
in which the timing of slow commands is reported in the Trail.
Any Calc command that takes two seconds or longer writes a line
to the Trail showing how many seconds it took.  This value is
accurate only to within one second.
X
All steps of executing a command are included; in particular, time
taken to format the result for display in the stack and trail is
counted.  Some prompts also count time taken waiting for them to
be answered, while others do not; this depends on the exact
implementation of the command.  For best results, if you are timing
a sequence that includes prompts or multiple commands, define a
keyboard macro to run the whole sequence at once.  Calc's @kbd{X}
command (@pxref{Keyboard Macros}) will then report the time taken
to execute the whole macro.
X
Another advantage of the @kbd{X} command is that while it is
executing, the stack and trail are not updated from step to step.
So if you expect the output of your test sequence to leave a result
that may take a long time to format and you don't wish to count
this formatting time, end your sequence with a @key{DEL} keystroke
to clear the result from the stack.  When you run the sequence with
@kbd{X}, Calc will never bother to format the large result.
X
Another thing @kbd{Z T} does is to increase the Emacs variable
@code{gc-cons-threshold} to a much higher value (two million; the
usual default in Calc is 250,000) for the duration of each command.
This generally prevents garbage collection during the timing of
the command, though it may cause your Emacs process to grow
abnormally large.  (Garbage collection time is a major unpredictable
factor in the timing of Emacs operations.)
X
Another command that is useful when debugging your own Lisp
extensions to Calc is @kbd{M-x calc-pass-errors}, which disables
the error handler that changes the ``@code{max-lisp-eval-depth}
exceeded'' message to the much more friendly ``Computation got
stuck or ran too long.''  This handler interferes with the Emacs
Lisp debugger's @code{debug-on-error} mode.  Errors are reported
in the handler itself rather than at the true location of the
error.  After you have executed @code{calc-pass-errors}, Lisp
errors will be reported correctly but the user-friendly message
will be lost.
X
@node Data Types, Stack and Trail, Introduction, Top
@chapter Data Types
X
@noindent
This chapter discusses the various types of objects that can be placed
on the Calculator stack, how they are displayed, and how they are
entered.  (@xref{Data Type Formats}, for information on how these data
types are represented as Lisp objects.)@refill
X
Integers, fractions, and floats are various ways of describing real
numbers.  HMS forms also for many purposes act as real numbers.  These
types can be combined to form complex numbers, modulo forms, error forms,
or interval forms.  (But these last four types cannot be combined with
each other: error forms may not contain modulo forms, for example.)
Finally, all these types of numbers may be combined into vectors,
matrices, or algebraic formulas.
X
@menu
* Integers::                The most basic data type.
* Fractions::               This and above are called @dfn{rationals}.
* Floats::                  This and above are called @dfn{reals}.
* Complex Numbers::         This and above are called @dfn{numbers}.
* Infinities::
* Vectors and Matrices::
* Strings::
* HMS Forms::
* Date Forms::
* Modulo Forms::
* Error Forms::
* Interval Forms::
* Incomplete Objects::
* Variables::
* Formulas::
@end menu
X
@node Integers, Fractions, Data Types, Data Types
@section Integers
X
@noindent
@cindex Integers
The Calculator stores integers to arbitrary precision.  Addition,
subtraction, and multiplication of integers always yields an exact
integer result.  (If the result of a division or exponentiation of
integers is not an integer, it is expressed in fractional or
floating-point form according to the current Fraction Mode.
@xref{Fraction Mode}.)
X
A decimal integer is represented as an optional sign followed by a
sequence of digits.  Grouping (@pxref{Grouping Digits}) can be used to
insert a comma at every third digit for display purposes, but such
commas are not allowed during the entry of numbers.@refill
X
@kindex #
A non-decimal integer is represented as an optional sign, a radix
between 2 and 36, a @samp{#} symbol, and one or more digits.  For radix 11
and above, the letters A through Z (upper- or lower-case) count as
digits and do not terminate numeric entry mode.  @xref{Radix Modes}, for how
to set the default radix for display of integers.  Numbers of any radix
may be entered at any time.  If you press @kbd{#} at the beginning of a
number, the current display radix is used.@refill
X
@node Fractions, Floats, Integers, Data Types
@section Fractions
X
@noindent
@cindex Fractions
A @dfn{fraction} is a ratio of two integers.  Fractions are traditionally
written ``2/3'' but Calc uses the notation @samp{2:3}.  (The @kbd{/} key
performs RPN division; the following two sequences push the number
@samp{2:3} on the stack:  @kbd{2 :@: 3 @key{RET}}, @kbd{2 @key{RET} 3 /},
assuming Fraction Mode has been enabled.)
When the Calculator produces a fractional result it always reduces it to
simplest form, which may in fact be an integer.@refill
X
Fractions may also be entered in a three-part form, where @samp{2:3:4}
represents two-and-three-quarters.  @xref{Fraction Formats}, for fraction
display formats.@refill
X
Non-decimal fractions are entered and displayed as
@samp{@var{radix}#@var{num}:@var{denom}} (or in the analogous three-part
form).  The numerator and denominator always use the same radix.@refill
X
@node Floats, Complex Numbers, Fractions, Data Types
@section Floats
X
@noindent
@cindex Floating-point numbers
A floating-point number or @dfn{float} is a number stored in scientific
notation.  The number of significant digits in the fractional part is
governed by the current floating precision (@pxref{Precision}).  The
range of acceptable values is from @c{$10^{-4000000}$}
@cite{10^-4000000} to @c{$10^{4000000}$}
@cite{10^4000000},
plus zero and corresponding negative values.
X
Calculations that would exceed the allowable range of values (such
as @samp{exp(exp(20))}) are left in symbolic form by the Calculator.
The messages ``floating-point overflow'' or ``floating-point underflow''
indicate that during the calculation, a number would have been produced
that was too large or too close to zero, respectively, to be represented
by Calc.  This does not necessarily mean the final result would have
overflowed, just that an overflow occurred while computing the result.
X
If a rational number and a float are mixed in a calculation, the result
will in general be expressed as a float.  Commands that require an integer
value (such as @code{calc-gcd}) will also accept integer-valued floats,
i.e., a floating-point number with nothing after the decimal point.
X
Floats are identified by the presence of a decimal point and/or an
exponent.  In general a float consists of an optional sign, digits
including an optional decimal point, and an optional exponent consisting
of an @samp{e}, an optional sign, and one to seven exponent digits.
For example, @samp{23.5e-2} is 23.5 times ten to the minus-second power,
or 0.235.
X
Floating-point numbers are normally displayed in decimal notation with
all significant figures shown.  Exceedingly large or small numbers are
displayed in scientific notation.  Various other display options are
available.  @xref{Float Formats}.
X
@cindex Accuracy of computations
Floating-point numbers are stored in decimal, not binary.  The result
of each operation is rounded to the nearest value representable in the
number of significant digits specified by the current precision,
rounding away from zero in the case of a tie.  Thus (in the default
display mode) what you see is exactly what you get.  Some operations such
as square roots and transcendental functions are performed with several
digits of extra precision and then rounded down, in an effort to make the
final result accurate to the full requested precision.  However,
accuracy is not rigorously guaranteed.  If you suspect the validity of a
result, try doing the same calculation in a higher precision.  The
Calculator's arithmetic is not intended to be IEEE-conformant in any
way.@refill
X
While floats are always @emph{stored} in decimal, they can be entered
and displayed in any radix just like integers and fractions.  The
notation @samp{@var{radix}#@var{ddd}.@var{ddd}} is a floating-point
number whose digits are in the specified radix.  Note that the @samp{.}
is usually referred to as a ``radix point'' rather than a decimal
point in this case.  The number @samp{8#123.4567} is defined as
@samp{8#1234567 * 8^-4}.  If the radix is 14 or less, you can use
@samp{e} notation to write a non-decimal number in scientific notation.
The exponent is written in decimal, and is considered to be a power
of the radix: @samp{8#1234567e-4}.  If the radix is 15 or above, the
letter @samp{e} is a digit, so scientific notation must be written
out, e.g., @samp{16#123.4567*16^2}.  The first two exercises of the
Modes Tutorial explore some of the properties of non-decimal floats.
X
@node Complex Numbers, Infinities, Floats, Data Types
@section Complex Numbers
X
@noindent
@cindex Complex numbers
There are two supported formats for complex numbers: rectangular and
polar.  The default format is rectangular, displayed in the form
@samp{(@var{real},@var{imag})} where @var{real} is the real part and
@var{imag} is the imaginary part, each of which may be any real number.
Rectangular complex numbers can also be displayed in @samp{@var{a}+@var{b}i}
notation; @pxref{Complex Formats}.@refill
X
Polar complex numbers are displayed in the form `@t{(}@var{r}@t{;}@c{$\theta$}
@var{theta}@t{)}'
where @var{r} is the nonnegative magnitude and @c{$\theta$}
@var{theta} is the argument
or phase angle.  The range of @c{$\theta$}
@var{theta} depends on the current angular
mode (@pxref{Angular Modes}); it is generally between @i{-180} and
@i{+180} degrees or the equivalent range in radians.@refill
X
Complex numbers are entered in stages using incomplete objects.
@xref{Incomplete Objects}.
X
Operations on rectangular complex numbers yield rectangular complex
results, and similarly for polar complex numbers.  Where the two types
are mixed, or where new complex numbers arise (as for the square root of
a negative real), the current @dfn{Polar Mode} is used to determine the
type.  @xref{Polar Mode}.
X
A complex result in which the imaginary part is zero (or the phase angle
is 0 or 180 degrees or @c{$\pi$}
@cite{pi} radians) is automatically converted to a real
number.
X
@node Infinities, Vectors and Matrices, Complex Numbers, Data Types
@section Infinities
X
@noindent
@cindex Infinity
@cindex @code{inf} variable
@cindex @code{uinf} variable
@cindex @code{nan} variable
@vindex inf
@vindex uinf
@vindex nan
The word @code{inf} represents the mathematical concept of @dfn{infinity}.
Calc actually has three slightly different infinity-like values:
@code{inf}, @code{uinf}, and @code{nan}.  These are just regular
variable names (@pxref{Variables}); you should avoid using these
names for your own variables because Calc gives them special
treatment.  Infinities, like all variable names, are normally
entered using algebraic entry.
X
Mathematically speaking, it is not rigorously correct to treat
``infinity'' as if it were a number, but mathematicians often do
so informally.  When they say that @samp{1 / inf = 0}, what they
really mean is that @cite{1 / x}, as @cite{x} becomes larger and
larger, becomes arbitrarily close to zero.  So you can imagine
that if @cite{x} got ``all the way to infinity,'' then @cite{1 / x}
would go all the way to zero.  Similarly, when they say that
@samp{exp(inf) = inf}, they mean that @c{$e^x$}
@cite{exp(x)} grows without
bound as @cite{x} grows.  The symbol @samp{-inf} likewise stands
for an infinitely negative real value; for example, we say that
@samp{exp(-inf) = 0}.  You can have an infinity pointing in any
direction on the complex plane:  @samp{sqrt(-inf) = i inf}.
X
The same concept of limits can be used to define @cite{1 / 0}.  We
really want the value that @cite{1 / x} approaches as @cite{x}
approaches zero.  But if all we have is @cite{1 / 0}, we can't
tell which direction @cite{x} was coming from.  If @cite{x} was
positive and decreasing toward zero, then we should say that
@samp{1 / 0 = inf}.  But if @cite{x} was negative and increasing
toward zero, the answer is @samp{1 / 0 = -inf}.  In fact, @cite{x}
could be an imaginary number, giving the answer @samp{i inf} or
@samp{-i inf}.  Calc uses the special symbol @samp{uinf} to mean
@dfn{undirected infinity}, i.e., a value which is infinitely
large but with an unknown sign (or direction on the complex plane).
X
Calc actually has three modes that say how infinities are handled.
Normally, infinities never arise from calculations that didn't
already have them.  Thus, @cite{1 / 0} is treated simply as an
error and left unevaluated.  The @kbd{m i} (@code{calc-infinite-mode})
command (@pxref{Infinite Mode}) enables a mode in which
@cite{1 / 0} evaluates to @code{uinf} instead.  There is also
an alternative type of infinite mode which says to treat zeros
as if they were positive, so that @samp{1 / 0 = inf}.  While this
is less mathematically correct, it may be the answer you want in
some cases.
X
Since all infinities are ``as large'' as all others, Calc simplifies,
e.g., @samp{5 inf} to @samp{inf}.  Another example is
@samp{5 - inf = -inf}, where the @samp{-inf} is so large that
adding a finite number like five to it does not affect it.
Note that @samp{a - inf} also results in @samp{-inf}; Calc assumes
that variables like @code{a} always stand for finite quantities.
Just to show that infinities really are all the same size,
note that @samp{sqrt(inf) = inf^2 = exp(inf) = inf} in Calc's
notation.
X
It's not so easy to define some formulas like @samp{0 * inf} and
@samp{inf / inf}.  Depending on where these zeros and infinities
came from, the answer could be literally anything.  The latter
formula could be the limit of @cite{x / x} (giving a result of one),
or @cite{2 x / x} (giving two), or @cite{x^2 / x} (giving @code{inf}),
or @cite{x / x^2} (giving zero).  Calc uses the symbol @code{nan}
to represent such an @dfn{indeterminate} value.  (The name ``nan''
comes from analogy with the ``NAN'' concept of IEEE standard
arithmetic; it stands for ``Not A Number.''  This is somewhat of a
misnomer, since @code{nan} @emph{does} stand for some number or
infinity, it's just that @emph{which} number it stands for
cannot be determined.)  In Calc's notation, @samp{0 * inf = nan}
and @samp{inf / inf = nan}.  A few other common indeterminate
expressions are @samp{inf - inf} and @samp{inf ^ 0}.  Also,
@samp{0 / 0 = nan} if you have turned on ``infinite mode''
(as described above).
X
Infinities are especially useful as parts of @dfn{intervals}.
@xref{Interval Forms}.
X
@node Vectors and Matrices, Strings, Infinities, Data Types
@section Vectors and Matrices
X
@noindent
@cindex Vectors
@cindex Plain vectors
@cindex Matrices
The @dfn{vector} data type is flexible and general.  A vector is simply a
list of zero or more data objects.  When these objects are numbers, the
whole is a vector in the mathematical sense.  When these objects are
themselves vectors of equal (nonzero) length, the whole is a @dfn{matrix}.
A vector which is not a matrix is referred to here as a @dfn{plain vector}.
X
A vector is displayed as a list of comma-separated values enclosed in
square brackets:  @samp{[1, 2, 3]}.  Thus the following is a 2 row by
3 column matrix:  @samp{[[1, 2, 3], [4, 5, 6]]}.  Vectors, like complex
numbers, are entered as incomplete objects.  @xref{Incomplete Objects}.
During algebraic entry, vectors are entered all at once in the usual
brackets-and-commas form.  Matrices may be entered algebraically as nested
vectors, or using the shortcut notation @samp{[1, 2, 3; 4, 5, 6]},
with rows separated by semicolons.  The commas may usually be omitted
when entering vectors:  @samp{[1 2 3]}.  Curly braces may be used in
place of brackets: @samp{@{1, 2, 3@}}, but the commas are required in
this case.
X
Traditional vector and matrix arithmetic is also supported;
@pxref{Basic Arithmetic} and @pxref{Matrix Functions}.
Many other operations are applied to vectors element-wise.  For example,
the complex conjugate of a vector is a vector of the complex conjugates
of its elements.@refill
X
@tindex vec
Algebraic functions for building vectors include @samp{vec(a, b, c)}
to build @samp{[a, b, c]}, @samp{cvec(a, n, m)} to build an @c{$n\times m$}
@asis{@var{n}x@var{m}}
matrix of @samp{a}s, and @samp{index(n)} to build a vector of integers
from 1 to @samp{n}.
X
@node Strings, HMS Forms, Vectors and Matrices, Data Types
@section Strings
X
@noindent
@kindex "
@cindex Strings
@cindex Character strings
Character strings are not a special data type in the Calculator.
Rather, a string is represented simply as a vector all of whose
elements are integers in the range 0 to 255.  You can enter a string
at any time by pressing the @kbd{"} key.  Quotation marks and
backslashes are written @samp{\"} and @samp{\\}, respectively,
inside strings.  Other notations introduced by backslashes are:
X
@example
\a     7
\b     8
\e     27
\f     12
\n     10
\r     13
\t     9
\^@    0
\^a-z  1-26
\^[    27
\^\\   28
\^]    29
\^^    30
\^_    31
\^?    127
@end example
X
@noindent
Finally, a backslash followed by three octal digits produces any
character from its ASCII code.
X
@kindex d "
@pindex calc-display-strings
Strings are normally displayed in vector-of-integers form.  The
@w{@kbd{d "}} (@code{calc-display-strings}) command toggles a mode in
which any vectors of the appropriate form are displayed as quoted
strings instead.
X
The backslash notations shown above are also used for displaying
strings.  Characters 128 and above are not translated by Calc; unless
you have an Emacs modified for 8-bit fonts, these will show up in
backslash-octal-digits notation.  But for characters below 32, and
for character 127, Calc uses the backslash-letter combination if
there is one, or otherwise uses a @samp{\^} sequence.
X
The only Calc feature that uses strings is @dfn{compositions};
@pxref{Compositions}.  Strings also provide a convenient
way to do conversions between ASCII characters and integers.
X
@tindex string
There is a @code{string} function which provides a different display
format for strings.  Basically, @samp{string(@var{s})}, where @var{s}
is a vector of integers in the proper range, is displayed as the
corresponding string of characters with no surrounding quotations
marks or other modifications.  Thus @samp{string("ABC")} (or
@samp{string([65 66 67])}) will look like @samp{ABC} on the stack.
This happens regardless of whether @w{@kbd{d "}} has been used.  The
only way to turn it off is to use @kbd{d U} (unformatted language
mode) which will display @samp{string("ABC")} instead.
X
Control characters are displayed somewhat differently by @code{string}.
Characters below 32, and character 127, are shown using @samp{^} notation
(same as shown above, but without the backslash).  The quote and
backslash characters are left alone, as are characters 128 and above.
X
@tindex bstring
The @code{bstring} function is just like @code{string} except that
the resulting string is breakable across multiple lines if it doesn't
fit all on one line.  Potential break points occur at every space
character in the string.
X
@node HMS Forms, Date Forms, Strings, Data Types
@section HMS Forms
X
@noindent
@cindex Hours-minutes-seconds forms
@cindex Degrees-minutes-seconds forms
@dfn{HMS} stands for Hours-Minutes-Seconds; when used as an angular
argument, the interpretation is Degrees-Minutes-Seconds.  All functions
that operate on angles accept HMS forms.  These are interpreted as
degrees regardless of the current angular mode.  It is also possible to
use HMS as the angular mode so that calculated angles are expressed in
degrees, minutes, and seconds.
X
@kindex @@
@kindex ' (HMS forms)
@kindex " (HMS forms)
@kindex h (HMS forms)
@kindex o (HMS forms)
@kindex m (HMS forms)
@kindex s (HMS forms)
The default format for HMS values is
@samp{@var{hours}@@ @var{mins}' @var{secs}"}.  During entry, the letters
@samp{h} (for ``hours'') or
@samp{o} (approximating the ``degrees'' symbol) are accepted as well as
@samp{@@}, @samp{m} is accepted in place of @samp{'}, and @samp{s} is
accepted in place of @samp{"}.
The @var{hours} value is an integer (or integer-valued float).
The @var{mins} value is an integer or integer-valued float between 0 and 59.
The @var{secs} value is a real number between 0 (inclusive) and 60
(exclusive).  A positive HMS form is interpreted as @var{hours} +
@var{mins}/60 + @var{secs}/3600.  A negative HMS form is interpreted
as - @var{hours} - @var{mins}/60 - @var{secs}/3600.
Display format for HMS forms is quite flexible.  @xref{HMS Formats}.@refill
X
HMS forms can be added and subtracted.  When they are added to numbers,
the numbers are interpreted according to the current angular mode.  HMS
forms can also be multiplied and divided by real numbers.  Dividing
two HMS forms produces a real-valued ratio of the two angles.
X
@pindex calc-time
@cindex Time of day
Just for kicks, @code{calc-time} pushes the current time of day on
the stack as an HMS form.
X
@node Date Forms, Modulo Forms, HMS Forms, Data Types
@section Date Forms
X
@noindent
@cindex Date forms
A @dfn{date form} represents a date and possibly an associated time.
Simple date arithmetic is supported:  Adding a number to a date
produces a new date shifted by that many days; adding an HMS form to
a date shifts it by that many hours.  Subtracting two date forms
computes the number of days between them (represented as a simple
number).  Many other operations, such as multiplying two date forms,
are nonsensical and are not allowed by Calc.
X
Date forms are entered and displayed enclosed in @samp{< >} brackets.
The default format is, e.g., @samp{<Wed Jan 9, 1991>} for dates,
or @samp{<3:32:20pm Wed Jan 9, 1991>} for dates with times.
Input is flexible; date forms can be entered in any of the usual
notations for dates and times.  @xref{Date Formats}.
X
Date forms are stored internally as numbers, specifically the number
of days since midnight on the morning of January 1 of the year 1 AD.
If the internal number is an integer, the form represents a date only;
if the internal number is a fraction or float, the form represents
a date and time.  For example, @samp{<6:00am Wed Jan 9, 1991>}
is represented by the number 726842.25.  The standard precision of
12 decimal digits is enough to ensure that a (reasonable) date and
time can be stored without roundoff error.
X
If the current precision is greater than 12, date forms will keep
additional digits in the seconds portion.  For example, if the
precision is 15, the seconds will keep three digits after the
decimal point.  Decreasing the precision below 12 may cause the
time part of a date form to become inaccurate.  This can also happen
if astronomically high years are used, though this will not be an
issue in everyday (or even everymillenium) use.  Note that date
forms without times are stored as exact integers, so roundoff is
never an issue for them.
X
You can use the @code{calc-pack} and @code{calc-unpack} commands
to get at the numerical representation of a date form.
@xref{Packing and Unpacking}.
X
Date forms can go arbitrarily far into the future or past.  Negative
year numbers represent years BC.  Calc uses a combination of the
Gregorian and Julian calendars, following the history of Great
Britain and the British colonies.  This is the same calendar that
is used by the @file{cal} program in most Unix implementations.
X
@cindex Julian calendar
@cindex Gregorian calendar
Some historical background:  The Julian calendar was created by
Julius Caesar in the year 46 BC as an attempt to fix the gradual
drift caused by the lack of leap years in the calendar used
until that time.  The Julian calendar introduced an extra day in
all years divisible by four.  After some initial confusion, the
calendar was adopted around the year we call 8 AD.  Some centuries
later it became apparent that the Julian year of 365.25 days was
itself not quite right.  In 1582 Pope Gregory XIII introduced the
Gregorian calendar, which added the new rule that years divisible
by 100, but not by 400, were not to be considered leap years
despite being divisible by four.  Many countries delayed adoption
of the Gregorian calendar because of religious differences;
in Britain it was put off until the year 1752, by which time
the Julian calendar had fallen eleven days behind the true
seasons.  So the switch to the Gregorian calendar in early
September 1752 introduced a discontinuity:  The day after
Sep 2, 1752 is Sep 14, 1752.  Calc follows this convention.
To take another example, Russia waited until 1918 before
adopting the new calendar, and thus needed to remove thirteen
days (between Feb 1, 1918 and Feb 14, 1918).  This means that
Calc's reckoning will be inconsistent with Russian history between
1752 and 1918, and similarly for various other countries.
X
Today's timekeepers introduce an occasional ``leap second'' as
well, but Calc does not take these minor effects into account.
(If it did, it would have to report a non-integer number of days
between, say, @samp{<12:00am Mon Jan 1, 1900>} and
@samp{<12:00am Sat Jan 1, 2000>}.)
X
Calc uses the Julian calendar for all dates before the year 1752,
including dates BC when the Julian calendar technically had not
yet been invented.  Thus the claim that day number @i{-10000} is
called ``August 16, 28 BC'' should be taken with a grain of salt.
X
Please note that there is no ``year 0''; the day before
@samp{<Sat Jan 1, +1>} is @samp{<Fri Dec 31, -1>}.  These are
days 0 and @i{-1} respectively in Calc's internal numbering scheme.
X
@cindex Julian day counting
Another day counting system in common use is, confusingly, also
called ``Julian.''  It was invented in 1583 by Joseph Justus
Scaliger, who named it in honor of his father Julius Caesar
Scaliger.  For obscure reasons he chose to start his day
numbering on Jan 1, 4713 BC at noon, which in Calc's scheme
is @i{-1721423.5} (recall that Calc starts at midnight instead
of noon).  Thus to convert a Calc date code obtained by
unpacking a date form into a Julian day number, simply add
1721423.5.  The Julian code for @samp{6:00am Jan 9, 1991}
is 2448265.75.  The built-in @kbd{t J} command performs
this conversion for you.
X
@cindex Unix time format
The Unix operating system measures time as an integer number of
seconds since midnight, Jan 1, 1970.  To convert a Calc date
value into a Unix time stamp, first subtract 719164 (the code
for @samp{<Jan 1, 1970>}), then multiply by 86400 (the number of
seconds in a day) and press @kbd{R} to round to the nearest
integer.  If you have a date form, you can simply subtract the
day @samp{<Jan 1, 1970>} instead of unpacking and subtracting
719164.  Likewise, divide by 86400 and add @samp{<Jan 1, 1970>}
to convert from Unix time to a Calc date form.  (Note that
Unix normally maintains the time in the GMT time zone; you may
need to subtract five hours to get New York time, or eight hours
for California time.  The same is usually true of Julian day
counts.)  The built-in @kbd{t U} command performs these
conversions.
X
@node Modulo Forms, Error Forms, Date Forms, Data Types
@section Modulo Forms
X
@noindent
@cindex Modulo forms
A @dfn{modulo form} is a real number which is taken modulo (i.e., within
an integer multiple of) some value @cite{M}.  Arithmetic modulo @cite{M}
often arises in number theory.  Modulo forms are written
`@i{a} @t{mod} @i{M}',
where @cite{a} and @cite{M} are real numbers or HMS forms, and
@c{$0 \le a < M$}
@cite{0 <= a < @var{M}}.
In many applications @cite{a} and @cite{M} will be
integers but this is not required.@refill
X
Modulo forms are not to be confused with the modulo operator @samp{%}.
The expression @samp{27 % 10} means to compute 27 modulo 10 to produce
the result 7.  Further computations treat this 7 as just a regular integer.
The expression @samp{27 mod 10} produces the result @samp{7 mod 10};
further computations with this value are again reduced modulo 10 so that
the result always lies in the desired range.
X
When two modulo forms with identical @cite{M}'s are added or multiplied,
the Calculator simply adds or multiplies the values, then reduces modulo
@cite{M}.  If one argument is a modulo form and the other a plain number,
the plain number is treated like a compatible modulo form.  It is also
possible to raise modulo forms to powers; the result is the value raised
to the power, then reduced modulo @cite{M}.  (When all values involved
are integers, this calculation is done much more efficiently than
actually computing the power and then reducing.)
X
@cindex Modulo division
Two modulo forms `@i{a} @t{mod} @i{M}' and `@i{b} @t{mod} @i{M}'
can be divided if @cite{a}, @cite{b}, and @cite{M} are all
integers.  The result is the modulo form which, when multiplied by
`@i{b} @t{mod} @i{M}', produces `@i{a} @t{mod} @i{M}'.  If
SHAR_EOF
true || echo 'restore of calc.texinfo failed'
fi
echo 'End of  part 37'
echo 'File calc.texinfo is continued in part 38'
echo 38 > _shar_seq_.tmp
exit 0
exit 0 # Just in case...
--
Kent Landfield                   INTERNET: [e-mail]
Sterling Software, IMD           UUCP:     uunet!sparky!kent
Phone:    [phone]         FAX:      [phone]
Please send comp.sources.misc-related mail to [e-mail].