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`(`

. 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).`x`0)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*`

returns`x``y`)`(`

, then`q``r`)

, with`q`*`y`+`r`=`x``r`between 0 (inclusive) and`r`(exclusive). Also, note that`(floor*`

is exactly equivalent to`x`)`(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*`

and`n`)`(random*`

(where`n``s`)`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 first, previous, next, last section, table of contents.