REF NUMBERS                               Titch Le Bek, Rob Duncan, 1986

       COPYRIGHT University of Sussex 1993. All Rights Reserved.

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<    LISP NUMERIC OPERATIONS  >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

This file  briefly  describes  the functions,  variables  and  constants
documented in Chapter 12  of the standard Common  Lisp guide, which  is:
Common Lisp: The Language (Guy L. Steele, Digital Press, 1984).


-------------------------------------------------
1  A Listing of Functions Variables and Constants
-------------------------------------------------

(* &rest numbers)                                             [function]
        Returns the product of numbers.


(+ &rest numbers)                                             [function]
        Returns the sum of numbers.


(- number &rest numbers)                                      [function]
        Returns the result of subtracting numbers from number.


(/ number &rest numbers)                                      [function]
        Successively divides number by numbers.


(/= number &rest numbers)                                     [function]
        True if all arguments are different; nil otherwise.


(1+ number)                                                   [function]
        Increments number by 1.


(1- number)                                                   [function]
        Decrements number by 1.


(< number &rest numbers)                                      [function]
        True if the sequence  of arguments is monotonically  increasing;
        nil otherwise.


(<= number &rest numbers)                                     [function]
        True   if   the   sequence   of   arguments   is   monotonically
        non-decreasing; nil otherwise.


(= number &rest numbers)                                      [function]
        True if all arguments are the same; nil otherwise.


(> number &rest numbers)                                      [function]
        True if the sequence  of arguments is monotonically  decreasing;
        nil otherwise.


(>= number &rest numbers)                                     [function]
        True   if   the   sequence   of   arguments   is   monotonically
        non-decreasing; nil otherwise.


(abs number)                                                  [function]
        Returns the absolute value of number.


(acos number)                                                 [function]
        Returns the arc cosine (in radians) of number.


(acosh number)                                                [function]
        Returns the hyperbolic arc cosine of number.


(ash integer number)                                          [function]
        Returns integer shifted left by number bit positions.


(asin number)                                                 [function]
        Returns the arc sine (in radians) of number.


(asinh number)                                                [function]
        Returns the hyperbolic arc sine of number.


(atan y &optional x)                                          [function]
        Returns the arc tangent of y or of y/x if x is supplied.


(atanh number)                                                [function]
        Returns the hyperbolic arc tangent of number.


(boole op integer1 integer2)                                  [function]
boole-1                                                       [constant]
boole-2                                                       [constant]
boole-and                                                     [constant]
boole-andc1                                                   [constant]
boole-andc2                                                   [constant]
boole-c1                                                      [constant]
boole-c2                                                      [constant]
boole-clr                                                     [constant]
boole-eqv                                                     [constant]
boole-ior                                                     [constant]
boole-nand                                                    [constant]
boole-nor                                                     [constant]
boole-orc1                                                    [constant]
boole-orc2                                                    [constant]
boole-set                                                     [constant]
boole-xor                                                     [constant]
        boole returns  an integer  produced  by performing  the  logical
        operation specified by  op on  integer1 and  integer2, where  op
        must be one of  the sixteen integer values  named by the  boole-
        constants. The  values of  these  constants and  the  operations
        corresponding to them are as follows:

            Operation       Value   Meaning
            ---------       -----   -------

            boole-clr       1       always 0
            boole-set       2       always 1
            boole-1         3       integer1
            boole-2         4       integer2
            boole-c1        5       complement integer1
            boole-c2        6       complement integer2
            boole-and       7       and
            boole-ior       8       inclusive or
            boole-xor       9       exclusive-or
            boole-eqv       10      equivalence (exclusive nor)
            boole-nand      11      not-and
            boole-nor       12      not-or
            boole-andc1     13      and complement integer1 and integer2
            boole-andc2     14      and complement integer2 and integer1
            boole-orc1      15      or complement integer1 and integer2
            boole-orc2      16      or complement integer2 and integer1


(byte size position)                                          [function]
        byte takes two integers representing the size and position  of a
        byte and returns a byte specifier suitable for use as an arg  to
        byte-manipulation functions.


(byte-position bytespec)                                      [function]
        Returns the position of bytespec.


(byte-size bytespec)                                          [function]
        Returns the size of bytespec.


(ceiling number &optional divisor)                            [function]
        Divides number by divisor and returns the smallest integer which
        is not smaller than the result; divisor defaults to 1. A  second
        result (the remainder)  can be  obtained from  this function  by
        using multiple-value-bind or similar.


(cis radians)                                                 [function]
        Returns a  complex  number whose  real  part is  the  cosine  of
        radians and whose imaginary part is the sine.


(complex realpart &optional imagpart)                         [function]
        Returns a number that has realpart as its real part and imagpart
        as its imaginary part. The result  may be either a complex  or a
        rational number.


