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

Text File | 1991-11-01 | 55.5 KB | 1,281 lines

Newsgroups: comp.sources.misc
From: [e-mail] (David Gillespie)
Subject:  v24i089:  gnucalc - GNU Emacs Calculator, v2.00, Part41/56
Message-ID: <[e-mail]>
X-Md4-Signature: 87c4d2c362e0f34785231a6a84a2e74d
Date: Fri, 1 Nov 1991 18:36:45 GMT
Approved: [e-mail]

Submitted-by: [e-mail] (David Gillespie)
Posting-number: Volume 24, Issue 89
Archive-name: gnucalc/part41
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" != 41; 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' &&
(This is entirely equivalent to @kbd{125 RET 1:3 ^}.)
X
@kindex %
@pindex calc-mod
@tindex %
The @kbd{%} (@code{calc-mod}) command performs a ``modulo'' (or ``remainder'')
operation.  Mathematically, @samp{a%b = a - floor(a/b)*b}, and is defined
for all real numbers @cite{a} and @cite{b} (except @cite{b=0}).  For
positive @cite{b}, the result will always be between 0 (inclusive) and
@cite{b} (exclusive).  Modulo does not work for HMS forms and error forms.
If @cite{a} is a modulo form, its modulo is changed to @cite{b}, which
must be positive real number.
X
@kindex \
@pindex calc-idiv
@tindex idiv
@tindex \
The @kbd{\} (@code{calc-idiv}) command divides two numbers on the stack
to produce an integer result.  It is equivalent to dividing with
@key{/}, then rounding down with @kbd{F} (@code{calc-floor}), only a bit
more convenient and efficient.  Also, since it is an all-integer
operation when the arguments are integers, it avoids problems that
@kbd{/ F} would have with floating-point roundoff.
X
@kindex :
@pindex calc-fdiv
@tindex fdiv
The @kbd{:} (@code{calc-fdiv}) command [@code{fdiv} function in a formula]
divides the two integers on the top of the stack to produce a fractional
result.  This is a convenient shorthand for enabling Fraction Mode (with
@kbd{m f}) temporarily and using @samp{/}.  Note that during numeric entry
the @kbd{:} key is interpreted as a fraction separator, so to divide 8 by 6
you would have to type @kbd{8 @key{RET} 6 @key{RET} :}.  (Of course, in
this case, it would be much easier simply to enter the fraction directly
as @kbd{8:6 @key{RET}}!)
X
@kindex n
@pindex calc-change-sign
The @kbd{n} (@code{calc-change-sign}) command negates the number on the top
of the stack.  It works on numbers, vectors and matrices, HMS forms, date
forms, error forms, intervals, and modulo forms.
X
@kindex A
@pindex calc-abs
@tindex abs
The @kbd{A} (@code{calc-abs}) [@code{abs}] command computes the absolute
value of a number.  The result of @code{abs} is always a nonnegative
real number:  With a complex argument, it computes the complex magnitude.
With a vector or matrix argument, it computes the Frobenius norm, i.e.,
the square root of the sum of the squares of the absolute values of the
elements.  The absolute value of an error form is defined by replacing
the mean part with its absolute value and leaving the error part the same.
The absolute value of a modulo form is undefined.  The absolute value of
an interval is defined in the obvious way.
X
@kindex f A
@pindex calc-abssqr
@tindex abssqr
The @kbd{f A} (@code{calc-abssqr}) [@code{abssqr}] command computes the
absolute value squared of a number, vector or matrix, or error form.
X
@kindex f s
@pindex calc-sign
@tindex sign
The @kbd{f s} (@code{calc-sign}) [@code{sign}] command returns 1 if its
argument is positive, @i{-1} if its argument is negative, or 0 if its
argument is zero.  In algebraic form, you can also write @samp{sign(a,x)}
which evaluates to @samp{x * sign(a)}, i.e., either @samp{x}, @samp{-x}, or
zero depending on the sign of @samp{a}.
X
@kindex &
@pindex calc-inv
@tindex inv
@cindex Reciprocal
The @kbd{&} (@code{calc-inv}) [@code{inv}] command computes the
reciprocal of a number, i.e., @cite{1 / x}.  Operating on a square
matrix, it computes the inverse of that matrix.
X
@kindex Q
@pindex calc-sqrt
@tindex sqrt
The @kbd{Q} (@code{calc-sqrt}) [@code{sqrt}] command computes the square
root of a number.  For a negative real argument, the result will be a
complex number whose form is determined by the current Polar Mode.
X
@kindex f h
@pindex calc-hypot
@tindex hypot
The @kbd{f h} (@code{calc-hypot}) [@code{hypot}] command computes the square
root of the sum of the squares of two numbers.  That is, @samp{hypot(a,b)}
is the length of the hypotenuse of a right triangle with sides @cite{a}
and @cite{b}.  If the arguments are complex numbers, their squared
magnitudes are used.
X
@kindex f Q
@pindex calc-isqrt
@tindex isqrt
The @kbd{f Q} (@code{calc-isqrt}) [@code{isqrt}] command computes the
integer square root of an integer.  This is the true square root of the
number, rounded down to an integer.  For example, @samp{isqrt(10)}
produces 3.  Note that, like @kbd{\} [@code{idiv}], this uses exact
integer arithmetic throughout to avoid roundoff problems.  If the input
is a floating-point number or other non-integer value, this is exactly
the same as @samp{floor(sqrt(x))}.
X
@kindex f n
@kindex f x
@pindex calc-min
@tindex min
@pindex calc-max
@tindex max
The @kbd{f n} (@code{calc-min}) [@code{min}] and @kbd{f x} (@code{calc-max})
[@code{max}] commands take the minimum or maximum of two real numbers,
respectively.  These commands also work on HMS forms, date forms,
intervals, and infinities.  (In algebraic expressions, these functions
take any number of arguments and return the maximum or minimum among
all the arguments.)@refill
X
@kindex f M
@kindex f X
@pindex calc-mant-part
@tindex mant
@pindex calc-xpon-part
@tindex xpon
The @kbd{f M} (@code{calc-mant-part}) [@code{mant}] function extracts
the ``mantissa'' part @cite{m} of its floating-point argument; @kbd{f X}
(@code{calc-xpon-part}) [@code{xpon}] extracts the ``exponent'' part
@cite{e}.  The original number is equal to @c{$m \times 10^e$}
@cite{m * 10^e},
where @cite{m} is in the interval @samp{[1.0 ..@: 10.0)} except that
@cite{m=e=0} if the original number is zero.  For integers
and fractions, @code{mant} returns the number unchanged and @code{xpon}
returns zero.  The @kbd{v u} (@code{calc-unpack}) command can also be
used to ``unpack'' a floating-point number; this produces an integer
mantissa and exponent, with the constraint that the mantissa is not a
a multiple of ten (again except for the @cite{m=e=0} case).@refill
X
@kindex f S
@pindex calc-scale-float
@tindex scf
The @kbd{f S} (@code{calc-scale-float}) [@code{scf}] function scales a number
by a given power of ten.  Thus, @samp{scf(mant(x), xpon(x)) = x} for any
real @samp{x}.  The second argument must be an integer, but the first
may actually be any numeric value.  For example, @samp{scf(5,-2) = 0.05}
or @samp{1:20} depending on the current Fraction Mode.@refill
X
@kindex f [
@kindex f ]
@pindex calc-decrement
@pindex calc-increment
@tindex decr
@tindex incr
The @kbd{f [} (@code{calc-decrement}) [@code{decr}] and @kbd{f ]}
(@code{calc-increment}) [@code{incr}] functions decrease or increase
a number by one unit.  For integers, the effect is obvious.  For
floating-point numbers, the change is by one unit in the last place.
For example, incrementing @samp{12.3456} when the current precision
is 6 digits yields @samp{12.3457}.  If the current precision had been
8 digits, the result would have been @samp{12.345601}.  Incrementing
@samp{0.0} produces @c{$10^{-p}$}
@cite{10^-p}, where @cite{p} is the current
precision.  These operations are defined only on integers and floats.
With numeric prefix arguments, they change the number by @cite{n} units.
X
Note that incrementing followed by decrementing, or vice-versa, will
almost but not quite always cancel out.  Suppose the precision is
6 digits and the number @samp{9.99999} is on the stack.  Incrementing
will produce @samp{10.0000}; decrementing will produce @samp{9.9999}.
One digit has been dropped.  This is an unavoidable consequence of the
way floating-point numbers work.
X
Incrementing a date/time form adjusts it by a certain number of seconds.
Incrementing a pure date form adjusts it by a certain number of days.
X
@node Integer Truncation, Complex Number Functions, Basic Arithmetic, Arithmetic
@section Integer Truncation
X
@noindent
There are four commands for truncating a real number to an integer,
differing mainly in their treatment of negative numbers.  All of these
commands have the property that if the argument is an integer, the result
is the same integer.  An integer-valued floating-point argument is converted
to integer form.
X
If you press @kbd{H} (@code{calc-hyperbolic}) first, the result will be
expressed as an integer-valued floating-point number.
X
@cindex Integer part of a number
@kindex F
@kindex H F
@pindex calc-floor
@tindex floor
@tindex ffloor
The @kbd{F} (@code{calc-floor}) [@code{floor} or @code{ffloor}] command
truncates a real number to the next lower integer, i.e., toward minus
infinity.  Thus @kbd{3.6 F} produces 3, but @kbd{_3.6 F} produces
-4.@refill
X
@kindex I F
@kindex H I F
@pindex calc-ceiling
@tindex ceil
@tindex fceil
The @kbd{I F} (@code{calc-ceiling}) [@code{ceil} or @code{fceil}]
command truncates toward positive infinity.  Thus @kbd{3.6 I F} produces
4, and @kbd{_3.6 I F} produces @i{-3}.@refill
X
@kindex R
@kindex H R
@pindex calc-round
@tindex round
@tindex fround
The @kbd{R} (@code{calc-round}) [@code{round} or @code{fround}] command
rounds to the nearest integer.  When the fractional part is .5 exactly,
this command rounds away from zero.  (All other rounding in the
Calculator uses this convention as well.)  Thus @kbd{3.5 R} produces 4
but @kbd{3.4 R} produces 3; @kbd{_3.5 R} produces @i{-4}.@refill
X
@kindex I R
@kindex H I R
@pindex calc-trunc
@tindex trunc
@tindex ftrunc
The @kbd{I R} (@code{calc-trunc}) [@code{trunc} or @code{ftrunc}]
command truncates toward zero.  In other words, it ``chops off''
everything after the decimal point.  Thus @kbd{3.6 I R} produces 3 and
@kbd{_3.6 I R} produces @i{-3}.@refill
X
These functions may not be applied meaningfully to error forms, but they
do work for intervals.  As a convenience, applying @code{floor} to a
modulo form floors the value part of the form.  Applied to a vector,
these functions operate on all elements of the vector one by one.
Applied to a date form, they operate on the internal numerical
representation of dates, converting a date/time form into a pure date.
X
@tindex rounde
@tindex roundu
@tindex frounde
@tindex froundu
There are two more rounding functions which can only be entered in
algebraic notation.  The @code{roundu} function is like @code{round}
except that it rounds up, toward plus infinity, when the fractional
part is .5.  This distinction matters only for negative arguments.
Also, @code{rounde} rounds to an even number in the case of a tie,
rounding up or down as necessary.  For example, @samp{rounde(3.5)} and
@samp{rounde(4.5)} both return 4, but @samp{rounde(5.5)} returns 6.
The advantage of round-to-even is that the net error due to rounding
after a long calculation tends to cancel out to zero.  An important
subtle point here is that the number being fed to @code{rounde} will
already have been rounded to the current precision before @code{rounde}
begins.  For example, @samp{rounde(2.500001)} with a current precision
of 6 will incorrectly, or at least surprisingly, yield 2 because the
argument will first have been rounded down to @cite{2.5} (which
@code{rounde} sees as an exact tie between 2 and 3).
X
Each of these functions, when written in algebraic formulas, allows
a second argument which specifies the number of digits after the
decimal point to keep.  For example, @samp{round(123.4567, 2)} will
produce the answer 123.46, and @samp{round(123.4567, -1)} will
produce 120 (i.e., the cutoff is one digit to the @emph{left} of
the decimal point).  A second argument of zero is equivalent to
no second argument at all.
X
@cindex Fractional part of a number
To compute the fractional part of a number (i.e., the amount which, when
added to `@t{floor(}@i{N}@t{)}', will produce @cite{N}) just take @cite{N}
modulo 1 using the @code{%} command.@refill
X
Note also the @kbd{\} (integer quotient), @kbd{f I} (integer logarithm),
and @kbd{f Q} (integer square root) commands, which are analogous to
@kbd{\}, @kbd{B}, and @kbd{Q}, respectively, except that they take integer
arguments and return the result rounded down to an integer.
X
@node Complex Number Functions, Conversions, Integer Truncation, Arithmetic
@section Complex Number Functions
X
@noindent
@kindex J
@pindex calc-conj
@tindex conj
The @kbd{J} (@code{calc-conj}) [@code{conj}] command computes the
complex conjugate of a number.  For complex number @cite{a+bi}, the
complex conjugate is @cite{a-bi}.  If the argument is a real number,
this command leaves it the same.  If the argument is a vector or matrix,
this command replaces each element by its complex conjugate.
X
@kindex G
@pindex calc-argument
@tindex arg
The @kbd{G} (@code{calc-argument}) [@code{arg}] command computes the
``argument'' or polar angle of a complex number.  For a number in polar
notation, this is simply the second component of the pair
`@t{(}@i{r}@t{;}@c{$\theta$}
@i{theta}@t{)}'.
The result is expressed according to the current angular mode and will
be in the range @i{-180} degrees (exclusive) to @i{+180} degrees
(inclusive), or the equivalent range in radians.@refill
X
@pindex calc-imaginary
The @code{calc-imaginary} command multiplies the number on the
top of the stack by the imaginary number @cite{i = (0,1)}.  This
command is not normally bound to a key in Calc, but it is available
on the @key{IMAG} button in Keypad Mode.
X
@kindex f r
@pindex calc-re
@tindex re
The @kbd{f r} (@code{calc-re}) [@code{re}] command replaces a complex number
by its real part.  This command has no effect on real numbers.  (As an
added convenience, @code{re} applied to a modulo form extracts
the value part.)@refill
X
@kindex f i
@pindex calc-im
@tindex im
The @kbd{f i} (@code{calc-im}) [@code{im}] command replaces a complex number
by its imaginary part; real numbers are converted to zero.  With a vector
or matrix argument, these functions operate element-wise.@refill
X
@kindex v p (complex)
@pindex calc-pack
The @kbd{v p} (@code{calc-pack}) command can pack the top two numbers on
the the stack into a composite object such as a complex number.  With
a prefix argument of @i{-1}, it produces a rectangular complex number;
with an argument of @i{-2}, it produces a polar complex number.
(Also, @pxref{Building Vectors}.)
X
@kindex v u (complex)
@pindex calc-unpack
The @kbd{v u} (@code{calc-unpack}) command takes the complex number
(or other composite object) on the top of the stack and unpacks it
into its separate components.
X
@node Conversions, Date Arithmetic, Complex Number Functions, Arithmetic
@section Conversions
X
@noindent
The commands described in this section are two-key sequences beginning with
the letter @kbd{c}.
X
@kindex c f
@pindex calc-float
@tindex pfloat
The @kbd{c f} (@code{calc-float}) [@code{pfloat}] command converts the
number on the top of the stack to floating-point form.  For example,
@cite{23} is converted to @cite{23.0}, @cite{3:2} is converted to
@cite{1.5}, and @cite{2.3} is left the same.  If the value is a composite
object such as a complex number or vector, each of the components is
converted to floating-point.  If the value is a formula, all numbers
in the formula are converted to floating-point.  Note that depending
on the current floating-point precision, conversion to floating-point
format may lose information.@refill
X
As a special exception, integers which appear as powers or subscripts
are not floated by @code{pfloat}.  If you really want to float a power,
you can use a @kbd{j s} command to select the power, then use @kbd{c f}.
Because @kbd{c f} cannot examine the formula outside of the selection,
it does not notice that the thing being floated is a power.
@xref{Selecting Subformulas}.
X
The normal @kbd{c f} command is ``pervasive'' in the sense that it
applies to all numbers throughout the formula.  The @code{pfloat}
algebraic function never stays around in a formula; @samp{pfloat(a + 1)}
changes to @samp{a + 1.0} as soon as it is evaluated.
X
@kindex H c f
@tindex float
With the Hyperbolic flag, @kbd{H c f} [@code{float}] operates
only on the number or vector of numbers at the top level of its
argument.  Thus, @samp{float(1)} is 1.0, but @samp{float(a + 1)}
is left unevaluated because its argument is not a number.
X
You should use @kbd{H c f} if you wish to guarantee that the final
value, once all the variables have been assigned, is a float; you
would use @kbd{c f} if you wish to do the conversion on the numbers
that appear right now.
X
@kindex c F
@pindex calc-fraction
@tindex pfrac
The @kbd{c F} (@code{calc-fraction}) [@code{pfrac}] command converts a
floating-point number into a fractional approximation.  By default, it
produces a fraction whose decimal representation is the same as the
input number, to within the current precision.  You can also give a
numeric prefix argument to specify a tolerance, either directly, or,
if the prefix argument is zero, by using the number on top of the stack
as the tolerance.  If the tolerance is a positive integer, the fraction
is correct to within that many significant figures.  If the tolerance is
a non-positive integer, it specifies how many digits fewer than the current
precision to use.  If the tolerance is a floating-point number, the
fraction is correct to within that absolute amount.
X
@kindex H c F
@tindex frac
The @code{pfrac} function is pervasive, like @code{pfloat}.
There is also a non-pervasive version, @kbd{H c F} [@code{frac}],
which is analogous to @kbd{H c f} discussed above.
X
@kindex c d
@pindex calc-to-degrees
@tindex deg
The @kbd{c d} (@code{calc-to-degrees}) [@code{deg}] command converts a
number into degrees form.  The value on the top of the stack may be an
HMS form (interpreted as degrees-minutes-seconds), or a real number which
will be interpreted in radians regardless of the current angular mode.@refill
X
@kindex c r
@pindex calc-to-radians
@tindex rad
The @kbd{c r} (@code{calc-to-radians}) [@code{rad}] command converts an
HMS form or angle in degrees into an angle in radians.
X
@kindex c h
@pindex calc-to-hms
@tindex hms
The @kbd{c h} (@code{calc-to-hms}) [@code{hms}] command converts a real
number, interpreted according to the current angular mode, to an HMS
form describing the same angle.  In algebraic notation, the @code{hms}
function also accepts three arguments: @samp{hms(@var{h}, @var{m}, @var{s})}.
(The three-argument version is independent of the current angular mode.)
X
@pindex calc-from-hms
The @code{calc-from-hms} command converts the HMS form on the top of the
stack into a real number according to the current angular mode.
X
@kindex c p
@kindex I c p
@pindex calc-polar
@tindex polar
@tindex rect
The @kbd{c p} (@code{calc-polar}) command converts the complex number on
the top of the stack from polar to rectangular form, or from rectangular
to polar form, whichever is appropriate.  Real numbers are left the same.
This command is equivalent to the @code{rect} or @code{polar}
functions in algebraic formulas, depending on the direction of
conversion.  (It uses @code{polar}, except that if the argument is
already a polar complex number, it uses @code{rect} instead.  The
@kbd{I c p} command always uses @code{rect}.)@refill
X
@kindex c c
@pindex calc-clean
@tindex pclean
The @kbd{c c} (@code{calc-clean}) [@code{pclean}] command ``cleans'' the
number on the top of the stack.  Floating point numbers are re-rounded
according to the current precision.  Polar numbers whose angular
components have strayed from the @i{-180} to @i{+180} degree range
are normalized.  (Note that results will be undesirable if the current
angular mode is different from the one under which the number was
produced!)  Integers and fractions are generally unaffected by this
operation.  Vectors and formulas are cleaned by cleaning each component
number (i.e., pervasively).@refill
X
If the simplification mode is set below the default level, it is raised
to the default level for the purposes of this command.  Thus, @kbd{c c}
applies the default simplifications even if their automatic application
is disabled.  @xref{Simplification Modes}.
X
@cindex Roundoff errors, correcting
A numeric prefix argument to @kbd{c c} sets the floating-point precision
to that value for the duration of the command.  A positive prefix (of at
least 3) sets the precision to the specified value; a negative or zero
prefix decreases the precision by the specified amount.
X
@kindex c 0-9
@pindex calc-clean-num
The keystroke sequences @kbd{c 0} through @kbd{c 9} are equivalent
to @kbd{c c} with the corresponding negative prefix argument.  If roundoff
errors have changed 2.0 into 1.999999, typing @kbd{c 1} to clip off one
decimal place often conveniently does the trick.
X
The @kbd{c c} command with a numeric prefix argument, and the @kbd{c 0}
through @kbd{c 9} commands, also ``clip'' very small floating-point
numbers to zero.  If the exponent is less than or equal to the negative
of the specified precision, the number is changed to 0.0.  For example,
if the current precision is 12, then @kbd{c 2} changes the vector
@samp{[1e-8, 1e-9, 1e-10, 1e-11]} to @samp{[1e-8, 1e-9, 0., 0.]}.
Numbers this small generally arise from roundoff noise.
X
If the numbers you are using really are legitimately this small,
you should avoid using the @kbd{c 0} through @kbd{c 9} commands.
(The plain @kbd{c c} command rounds to the current precision but
does not clip small numbers.)
X
One more property of @kbd{c 0} through @kbd{c 9}, and of @kbd{c c} with
a prefix argument, is that integer-valued floats are converted to
plain integers, so that @kbd{c 1} on @samp{[1., 1.5, 2., 2.5, 3.]}
produces @samp{[1, 1.5, 2, 2.5, 3]}.  This is not done for huge
numbers (@samp{1e100} is techinically an integer-valued float, but
you wouldn't want it automatically converted to a 100-digit integer).
X
@kindex H c 0-9
@kindex H c c
@tindex clean
With the Hyperbolic flag, @kbd{H c c} and @kbd{H c 0} through @kbd{H c 9}
operate non-pervasively [@code{clean}].
X
@node Date Arithmetic, Financial Functions, Conversions, Arithmetic
@section Date Arithmetic
X
@noindent
@cindex Date arithmetic, additional functions
The commands described in this section perform various conversions
and calculations involving date forms (@pxref{Date Forms}).  They
use the @kbd{t} (for time/date) prefix key followed by shifted
letters.
X
The simplest date arithmetic is done using the regular @kbd{+} and @kbd{-}
commands.  In particular, adding a number to a date form advances the
date form by a certain number of days; adding an HMS form to a date
form advances the date by an amount of time; and subtracting two
date forms produces a difference measured in days.  The commands
described here provide additional, more specialized operations on dates.
X
Many of these commands accept a numeric prefix argument; if you give
plain @kbd{C-u} as the prefix, these commands will instead take the
additional argument from the top of the stack.
X
@menu
* Date Conversions::
* Date Functions::
* Time Zones::
@end menu
X
@node Date Conversions, Date Functions, Date Arithmetic, Date Arithmetic
@subsection Date Conversions
X
@noindent
@kindex t D
@pindex calc-date
@tindex date
The @kbd{t D} (@code{calc-date}) [@code{date}] command converts a
date form into a number, measured in days since Jan 1, 1 AD.  The
result will be an integer if @var{date} is a pure date form, or a
fraction or float if @var{date} is a date/time form.  Or, if its
argument is a number, it converts this number into a date form.
X
With a numeric prefix argument, @kbd{t D} takes that many objects
(up to six) from the top of the stack and interprets them in one
of the following ways:
X
The @samp{date(@var{year}, @var{month}, @var{day})} function
builds a pure date form out of the specified year, month, and
day, which must all be integers.  @var{Year} is a year number,
such as 1991 (@emph{not} the same as 91!).  @var{Month} must be
an integer in the range 1 to 12; @var{day} must be in the range
1 to 31.  If the specified month has fewer than 31 days and
@var{day} is too large, the equivalent day in the following
month will be used.
X
The @samp{date(@var{month}, @var{day})} function builds a
pure date form using the current year, as determined by the
real-time clock.
X
The @samp{date(@var{year}, @var{month}, @var{day}, @var{hms})}
function builds a date/time form using an @var{hms} form.
X
The @samp{date(@var{year}, @var{month}, @var{day}, @var{hour},
@var{minute}, @var{second})} function builds a date/time form.
@var{hour} should be an integer in the range 0 to 23;
@var{minute} should be an integer in the range 0 to 59;
@var{second} should be any real number in the range @samp{[0 .. 60)}.
The last two arguments default to zero if omitted.
X
@kindex t J
@pindex calc-julian
@tindex julian
@cindex Julian day counts, conversions
The @kbd{t J} (@code{calc-julian}) [@code{julian}] command converts
a date form into a Julian day count, which is the number of days
since noon on Jan 1, 4713 BC.  A pure date is converted to an integer
Julian count representing noon of that day.  A date/time form is
converted to an exact floating-point Julian count, adjusted to
interpret the date form in the current time zone but the Julian
day count in Greenwich Mean Time.  A numeric prefix argument allows
you to specify the time zone; @pxref{Time Zones}.  Use a prefix of
zero to suppress the time zone adjustment.  Note that pure date forms
are never time-zone adjusted.
X
This command can also do the opposite conversion, from a Julian day
count (either an integer day, or a floating-point day and time in
the GMT zone), into a pure date form or a date/time form in the
current or specified time zone.
X
@kindex t U
@pindex calc-unix-time
@tindex unixtime
@cindex Unix time format, conversions
The @kbd{t U} (@code{calc-unix-time}) [@code{unixtime}] command
converts a date form into a Unix time value, which is the number of
seconds since midnight on Jan 1, 1970, or vice-versa.  The numeric result
will be an integer if the current precision is 12 or less; for higher
precisions, the result may be a float with (@var{precision} - 12)
digits after the decimal.  Just as for @kbd{t J}, the numeric time
is interpreted in the GMT time zone and the date form is interpreted
in the current or specified zone.  Some systems use Unix-like
numbering but with the local time zone; give a prefix of zero to
suppress the adjustment if so.
X
@kindex t C
@pindex calc-convert-time-zones
@tindex tzconv
@cindex Time Zones, converting between
The @kbd{t C} (@code{calc-convert-time-zones}) [@code{tzconv}]
command converts a date form from one time zone to another.  You
are prompted for each time zone name in turn; you can answer with
any suitable Calc time zone expression (@pxref{Time Zones}).
If you answer either prompt with a blank line, the local time
zone is used for that prompt.  You can also answer the first
prompt with @kbd{$} to take the two time zone names from the
stack (and the date to be converted from the third stack level).
X
@node Date Functions, Time Zones, Date Conversions, Date Arithmetic
@subsection Date Functions
X
@noindent
@kindex t N
@pindex calc-now
@tindex now
The @kbd{t N} (@code{calc-now}) [@code{now}] command pushes the
current date and time on the stack as a date form.  The time is
reported in terms of the specified time zone; with no numeric prefix
argument, @kbd{t N} reports for the current time zone.
X
@kindex t P
@pindex calc-date-part
The @kbd{t P} (@code{calc-date-part}) command extracts one part
of a date form.  The prefix argument specifies the part; with no
argument, this command prompts for a part code from 1 to 9.
The various part codes are described in the following paragraphs.
X
@tindex year
The @kbd{M-1 t P} [@code{year}] function extracts the year number
from a date form as an integer, e.g., 1991.  This and the
following functions will also accept a real number for an
argument, which is interpreted as a standard Calc day number.
Note that this function will never return zero, since the year
1 BC immediately precedes the year 1 AD.
X
@tindex month
The @kbd{M-2 t P} [@code{month}] function extracts the month number
from a date form as an integer in the range 1 to 12.
X
@tindex day
The @kbd{M-3 t P} [@code{day}] function extracts the day number
from a date form as an integer in the range 1 to 31.
X
@tindex hour
The @kbd{M-4 t P} [@code{hour}] function extracts the hour from
a date form as an integer in the range 0 (midnight) to 23.  Note
that 24-hour time is always used.  This returns zero for a pure
date form.  This function (and the following two) also accept
HMS forms as input.
X
@tindex minute
The @kbd{M-5 t P} [@code{minute}] function extracts the minute
from a date form as an integer in the range 0 to 59.
X
@tindex second
The @kbd{M-6 t P} [@code{second}] function extracts the second
from a date form.  If the current precision is 12 or less,
the result is an integer in the range 0 to 59.  For higher
precisions, the result may instead be a floating-point number.
X
@tindex weekday
The @kbd{M-7 t P} [@code{weekday}] function extracts the weekday
number from a date form as an integer in the range 0 (Sunday)
to 6 (Saturday).
X
@tindex yearday
The @kbd{M-8 t P} [@code{yearday}] function extracts the day-of-year
number from a date form as an integer in the range 1 (January 1)
to 366 (December 31 of a leap year).
X
@tindex time
The @kbd{M-9 t P} [@code{time}] function extracts the time portion
of a date form as an HMS form.  This returns @samp{0@@ 0' 0"}
for a pure date form.
X
@kindex t M
@pindex calc-new-month
@tindex newmonth
The @kbd{t M} (@code{calc-new-month}) [@code{newmonth}] command
computes a new date form that represents the first day of the month
specified by the input date.  The result is always a pure date
form; only the year and month numbers of the input are retained.
With a numeric prefix argument @var{n} in the range from 1 to 31,
@kbd{t M} computes the @var{n}th day of the month.  (If @var{n}
is greater than the actual number of days in the month, or if
@var{n} is zero, the last day of the month is used.)
X
@kindex t Y
@pindex calc-new-year
@tindex newyear
The @kbd{t Y} (@code{calc-new-year}) [@code{newyear}] command
computes a new pure date form that represents the first day of
the year specified by the input.  The month, day, and time
of the input date form are lost.  With a numeric prefix argument
@var{n} in the range from 1 to 366, @kbd{t Y} computes the
@var{n}th day of the year (366 is treated as 365 in non-leap
years).  A prefix argument of 0 computes the last day of the
year (December 31).  A negative prefix argument from @i{-1} to
@i{-12} computes the first day of the @var{n}th month of the year.
X
@kindex t W
@pindex calc-new-week
@tindex newweek
The @kbd{t W} (@code{calc-new-week}) [@code{newweek}] command
computes a new pure date form that represents the Sunday on or before
the input date.  With a numeric prefix argument, it can be made to
use any day of the week as the starting day; the argument must be in
the range from 0 (Sunday) to 6 (Saturday).  This function always
subtracts between 0 and 6 days from the input date.
X
Here's an example use of @code{newweek}:  Find the date of the next
Wednesday after a given date.  Using @kbd{M-3 t W} or @samp{newweek(d, 3)}
will give you the @emph{preceding} Wednesday, so @samp{newweek(d+7, 3)}
will give you the following Wednesday.  A further look at the definition
of @code{newweek} shows that if the input date is itself a Wednesday,
this formula will return the Wednesday one week in the future.  An
exercise for the reader is to modify this formula to yield the same day
if the input is already a Wednesday.  Another interesting exercise is
to preserve the time-of-day portion of the input (@code{newweek} resets
the time to midnight; hint: how can @code{newweek} be defined in terms
of the @code{weekday} function?).
X
@tindex pwday
The @samp{pwday(@var{date})} function (not on any key) computes the
day-of-month number of the Sunday on or before @var{date}.  With
two arguments, @samp{pwday(@var{date}, @var{day})} computes the day
number of the Sunday on or before day number @var{day} of the month
specified by @var{date}.  The @var{day} must be in the range from
7 to 31; if the day number is greater than the actual number of days
in the month, the true number of days is used instead.  Thus
@samp{pwday(@var{date}, 7)} finds the first Sunday of the month, and
@samp{pwday(@var{date}, 31)} finds the last Sunday of the month.
With a third @var{weekday} argument, @code{pwday} can be made to look
for any day of the week instead of Sunday.
X
@kindex t I
@pindex calc-inc-month
@tindex incmonth
The @kbd{t I} (@code{calc-inc-month}) [@code{incmonth}] command
increases a date form by one month, or by an arbitrary number of
months specified by a numeric prefix argument.  The time portion,
if any, of the date form stays the same.  The day also stays the
same, except that if the new month has fewer days the day
number may be reduced to lie in the valid range.  For example,
@samp{incmonth(<Jan 31, 1991>)} produces @samp{<Feb 28, 1991>}.
Because of this, @kbd{t I t I} and @kbd{M-2 t I} do not always give
the same results (@samp{<Mar 28, 1991>} versus @samp{<Mar 31, 1991>}
in this case).
X
@tindex incyear
The @samp{incyear(@var{date}, @var{step})} function increases
a date form by the specified number of years, which may be
any positive or negative integer.  Note that @samp{incyear(d, n)}
is equivalent to @samp{incmonth(d, 12*n)}, but these do not have
simple equivalents in terms of day arithmetic because
months and years have varying lengths.  If the @var{step}
argument is omitted, 1 year is assumed.  There is no keyboard
command for this function; use @kbd{C-u 12 t I} instead.
X
There is no @code{newday} function at all because @kbd{F} [@code{floor}]
serves this purpose.  Similarly, instead of @code{incday} and
@code{incweek} simply use @cite{d + n} or @cite{d + 7 n}.
X
@xref{Basic Arithmetic}, for the @kbd{f ]} [@code{incr}] command
which can adjust a date/time form by a certain number of seconds.
X
@node Time Zones, , Date Functions, Date Arithmetic
@subsection Time Zones
X
@noindent
@cindex Time zones
@cindex Daylight savings time
Time zones and daylight savings time are a complicated business.
The conversions to and from Julian and Unix-style dates automatically
compute the correct time zone and daylight savings adjustment to use,
provided they can figure out this information.  This section describes
Calc's time zone adjustment algorithm in detail, in case you want to
do conversions in different time zones or in case Calc's algorithms
can't determine the right correction to use.
X
Adjustments for time zones and daylight savings time are done by
@kbd{t U}, @kbd{t J}, @kbd{t N}, and @kbd{t C}, but not by any other
commands.  In particular, @samp{<may 1 1991> - <apr 1 1991>} evaluates
to exactly 30 days even though there is a daylight-savings
transition in between.  This is also true for Julian pure dates:
@samp{julian(<may 1 1991>) - julian(<apr 1 1991>)}.  But Julian
and Unix date/times will adjust for daylight savings time:
@samp{julian(<12am may 1 1991>) - julian(<12am apr 1 1991>)}
evaluates to @samp{29.95834} (that's 29 days and 23 hours)
because one hour was lost when daylight savings commenced on
April 7, 1991.
X
In brief, the idiom @samp{julian(@var{date1}) - julian(@var{date2})}
computes the actual number of 24-hour periods between two dates, whereas
@samp{@var{date1} - @var{date2}} computes the number of calendar
days between two dates without taking daylight savings into account.
X
@pindex calc-time-zone
@tindex tzone
The @code{calc-time-zone} [@code{tzone}] command converts the time
zone specified by its numeric prefix argument into a number of
seconds difference from Greenwich mean time (GMT).  If the argument
is a number, the result is simply that value multiplied by 3600.
Typical arguments for North America are 5 (Eastern) or 8 (Pacific).  If
Daylight Savings time is in effect, one hour should be subtracted from
the normal difference.
X
If you give a prefix of plain @kbd{C-u}, @code{calc-time-zone} (like other
date arithmetic commands that include a time zone argument) takes the
zone argument from the top of the stack.  (In the case of @kbd{t J}
and @kbd{t U}, the normal argument is then taken from the second-to-top
stack position.)  This allows you to give a non-integer time zone
adjustment.  The time-zone argument can also be an HMS form, or
it can be a variable which is a time zone name in upper- or lower-case.
For example @samp{tzone(PST) = tzone(8)} and @samp{tzone(pdt) = tzone(7)}
(for Pacific standard and daylight savings times, respectively).
X
North American and European time zone names are defined as follows;
note that for each time zone there is one name for standard time,
another for daylight savings time, and a third for ``generalized'' time
in which the daylight savings adjustment is computed from context.
X
@group
@smallexample
YST  PST  MST  CST  EST  AST    NST    GMT   WET     MET    MEZ
X 9    8    7    6    5    4     3.5     0     -1      -2     -2
X
YDT  PDT  MDT  CDT  EDT  ADT    NDT    BST  WETDST  METDST  MESZ
X 8    7    6    5    4    3     2.5     -1    -2      -3     -3
X
YGT  PGT  MGT  CGT  EGT  AGT    NGT    BGT   WEGT    MEGT   MEGZ
9/8  8/7  7/6  6/5  5/4  4/3  3.5/2.5  0/-1 -1/-2   -2/-3  -2/-3
@end smallexample
@end group
X
@vindex math-tzone-names
To define time zone names that do not appear in the above table,
you must modify the Lisp variable @code{math-tzone-names}.  This
is a list of lists describing the different time zone names; its
structure is best explained by an example.  The three entries for
Pacific Time look like this:
X
@group
@smallexample
( ( "PST" 8 0 )    ; Name as an upper-case string, then standard
X  ( "PDT" 8 -1 )   ; adjustment, then daylight savings adjustment.
X  ( "PGT" 8 "PST" "PDT" ) )   ; Generalized time zone.
@end smallexample
@end group
X
@cindex @code{TimeZone} variable.
@vindex TimeZone
With no arguments, @code{calc-time-zone} or @samp{tzone()} obtains an
argument from the Calc variable @code{TimeZone} if a value has been
stored for that variable.  If not, Calc runs the Unix @samp{date}
command and looks for one of the above time zone names in the output;
if this does not succeed, @samp{tzone()} leaves itself unevaluated.
The time zone name in the @samp{date} output may be followed by a signed
adjustment, e.g., @samp{GMT+5} or @samp{GMT+0500} which specifies a
number of hours and minutes to be added to the base time zone.
Calc stores the time zone it finds into @code{TimeZone} to speed
later calls to @samp{tzone()}.
X
The special time zone name @code{local} is equivalent to no argument,
i.e., it uses the local time zone as obtained from the @code{date}
command.
X
If the time zone name found is one of the standard or daylight
savings zone names from the above table, and Calc's internal
daylight savings algorithm says that time and zone are consistent
(e.g., @code{PDT} accompanies a date that Calc's algorithm would also
consider to be daylight savings, or @code{PST} accompanies a date
that Calc would consider to be standard time), then Calc substitutes
the corresponding generalized time zone (like @code{PGT}).
X
If your system does not have a suitable @samp{date} command, you
may wish to put a @samp{(setq var-TimeZone ...)} in your Emacs
initialization file to set the time zone.  The easiest way to do
this is to edit the @code{TimeZone} variable using Calc's @kbd{s T}
command, then use the @kbd{s p} (@code{calc-permanent-variable})
command to save the value of @code{TimeZone} permanently.
X
The @kbd{t J} and @code{t U} commands with no numeric prefix
arguments do the same thing as @samp{tzone()}.  If the current
time zone is a generalized time zone, e.g., @code{EGT}, Calc
examines the date being converted to tell whether to use standard
or daylight savings time.  But if the current time zone is explicit,
e.g., @code{EST} or @code{EDT}, then that adjustment is used exactly
and Calc's daylight savings algorithm is not consulted.
X
Some places don't follow the usual rules for daylight savings time.
The state of Arizona, for example, does not observe daylight savings
time.  If you run Calc during the winter season in Arizona, the
Unix @code{date} command will report @code{MST} time zone, which
Calc will change to @code{MGT}.  If you then convert a time that
lies in the summer months, Calc will apply an incorrect daylight
savings time adjustment.  To avoid this, set your @code{TimeZone}
variable explicitly to @code{MST} to force the use of standard,
non-daylight-savings time.
X
@vindex math-daylight-savings-hook
@findex math-std-daylight-savings
By default Calc always considers daylight savings time to begin at
2 a.m.@: on the first Sunday of April, and to end at 2 a.m.@: on the
last Sunday of October.  This is the rule that has been in effect
in North America since 1987.  If you are in a country that uses
different rules for computing daylight savings time, you have two
choices:  Write your own daylight savings hook, or control time
zones explicitly by setting the @code{TimeZone} variable and/or
always giving a time-zone argument for the conversion functions.
X
The Lisp variable @code{math-daylight-savings-hook} holds the
name of a function that is used to compute the daylight savings
adjustment for a given date.  The default is
@code{math-std-daylight-savings}, which computes an adjustment
(either 0 or @i{-1}) using the North American rules given above.
X
The daylight savings hook function is called with four arguments:
The date, as a floating-point number in standard Calc format;
a six-element list of the date decomposed into year, month, day,
hour, minute, and second, respectively; a string which contains
the generalized time zone name in upper-case, e.g., @code{"WEGT"};
and a special adjustment to be applied to the hour value when
converting into a generalized time zone (see below).
X
@findex math-prev-weekday-in-month
The Lisp function @code{math-prev-weekday-in-month} is useful for
daylight savings computations.  This is an internal version of
the user-level @code{pwday} function described in the previous
section. It takes four arguments:  The floating-point date value,
the corresponding six-element date list, the day-of-month number,
and the weekday number (0-6).
X
The default daylight savings hook ignores the time zone name, but a
more sophisticated hook could use different algorithms for different
time zones.  It would also be possible to use different algorithms
depending on the year number, but the default hook always uses the
algorithm for 1987 and later.  Here is a listing of the default
daylight savings hook:
X
@smallexample
(defun math-std-daylight-savings (date dt zone bump)
X  (cond ((< (nth 1 dt) 4) 0)
X        ((= (nth 1 dt) 4)
X         (let ((sunday (math-prev-weekday-in-month date dt 7 0)))
X           (cond ((< (nth 2 dt) sunday) 0)
X                 ((= (nth 2 dt) sunday)
X                  (if (>= (nth 3 dt) (+ 3 bump)) -1 0))
X                 (t -1))))
X        ((< (nth 1 dt) 10) -1)
X        ((= (nth 1 dt) 10)
X         (let ((sunday (math-prev-weekday-in-month date dt 31 0)))
X           (cond ((< (nth 2 dt) sunday) -1)
X                 ((= (nth 2 dt) sunday)
X                  (if (>= (nth 3 dt) (+ 2 bump)) 0 -1))
X                 (t 0))))
X        (t 0))
)
@end smallexample
X
@noindent
The @code{bump} parameter is equal to zero when Calc is converting
from a date form in a generalized time zone into a GMT date value.
It is @i{-1} when Calc is converting in the other direction.  The
adjustments shown above ensure that the conversion behaves correctly
and reasonably around the 2 a.m.@: transition in each direction.
X
There is a ``missing'' hour between 2 a.m.@: and 3 a.m.@: at the
beginning of daylight savings time; converting a date/time form that
falls in this hour results in a time value for the following hour,
from 3 a.m.@: to 4 a.m.  At the end of daylight savings time, the
hour from 1 a.m.@: to 2 a.m.@: repeats itself; converting a date/time
form that falls in in this hour results in a time value for the first
manifestion of that time (@emph{not} the one that occurs one hour later).
X
If @code{math-daylight-savings-hook} is @code{nil}, then the
daylight savings adjustment is always taken to be zero.
X
In algebraic formulas, @samp{tzone(@var{zone}, @var{date})}
computes the time zone adjustment for a given zone name at a
given date.  The @var{date} is ignored unless @var{zone} is a
generalized time zone.  If @var{date} is a date form, the
daylight savings computation is applied to it as it appears.
If @var{date} is a numeric date value, it is adjusted for the
daylight-savings version of @var{zone} before being given to
the daylight savings hook.  This odd-sounding rule ensures
that the daylight-savings computation is always done in
local time, not in the GMT time that a numeric @var{date}
is typically represented in.
X
@tindex dsadj
The @samp{dsadj(@var{date}, @var{zone})} function computes the
daylight savings adjustment that is appropriate for @var{date} in
time zone @var{zone}.  If @var{zone} is explicitly in or not in
daylight savings time (e.g., @code{PDT} or @code{PST}) the
@var{date} is ignored.  If @var{zone} is a generalized time zone,
the algorithms described above are used.  If @var{zone} is omitted,
the computation is done for the current time zone.
X
@xref{Reporting Bugs}, for the address of Calc's author, if you
should wish to contribute your improved versions of
@code{math-tzone-names} and @code{math-daylight-savings-hook}
to the Calc distribution.
X
@node Financial Functions, Binary Functions, Date Arithmetic, Arithmetic
@section Financial Functions
X
@noindent
Calc's financial or business functions use the @kbd{b} prefix
key followed by a shifted letter.  (The @kbd{b} prefix followed by
a lower-case letter is used for operations on binary numbers.)
X
@tindex %
@tindex percent
Since many of these functions have @var{rate} arguments which would
normally be written as percentages, Calc accepts the notation
@samp{@var{x}%} during algebraic entry.  This is equivalent to
@samp{@var{x} * .01}.  In other words, the @var{rate} argument
to these functions wants something like @samp{8%} or @samp{.08}
as a value, @emph{not} 8 (which would correspond to a rate of
800%!).
X
Also note that the rate and the number of intervals must be on the
same time scale, e.g., months or years.  Mixing an annual interest
rate with a time expressed in months will give you very wrong
answers!
X
Finally, it is wise to compute these functions to a higher precision
than you really need, just to make sure your answer is correct to
the last penny; also, you may wish to check the definitions at the end
of this section to make sure the functions have the meaning you expect.
X
@menu
* Future Value::
* Present Value::
* Related Financial Functions::
* Depreciation Functions::
* Definitions of Financial Functions::
@end menu
X
@node Future Value, Present Value, Financial Functions, Financial Functions
@subsection Future Value
X
@noindent
@kindex b F
@pindex calc-fin-fv
@tindex fv
The @kbd{b F} (@code{calc-fin-fv}) [@code{fv}] command computes
the future value of an investment.  It takes three arguments
from the stack:  @samp{fv(@var{rate}, @var{n}, @var{payment})}.
If you give payments of @var{payment} every year for @var{n}
years, and the money you have paid earns interest at @var{rate} per
year, then this function tells you what your investment would be
worth at the end of the period.  (The actual interval doesn't
have to be years, as long as @var{n} and @var{rate} are expressed
in terms of the same intervals.)  This function assumes payments
occur at the @emph{end} of each interval.
X
@kindex I b F
@tindex fvb
The @kbd{I b F} [@code{fvb}] command does the same computation,
but assuming your payments are at the beginning of each interval.
Suppose you plan to deposit $1000 per year in a savings account
earning 5.4% interest, starting right now.  How much will be
in the account after five years?  @code{fvb(5.4%, 5, 1000) = 5870.73}.
Thus you will have earned $870 worth of interest over the years.
Using the stack, this calculation would have been
@kbd{.054 RET 5 RET 1000 I b F}.  Note that the rate is expressed
as a number between 0 and 1, @emph{not} as a percentage.
X
@kindex H b F
@tindex fvl
The @kbd{H b F} [@code{fvl}] command computes the future value
of an initial lump sum investment.  Suppose you could deposit
those five thousand dollars in the bank right now; how much would
they be worth in five years?  @code{fvl(5.4%, 5, 5000) = 6503.89}.
X
The algebraic functions @code{fv} and @code{fvb} accept an optional
fourth argument, which is used as an initial lump sum in the sense
of @code{fvl}.  In other words, @code{fv(@var{rate}, @var{n},
@var{payment}, @var{initial}) = fv(@var{rate}, @var{n}, @var{payment})
+ fvl(@var{rate}, @var{n}, @var{initial})}.@refill
X
To illustrate the relationships between these functions, we could
do the @code{fvb} calculation ``by hand'' using @code{fvl}.  The
final balance will be the sum of the contributions of our five
deposits at various times.  The first deposit earns interest for
five years:  @code{fvl(5.4%, 5, 1000) = 1300.78}.  The second
deposit only earns interest for four years:  @code{fvl(5.4%, 4, 1000) =
1234.13}.  And so on down to the last deposit, which earns one
year's interest:  @code{fvl(5.4%, 1, 1000) = 1054.00}.  The sum of
these five values is, sure enough, $5870.73, just as was computed
by @code{fvb} directly.
X
What does @code{fv(5.4%, 5, 1000) = 5569.96} mean?  The payments
are now at the ends of the periods.  The end of one year is the same
as the beginning of the next, so what this really means is that we've
lost the payment at year zero (which contributed $1300.78), but we're
now counting the payment at year five (which, since it didn't have
a chance to earn interest, counts as $1000).  Indeed, @cite{5569.96 =
5870.73 - 1300.78 + 1000} (give or take a bit of roundoff error).
X
@node Present Value, Related Financial Functions, Future Value, Financial Functions
@subsection Present Value
X
@noindent
@kindex b P
@pindex calc-fin-pv
@tindex pv
The @kbd{b P} (@code{calc-fin-pv}) [@code{pv}] command computes
the present value of an investment.  Like @code{fv}, it takes
three arguments:  @code{pv(@var{rate}, @var{n}, @var{payment})}.
It computes the present value of a series of regular payments.
Suppose you have the chance to make an investment that will
pay $2000 per year over the next four years; as you receive
these payments you can put them in the bank at 9% interest.
You want to know whether it is better to make the investment, or
to keep the money in the bank where it earns 9% interest right
from the start.  The calculation @code{pv(9%, 4, 2000)} gives the
result 6479.44.  If your initial investment must be less than this,
say, $6000, then the investment is worthwhile.  But if you had to
put up $7000, then it would be better just to leave it in the bank.
X
Here is the interpretation of the result of @code{pv}:  You are
trying to compare the return from the investment you are
considering, which is @code{fv(9%, 4, 2000) = 9146.26}, with
the return from leaving the money in the bank, which is
@code{fvl(9%, 4, @var{x})} where @var{x} is the amount of money
you would have to put up in advance.  The @code{pv} function
finds the break-even point, @cite{x = 6479.44}, at which
@code{fvl(9%, 4, 6479.44)} is also equal to 9146.26.  This is
the largest amount you should be willing to invest.
X
@kindex I b P
@tindex pvb
The @kbd{I b P} [@code{pvb}] command solves the same problem,
but with payments occurring at the beginning of each interval.
It has the same relationship to @code{fvb} as @code{pv} has
to @code{fv}.  For example @code{pvb(9%, 4, 2000) = 7062.59},
a larger number than @code{pv} produced because we get to start
earning interest on the return from our investment sooner.
X
@kindex H b P
@tindex pvl
The @kbd{H b P} [@code{pvl}] command computes the present value of
an investment that will pay off in one lump sum at the end of the
period.  For example, if we get our $8000 all at the end of the
four years, @code{pvl(9%, 4, 8000) = 5667.40}.  This is much
less than @code{pv} reported, because we don't earn any interest
on the return from this investment.  Note that @code{pvl} and
@code{fvl} are simple inverses:  @code{fvl(9%, 4, 5667.40) = 8000}.
X
You can give an optional fourth lump-sum argument to @code{pv}
and @code{pvb}; this is handled in exactly the same way as the
fourth argument for @code{fv} and @code{fvb}.
X
@kindex b N
@pindex calc-fin-npv
@tindex npv
The @kbd{b N} (@code{calc-fin-npv}) [@code{npv}] command computes
the net present value of a series of irregular investments.
The first argument is the interest rate.  The second argument is
a vector which represents the expected return from the investment
at the end of each interval.  For example, if the rate represents
a yearly interest rate, then the vector elements are the return
from the first year, second year, and so on.
X
Thus, @code{npv(9%, [2000,2000,2000,2000]) = pv(9%, 4, 2000) = 6479.44}.
Obviously this function is more interesting when the payments are
not all the same!
X
The @code{npv} function can actually have two or more arguments.
Multiple arguments are interpreted in the same way as for the
vector statistical functions like @code{vsum}.
@xref{Single-Variable Statistics}.  Basically, if there are several
payment arguments, each either a vector or a plain number, all these
values are collected left-to-right into the complete list of payments.
A numeric prefix argument on the @kbd{b N} command says how many
payment values or vectors to take from the stack.@refill
X
@kindex I b N
@tindex npvb
The @kbd{I b N} [@code{npvb}] command computes the net present
value where payments occur at the beginning of each interval
rather than at the end.
X
@node Related Financial Functions, Depreciation Functions, Present Value, Financial Functions
@subsection Related Financial Functions
X
@noindent
The functions in this section are basically inverses of the
present value functions with respect to the various arguments.
X
@kindex b M
@pindex calc-fin-pmt
@tindex pmt
The @kbd{b M} (@code{calc-fin-pmt}) [@code{pmt}] command computes
the amount of periodic payment necessary to amortize a loan.
Thus @code{pmt(@var{rate}, @var{n}, @var{amount})} equals the
value of @var{payment} such that @code{pv(@var{rate}, @var{n},
@var{payment}) = @var{amount}}.@refill
X
@kindex I b M
@tindex pmtb
The @kbd{I b M} [@code{pmtb}] command does the same computation
but using @code{pvb} instead of @code{pv}.  Like @code{pv} and
@code{pvb}, these functions can also take a fourth argument which
represents an initial lump-sum investment.
X
@kindex H b M
The @kbd{H b M} key just invokes the @code{fvl} function, which is
the inverse of @code{pvl}.  There is no explicit @code{pmtl} function.
X
@kindex b #
@pindex calc-fin-nper
@tindex nper
The @kbd{b #} (@code{calc-fin-nper}) [@code{nper}] command computes
the number of regular payments necessary to amortize a loan.
Thus @code{nper(@var{rate}, @var{payment}, @var{amount})} equals
the value of @var{n} such that @code{pv(@var{rate}, @var{n},
@var{payment}) = @var{amount}}.  If @var{payment} is too small
ever to amortize a loan for @var{amount} at interest rate @var{rate},
the @code{nper} function is left in symbolic form.@refill
X
@kindex I b #
@tindex nperb
The @kbd{I b #} [@code{nperb}] command does the same computation
but using @code{pvb} instead of @code{pv}.  You can give a fourth
SHAR_EOF
true || echo 'restore of calc.texinfo failed'
fi
echo 'End of  part 41'
echo 'File calc.texinfo is continued in part 42'
echo 42 > _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].