Go to the previous, next chapter.
This section defines a few simple Common Lisp operations on numbers which were left out of Emacs Lisp.
@secno=1
These functions return t if the specified condition is
true of the numerical argument, or nil otherwise.
{Function} plusp number
This predicate tests whether number is positive. It is an error if the argument is not a number.
{Function} minusp number
This predicate tests whether number is negative. It is an error if the argument is not a number.
{Function} oddp integer
This predicate tests whether integer is odd. It is an error if the argument is not an integer.
{Function} evenp integer
This predicate tests whether integer is even. It is an error if the argument is not an integer.
{Function} floatp-safe object
This predicate tests whether object is a floating-point
number. On systems that support floating-point, this is equivalent
to floatp. On other systems, this always returns nil.
@secno=3
These functions perform various arithmetic operations on numbers.
{Function} abs number
This function returns the absolute value of number. (Newer
versions of Emacs provide this as a built-in function; this package
defines abs only for Emacs 18 versions which don't provide
it as a primitive.)
{Function} expt base power
This function returns base raised to the power of number.
(Newer versions of Emacs provide this as a built-in function; this
package defines expt only for Emacs 18 versions which don't
provide it as a primitive.)
{Function} gcd &rest integers
This function returns the Greatest Common Divisor of the arguments. For one argument, it returns the absolute value of that argument. For zero arguments, it returns zero.
{Function} lcm &rest integers
This function returns the Least Common Multiple of the arguments. For one argument, it returns the absolute value of that argument. For zero arguments, it returns one.
{Function} isqrt integer
This function computes the "integer square root" of its integer argument, i.e., the greatest integer less than or equal to the true square root of the argument.
{Function} floor* number &optional divisor
This function implements the Common Lisp floor function.
It is called floor* to avoid name conflicts with the
simpler floor function built-in to Emacs 19.
With one argument, floor* returns a list of two numbers:
The argument rounded down (toward minus infinity) to an integer,
and the "remainder" which would have to be added back to the
first return value to yield the argument again. If the argument
is an integer x, the result is always the list (x 0).
If the argument is an Emacs 19 floating-point number, the first
result is a Lisp integer and the second is a Lisp float between
0 (inclusive) and 1 (exclusive).
With two arguments, floor* divides number by
divisor, and returns the floor of the quotient and the
corresponding remainder as a list of two numbers. If
(floor* x y) returns (q r),
then q*y + r = x, with r
between 0 (inclusive) and r (exclusive). Also, note
that (floor* x) is exactly equivalent to
(floor* x 1).
This function is entirely compatible with Common Lisp's floor
function, except that it returns the two results in a list since
Emacs Lisp does not support multiple-valued functions.
{Function} ceiling* number &optional divisor
This function implements the Common Lisp ceiling function,
which is analogous to floor except that it rounds the
argument or quotient of the arguments up toward plus infinity.
The remainder will be between 0 and minus r.
{Function} truncate* number &optional divisor
This function implements the Common Lisp truncate function,
which is analogous to floor except that it rounds the
argument or quotient of the arguments toward zero. Thus it is
equivalent to floor* if the argument or quotient is
positive, or to ceiling* otherwise. The remainder has
the same sign as number.
{Function} round* number &optional divisor
This function implements the Common Lisp round function,
which is analogous to floor except that it rounds the
argument or quotient of the arguments to the nearest integer.
In the case of a tie (the argument or quotient is exactly
halfway between two integers), it rounds to the even integer.
{Function} mod* number divisor
This function returns the same value as the second return value
of floor.
{Function} rem* number divisor
This function returns the same value as the second return value
of truncate.
These definitions are compatible with those in the Quiroz `cl.el' package, except that this package appends `*' to certain function names to avoid conflicts with existing Emacs 19 functions, and that the mechanism for returning multiple values is different.
@secno=8
This package also provides an implementation of the Common Lisp random number generator. It uses its own additive-congruential algorithm, which is much more likely to give statistically clean random numbers than the simple generators supplied by many operating systems.
{Function} random* number &optional state
This function returns a random nonnegative number less than
number, and of the same type (either integer or floating-point).
The state argument should be a random-state object
which holds the state of the random number generator. The
function modifies this state object as a side effect. If
state is omitted, it defaults to the variable
*random-state*, which contains a pre-initialized
random-state object.
{Variable} *random-state*
This variable contains the system "default" random-state
object, used for calls to random* that do not specify an
alternative state object. Since any number of programs in the
Emacs process may be accessing *random-state* in interleaved
fashion, the sequence generated from this variable will be
irreproducible for all intents and purposes.
{Function} make-random-state &optional state
This function creates or copies a random-state object.
If state is omitted or nil, it returns a new copy of
*random-state*. This is a copy in the sense that future
sequences of calls to (random* n) and
(random* n s) (where s is the new
random-state object) will return identical sequences of random
numbers.
If state is a random-state object, this function
returns a copy of that object. If state is t, this
function returns a new random-state object seeded from the
date and time. As an extension to Common Lisp, state may also
be an integer in which case the new object is seeded from that
integer; each different integer seed will result in a completely
different sequence of random numbers.
It is legal to print a random-state object to a buffer or
file and later read it back with read. If a program wishes
to use a sequence of pseudo-random numbers which can be reproduced
later for debugging, it can call (make-random-state t) to
get a new sequence, then print this sequence to a file. When the
program is later rerun, it can read the original run's random-state
from the file.
{Function} random-state-p object
This predicate returns t if object is a
random-state object, or nil otherwise.
This package defines several useful constants having to with numbers.
{Variable} most-positive-fixnum
This constant equals the largest value a Lisp integer can hold.
It is typically 2^23-1 or 2^25-1.
{Variable} most-negative-fixnum
This constant equals the smallest (most negative) value a Lisp integer can hold.
The following parameters have to do with floating-point numbers. This package determines their values by exercising the computer's floating-point arithmetic in various ways. Because this operation might be slow, the code for initializing them is kept in a separate function that must be called before the parameters can be used.
{Function} cl-float-limits
This function makes sure that the Common Lisp floating-point
parameters like most-positive-float have been initialized.
Until it is called, these parameters will be nil. If this
version of Emacs does not support floats (e.g., most versions of
Emacs 18), the parameters will remain nil. If the parameters
have already been initialized, the function returns immediately.
The algorithm makes assumptions that will be valid for most modern machines, but will fail if the machine's arithmetic is extremely unusual, e.g., decimal.
Since true Common Lisp supports up to four different floating-point
precisions, it has families of constants like
most-positive-single-float, most-positive-double-float,
most-positive-long-float, and so on. Emacs has only one
floating-point precision, so this package omits the precision word
from the constants' names.
{Variable} most-positive-float
This constant equals the largest value a Lisp float can hold.
For those systems whose arithmetic supports infinities, this is
the largest finite value. For IEEE machines, the value
is approximately 1.79e+308.
{Variable} most-negative-float
This constant equals the most-negative value a Lisp float can hold.
(It is assumed to be equal to (- most-positive-float).)
{Variable} least-positive-float
This constant equals the smallest Lisp float value greater than zero.
For IEEE machines, it is about 4.94e-324 if denormals are
supported or 2.22e-308 if not.
{Variable} least-positive-normalized-float
This constant equals the smallest normalized Lisp float greater
than zero, i.e., the smallest value for which IEEE denormalization
will not result in a loss of precision. For IEEE machines, this
value is about 2.22e-308. For machines that do not support
the concept of denormalization and gradual underflow, this constant
will always equal least-positive-float.
{Variable} least-negative-float
This constant is the negative counterpart of least-positive-float.
{Variable} least-negative-normalized-float
This constant is the negative counterpart of
least-positive-normalized-float.
{Variable} float-epsilon
This constant is the smallest positive Lisp float that can be added
to 1.0 to produce a distinct value. Adding a smaller number to 1.0
will yield 1.0 again due to roundoff. For IEEE machines, epsilon
is about 2.22e-16.
{Variable} float-negative-epsilon
This is the smallest positive value that can be subtracted from
1.0 to produce a distinct value. For IEEE machines, it is about
1.11e-16.
@chapno=13
Go to the previous, next chapter.