(conjugate number)                                            [function]
        Returns the  complex conjugate  of  number. The  conjugate  of a
        non-complex number is itself.


(cos number)                                                  [function]
        Returns the cosine of number.


(cosh number)                                                 [function]
        Returns the hyperbolic cosine of number.


(decf var [number])                                              [macro]
        The number produced by  the form number  is subtracted from  the
        generalized variable named by var. The sum is stored back in var
        and returned. If number is not supplied then var is  decremented
        by 1.


(decode-float float)                                          [function]
        Returns 3  values :  a  new floating  point number,  an  integer
        representing the exponent and a floating point number indicating
        the sign.


(denominator rational)                                        [function]
        Returns the denominator of the rational number rational.


(deposit-field newbyte bytespec integer)                      [function]
        Returns an integer that contains the bits of newbyte within byte
        bytespec and elsewhere the bits of integer.


(dpb newbyte bytespec integer)                                [function]
        Returns a number that is the same as integer except in the  bits
        specified by  bytespec. The  integer newbyte  is interpreted  as
        being right-justified as if it were the result of ldb.


(evenp integer)                                               [function]
        Returns true if integer is even and otherwise nil.


(exp number)                                                  [function]
        Returns e raised to the power of number.


(expt number1 number2)                                        [function]
        Returns number1 raised to the power of number2.


(fceiling number &optional divisor)                           [function]
        Works like ceiling, except that  the result is a floating  point
        number.


(ffloor number &optional divisor)                             [function]
        Works like floor,  except that  the result is  a floating  point
        number.


(float number &optional other)                                [function]
        Converts any non-complex number to  a floating point number.  If
        other is not  provided and  number is  already a  floating-point
        number,  then  it  is  returned,  otherwise  a  single-float  is
        produced. If other is provided number is converted to the format
        of other.


(float-digits float)                                          [function]
        Returns the number of binary  digits used in the  representation
        of float.


(float-precision float)                                       [function]
        Returns the number of significant binary digits in float.


(float-radix float)                                           [function]
        Returns the radix of the floating point number float.


(float-sign float1 &optional float2)                          [function]
        Returns a floating point number with the same sign as float1 and
        the same absolute value as float2 (which defaults to 1).


(floor number &optional divisor)                              [function]
        Divides number by divisor and returns the largest integer  which
        is not larger than the result;  divisor defaults to 1. A  second
        result (the remainder)  can be  obtained from  this function  by
        using multiple-value-bind or similar.


(fround number &optional divisor)                             [function]
        Converts number by rounding to the nearest floating-point number
        which is returned.


(ftruncate number &optional divisor)                          [function]
        Converts number by truncating towards  zero; that is the  result
        is a floating point number of the same sign as number and  which
        has the greatest  integral magnitude  not greater  than that  of
        number.


(gcd &rest integers)                                          [function]
        Returns the greatest common divisor of integers.


(imagpart number)                                             [function]
        Returns the imaginary part of the complex number number.


(incf var [number])                                              [macro]
        The  number  produced  by  the  form  number  is  added  to  the
        generalized variable named by var and the sum is stored back  in
        var and  returned.  If  number  is  not  supplied  then  var  is
        incremented by 1.


(integer-decode-float float)                                  [function]
        Similar to decode-float but  for its first  value returns as  an
        integer the significand scaled so as to be an integer.


(integer-length integer)                                      [function]
        Returns  the  unsigned  binary  form  or  signed  binary   two's
        complement form of integer.


(isqrt integer)                                               [function]
        Returns the greatest integer less than or equal to the  positive
        square root of the integer.


(lcm integer &rest integers)                                  [function]
        Returns the least common multiple of the integer arguments.


(ldb bytespec integer)                                        [function]
        bytespec specifies a  byte of integer  to be extracted.  The
        result is a non-negative integer.


(ldb-test bytespec integer)                                   [function]
        ldb-test is  a  predicate  that  is true  if  any  of  the  bits
        designated by the  byte-specifier bytespec are  1's in  integer;
        that is, it is true if the designated field is non-zero.


(log number &optional base)                                   [function]
        Returns the logarithm of number in the base base, which defaults
        to e, the base of the natural logarithms.


(logand &rest integers)                                       [function]
        Returns the bitwise logical `and'  of integers. If no  arguments
        are given, then the result is -1 which is the identity for  this
        operation.


(logandc1 integer1 integer2)                                  [function]
        Returns the bitwise  `and' of  the complement  of integer1  with
        integer2.


(logandc2 integer1 integer2)                                  [function]
        Returns the bitwise  `and' of  the complement  of integer2  with
        integer1.


(logbitp index integer)                                       [function]
        Returns true  if the  index bit  in integer  is a  one-bit;  nil
        otherwise.


(logcount integer)                                            [function]
        Returns the number of bits in integer.


(logeqv &rest integers)                                       [function]
        Returns the bit-wise logical equivalence of integers.


(logior &rest integers)                                       [function]
        Returns the bit-wise logical inclusive `or' of integers.


