GNU Emacs Calc 2.02 Manual
18.5.7.5 Computational Functions
The functions described here do the actual computational work of the
Calculator. In addition to these, note that any function described in
the main body of this manual may be called from Lisp; for example, if
the documentation refers to the calcsqrt
[sqrt
] command,
this means calcsqrt
is an interactive stackbased squareroot
command and sqrt
(which defmath
expands to calcFuncsqrt
)
is the actual Lisp function for taking square roots.
The functions mathadd
, mathsub
, mathmul
,
mathdiv
, mathmod
, and mathneg
are not included
in this list, since defmath
allows you to write native Lisp
+
, 
, *
, /
, %
, and unary 
,
respectively, instead.
 Function: normalize val
 (Full form:
mathnormalize
.)
Reduce the value val to standard form. For example, if val
is a fixnum, it will be converted to a bignum if it is too large, and
if val is a bignum it will be normalized by clipping off trailing
(i.e., mostsignificant) zero digits and converting to a fixnum if it is
small. All the various data types are similarly converted to their standard
forms. Variables are left alone, but function calls are actually evaluated
in formulas. For example, normalizing `(+ 2 (calcFuncabs 4))' will
return 6.
If a function call fails, because the function is void or has the wrong
number of parameters, or because it returns nil
or calls
rejectarg
or inexactresult
, normalize
returns
the formula still in symbolic form.
If the current Simplification Mode is "none" or "numeric arguments
only," normalize
will act appropriately. However, the more
powerful simplification modes (like algebraic simplification) are
not handled by normalize
. They are handled by calcnormalize
,
which calls normalize
and possibly some other routines, such
as simplify
or simplifyunits
. Programs generally will
never call calcnormalize
except when popping or pushing values
on the stack.
 Function: evaluateexpr expr
 Replace all variables in expr that have values with their values,
then use
normalize
to simplify the result. This is what happens
when you press the = key interactively.
 Macro: withextraprec n body
 Evaluate the Lisp forms in body with precision increased by n
digits. This is a macro which expands to
 (mathnormalize
(let ((calcinternalprec (+ calcinternalprec n)))
body))

The surrounding call to mathnormalize
causes a floatingpoint
result to be rounded down to the original precision afterwards. This
is important because some arithmetic operations assume a number's
mantissa contains no more digits than the current precision allows.
 Function: makefrac n d
 Build a fraction `n:d'. This is equivalent to calling
`(normalize (list 'frac n d))', but more efficient.
 Function: makefloat mant exp
 Build a floatingpoint value out of mant and exp, both
of which are arbitrary integers. This function will return a
properly normalized float value, or signal an overflow or underflow
if exp is out of range.
 Function: makesdev x sigma
 Build an error form out of x and the absolute value of sigma.
If sigma is zero, the result is the number x directly.
If sigma is negative or complex, its absolute value is used.
If x or sigma is not a valid type of object for use in
error forms, this calls
rejectarg
.
 Function: makeintv mask lo hi
 Build an interval form out of mask (which is assumed to be an
integer from 0 to 3), and the limits lo and hi. If
lo is greater than hi, an empty interval form is returned.
This calls
rejectarg
if lo or hi is unsuitable.
 Function: sortintv mask lo hi
 Build an interval form, similar to
makeintv
, except that if
lo is less than hi they are simply exchanged, and the
bits of mask are swapped accordingly.
 Function: makemod n m
 Build a modulo form out of n and the modulus m. Since modulo
forms do not allow formulas as their components, if n or m
is not a real number or HMS form the result will be a formula which
is a call to
makemod
, the algebraic version of this function.
 Function: float x
 Convert x to floatingpoint form. Integers and fractions are
converted to numerically equivalent floats; components of complex
numbers, vectors, HMS forms, date forms, error forms, intervals, and
modulo forms are recursively floated. If the argument is a variable
or formula, this calls
rejectarg
.
 Function: compare x y
 Compare the numbers x and y, and return 1 if
`(lessp x y)', 1 if `(lessp y x)',
0 if `(mathequal x y)', or 2 if the order is
undefined or cannot be determined.
 Function: numdigs n
 Return the number of digits of integer n, effectively
`ceil(log10(n))', but much more efficient. Zero is
considered to have zero digits.
 Function: scaleint x n
 Shift integer x left n decimal digits, or right n
digits with truncation toward zero.
 Function: scalerounding x n
 Like
scaleint
, except that a right shift rounds to the nearest
integer rather than truncating.
 Function: fixnum n
 Return the integer n as a fixnum, i.e., a native Lisp integer.
If n is outside the permissible range for Lisp integers (usually
24 binary bits) the result is undefined.
 Function: sqr x
 Compute the square of x; short for `(* x x)'.
 Function: quotient x y
 Divide integer x by integer y; return an integer quotient
and discard the remainder. If x or y is negative, the
direction of rounding is undefined.
 Function: idiv x y
 Perform an integer division; if x and y are both nonnegative
integers, this uses the
quotient
function, otherwise it computes
`floor(x/y)'. Thus the result is welldefined but
slower than for quotient
.
 Function: imod x y
 Divide integer x by integer y; return the integer remainder
