9. Numbers

This section defines a few simple Common Lisp operations on numbers which were left out of Emacs Lisp.

9.1 Predicates on Numbers

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.

9.2 Numerical Functions

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: 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.

The following functions are identical to their built-in counterparts, without the trailing * in their names, but they return lists instead of multiple values. @xref{(lispref.info)Rounding Operations}

Function: floor* number &optional divisor

Function: ceiling* number &optional divisor

Function: truncate* number &optional divisor

Function: round* number &optional divisor

All the above 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.

9.3 Random Numbers

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.

9.4 Implementation Parameters

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.