(lognand integer1 integer2)                                   [function]
        Returns the bit-wise logical `not-and' of integer1 and integer2.


(lognor integer1 integer2)                                    [function]
        Returns the bit-wise logical `not-or' of integer1 and integer2.


(lognot integer)                                              [function]
        Returns the bit-wise logical complement of integer. Every bit of
        the result is  the complement  of the corresponding  bit in  the
        argument.


(logorc1 integer1 integer2)                                   [function]
        Returns the  bitwise `or'  of the  complement of  integer1  with
        integer2.


(logorc2 integer1 integer2)                                   [function]
        Returns the  bitwise `or'  of the  complement of  integer2  with
        integer1.


(logtest integer1 integer2)                                   [function]
        Returns true  if  any of  the  bits  designated by  the  1's  in
        integer1 are 1's in integer2.


(logxor &rest integers)                                       [function]
        Returns the bit-wise logical exclusive `or' of integers.


(mask-field bytespec integer)                                 [function]
        mask-field is like ldb except the result contains the  specified
        byte of integer  in the  position specified  by bytespec  rather
        than in position 0 as with ldb. The result therefore agrees with
        integer in the byte specified but has zero-bits everywhere else.


(max number &rest numbers)                                    [function]
        Returns the greatest number.


(min number &rest numbers)                                    [function]
        Returns the smallest argument.


(minusp number)                                               [function]
        Returns  true  if  number  is  strictly  less  than  zero;   nil
        otherwise. It is an error if number is not a non-complex number.


(mod number divisor)                                          [function]
        Performs the operation  floor on its  two arguments and  returns
        the second  (remainder) result  as its  only result.  It is  the
        usual modulus function when applied to two integer arguments.


(numerator rational)                                          [function]
        Returns the numerator  of the  rational. The  numerator of  an
        integer is that integer.


(oddp integer)                                                [function]
        Returns true if integer is odd; nil otherwise.


(phase number)                                                [function]
        Returns the  angle  part  of the  polar  representation  of  the
        complex number number.


pi                                                            [constant]
        The best  possible approximation  to the  mathematical  constant
        pi, represented as a double length floating point number.


(plusp  number)                                               [function]
        Returns true if number is non-complex and greater than zero.


(random number &optional state)                               [function]
        Returns a  pseudo random  number  between zero  (inclusive)  and
        number  (exclusive).   state  must   be   an  object   of   type
        random-state;  it  defaults  to   the  value  of  the   variable
        *random-state*.


*random-state*                                                [variable]
        This variable holds a data structure of type random-state  which
        encodes the internal state  of the random-number generator  used
        as a default by random. It may be read and written, but its form
        is implementation dependent.


(make-random-state &optional state)                           [function]
        Returns a new object  of type random-state  suitable for use  as
        the  variable  *random-state*.  If  state  is  nil  or   omitted
        random-state returns a copy  of the current random-number  state
        object. If state is a state object, a copy of that state  object
        is returned. If state is t  then a new state object is  returned
        that has been "randomly" initialized by some means.


(random-state-p object)                                       [function]
        Returns true if object is a random state object; nil otherwise.


(rational number)                                             [function]
        Converts number (which must not be complex) to a rational number
        which is returned.  It assumes that  a floating-point number  is
        completely  accurate   and   so  returns   a   rational   number
        mathematically equal to the precise value of number.


(rationalize number)                                          [function]
        Converts number (which must not be complex) to a rational number
        which is returned.  It assumes that  a floating-point number  is
        accurate  only   to   the  precision   of   the   floating-point
        representation, and  may return  any rational  number for  which
        number is the best available approximation.


(realpart number)                                             [function]
        Returns the real part of a complex number.


(rem number divisor)                                          [function]
        Performs the operation truncate on its two arguments and returns
        the second  (remainder) result  as its  only result.  It is  the
        usual remainder function when applied to two integer arguments.


(round number &optional divisor)                              [function]
        Divides number by divisor and converts the result by rounding to
        the nearest integer;  if the result  is exactly halfway  between
        two integers, it is  rounded to the one  that is even. A  second
        result (the remainder)  can be  obtained from  this function  by
        using multiple-value-bind or similar.


(scale-float float integer)                                   [function]
        Returns (*  float  (expt  (float  b)  integer)).  This  is  more
        efficient than  using  exponentiation  and  multiplication,  and
        avoids intermediate overflow and  underflow if the final  result
        is representable.


(signum number)                                               [function]
        If number  is a  rational, signum  returns one  of -1,  0,  or 1
        according to whether  it is negative,  zero, or positive.  For a
        floating-point number, the result is a floating-point number  of
        the same format whose value is -1, 0, or 1. For a complex number
        (signum z) is of the same phase but with unit magnitude,  unless
        z is a complex zero, in which case the result is z.


(sin number)                                                  [function]
        Returns the sine of number in radians.


(sinh number)                                                 [function]
        Returns the hyperbolic sine of number.


(sqrt number)                                                 [function]
        Returns the principal square root of number.


(tan number)                                                  [function]
        Returns the tangent of number.


(tanh number)                                                 [function]
        Returns the hyperbolic tangent of number.


(truncate number &optional divisor)                           [function]
        Divides number by divisor and converts that value to an  integer
        by truncating towards zero, i.e. the result is an integer of the
        same sign  and which  has the  greatest integral  magnitude  not
        greater than that of the argument. The divisor defaults to  1. A
        second result (the remainder) can be obtained from this function
        by using multiple-value-bind or similar.


(zerop number)                                                [function]
        Returns true if number is zero. nil otherwise.


least-positive-short-float                                    [constant]
        The positive short floating point number which is the closest in
        value to zero provided by this implementation.


least-positive-single-float                                   [constant]
        The positive single floating point  number which is the  closest
        in value to zero provided by this implementation.


least-positive-double-float                                   [constant]
        The positive double floating point  number which is the  closest
        in value to zero provided by this implementation.


least-positive-long-float                                     [constant]
        The positive long floating point number which is the closest  in
        value to zero provided by this implementation.


least-negative-short-float                                    [constant]
        The negative short floating point number which is the closest in
        value to zero provided by this implementation.


least-negative-single-float                                   [constant]
        The negative single floating point  number which is the  closest
        in value to zero provided by this implementation.


least-negative-double-float                                   [constant]
        The negative double floating point  number which is the  closest
        in value to zero provided by this implementation.


least-negative-long-float                                     [constant]
        The negative long floating point number which is the closest  in
        value to zero provided by this implementation.


most-positive-fixnum                                          [constant]
        The positive fixnum which  is the closest  in value to  infinity
        provided by this implementation.


most-negative-fixnum                                          [constant]
        The negative fixnum which  is the closest  in value to  negative
        infinity provided by this implementation.


most-positive-short-float                                     [constant]
        The positive short floating point number which is the closest in
        value to infinity provided by this implementation.


most-positive-single-float                                    [constant]
        The positive single floating point  number which is the  closest
        in value to infinity provided by this implementation.


most-positive-double-float                                    [constant]
        The positive double floating point  number which is the  closest
        in value to infinity provided by this implementation.


most-positive-long-float                                      [constant]
        The positive long floating point number which is the closest  in
        value to infinity provided by this implementation.


most-negative-short-float                                     [constant]
        The negative short floating point number which is the closest in
        value to negative infinity provided by this implementation.


most-negative-single-float                                    [constant]
        The negative single floating point  number which is the  closest
        in value to negative infinity provided by this implementation.


most-negative-double-float                                    [constant]
        The negative double floating point  number which is the  closest
        in value to negative infinity provided by this implementation.


most-negative-long-float                                      [constant]
        The negative long floating point number which is the closest  in
        value to negative infinity provided by this implementation.


short-float-epsilon                                           [constant]
        The smallest positive short floating point number, e, such  that
        the expression:

            (not (= (float 1 e) (+ (float 1 e) e)))

        has value t.


short-float-negative-epsilon                                  [constant]
        The smallest positive short floating point number, e, such  that
        the expression:

            (not (= (float 1 e) (- (float 1 e) e)))

        has value t.


single-float-epsilon                                          [constant]
        The smallest positive single floating point number, e, such that
        the expression:

            (not (= (float 1 e) (+ (float 1 e) e)))

        has value t.


single-float-negative-epsilon                                 [constant]
        The smallest positive single floating point number, e, such that
        the expression:

            (not (= (float 1 e) (- (float 1 e) e)))

        has value t.


double-float-epsilon                                          [constant]
        The smallest positive double floating point number, e, such that
        the expression:

            (not (= (float 1 e) (+ (float 1 e) e)))

        has value t.


double-float-negative-epsilon                                 [constant]
        The smallest positive double floating point number, e, such that
        the expression:

            (not (= (float 1 e) (- (float 1 e) e)))

        has value t.


long-float-epsilon                                            [constant]
        The smallest positive long floating  point number, e, such  that
        the expression:

            (not (= (float 1 e) (+ (float 1 e) e)))

        has value t.


long-float-negative-epsilon                                   [constant]
        The smallest positive long floating  point number, e, such  that
        the expression:

            (not (= (float 1 e) (- (float 1 e) e)))

        has value t.



--- C.all/lisp/ref/numbers
--- Copyright University of Sussex 1993. All rights reserved.