and discard the quotient. Like
quotient
, this works only for
integer arguments and is not welldefined for negative arguments.
For a more welldefined result, use `(% x y)'.
 Function: idivmod x y
 Divide integer x by integer y; return a cons cell whose
car
is `(quotient x y)' and whose cdr
is `(imod x y)'.
 Function: pow x y
 Compute x to the power y. In
defmath
code, this can
also be written `(^ x y)' or
`(expt x y)'.
 Function: absapprox x
 Compute a fast approximation to the absolute value of x. For
example, for a rectangular complex number the result is the sum of
the absolute values of the components.
 Function: pi
 The function `(pi)' computes `pi' to the current precision.
Other related constantgenerating functions are
twopi
,
piover2
, piover4
, piover180
, sqrttwopi
,
e
, sqrte
, ln2
, and ln10
. Each function
returns a floatingpoint value in the current precision, and each uses
caching so that all calls after the first are essentially free.
 Macro: mathdefcache func initial form
 This macro, usually used as a toplevel call like
defun
or
defvar
, defines a new cached constant analogous to pi
, etc.
It defines a function func
which returns the requested value;
if initial is nonnil
it must be a `(float ...)'
form which serves as an initial value for the cache. If func
is called when the cache is empty or does not have enough digits to
satisfy the current precision, the Lisp expression form is evaluated
with the current precision increased by four, and the result minus its
two least significant digits is stored in the cache. For example,
calling `(pi)' with a precision of 30 computes `pi' to 34
digits, rounds it down to 32 digits for future use, then rounds it
again to 30 digits for use in the present request.
 Function: fullcircle symb
 If the current angular mode is Degrees or HMS, this function returns the
integer 360. In Radians mode, this function returns either the
corresponding value in radians to the current precision, or the formula
`2*pi', depending on the Symbolic Mode. There are also similar
function
halfcircle
and quartercircle
.
 Function: powerof2 n
 Compute two to the integer power n, as a (potentially very large)
integer. Powers of two are cached, so only the first call for a
particular n is expensive.
 Function: integerlog2 n
 Compute the base2 logarithm of n, which must be an integer which
is a power of two. If n is not a power of two, this function will
return
nil
.
 Function: divmod a b m
 Divide a by b, modulo m. This returns
nil
if
there is no solution, or if any of the arguments are not integers.
 Function: powmod a b m
 Compute a to the power b, modulo m. If a,
b, and m are integers, this uses an especially efficient
algorithm. Otherwise, it simply computes `(% (^ a b) m)'.
 Function: isqrt n
 Compute the integer square root of n. This is the square root
of n rounded down toward zero, i.e., `floor(sqrt(n))'.
If n is itself an integer, the computation is especially efficient.
 Function: tohms a ang
 Convert the argument a into an HMS form. If ang is specified,
it is the angular mode in which to interpret a, either
deg
or rad
. Otherwise, the current angular mode is used. If a
is already an HMS form it is returned asis.
 Function: fromhms a ang
 Convert the HMS form a into a real number. If ang is specified,
it is the angular mode in which to express the result, otherwise the
current angular mode is used. If a is already a real number, it
is returned asis.
 Function: toradians a
 Convert the number or HMS form a to radians from the current
angular mode.
 Function: fromradians a
 Convert the number a from radians to the current angular mode.
If a is a formula, this returns the formula `deg(a)'.
 Function: toradians2 a
 Like
toradians
, except that in Symbolic Mode a degrees to
radians conversion yields a formula like `a*pi/180'.
 Function: fromradians2 a
 Like
fromradians
, except that in Symbolic Mode a radians to
degrees conversion yields a formula like `a*180/pi'.
 Function: randomdigit
 Produce a random base1000 digit in the range 0 to 999.
 Function: randomdigits n
 Produce a random ndigit integer; this will be an integer
in the interval `[0, 10^n)'.
 Function: randomfloat
 Produce a random float in the interval `[0, 1)'.
 Function: primetest n iters
 Determine whether the integer n is prime. Return a list which has
one of these forms: `(nil f)' means the number is nonprime
because it was found to be divisible by f; `(nil)' means it
was found to be nonprime by table lookup (so no factors are known);
`(nil unknown)' means it is definitely nonprime but no factors
are known because n was large enough that Fermat's probabilistic
test had to be used; `(t)' means the number is definitely prime;
and `(maybe i p)' means that Fermat's test, after i
iterations, is p percent sure that the number is prime. The
iters parameter is the number of Fermat iterations to use, in the
case that this is necessary. If
primetest
returns "maybe,"
you can call it again with the same n to get a greater certainty;
primetest
remembers where it left off.
 Function: tosimplefraction f
 If f is a floatingpoint number which can be represented exactly
as a small rational number. return that number, else return f.
For example, 0.75 would be converted to 3:4. This function is very
fast.
 Function: tofraction f tol
 Find a rational approximation to floatingpoint number f to within
a specified tolerance tol; this corresponds to the algebraic
function
frac
, and can be rather slow.
 Function: quarterinteger n
 If n is an integer or integervalued float, this function
returns zero. If n is a halfinteger (i.e., an integer plus
1:2 or 0.5), it returns 2. If n is a quarterinteger,
it returns 1 or 3. If n is anything else, this function
returns
nil
.