12. Numbers

• 12.1 Number Concepts
• Dictionary

12.1 Number Concepts#

12.1.1 Numeric Operations#

Common Lisp provides a large variety of operations related to numbers. This section provides an overview of those operations by grouping them into categories that emphasize some of the relationships among them.

The next figure shows operators relating to arithmetic operations.

The next figure shows defined names relating to exponential, logarithmic, and trigonometric operations.

The next figure shows operators relating to numeric comparison and predication.

The next figure shows defined names relating to numeric type manipulation and coercion.

12.1.1.1 Associativity and Commutativity in Numeric Operations#

A conforming program can control the order of processing explicitly by separating the operations into separate (possibly nested) function forms, or by writing explicit calls to functions that perform coercions.

12.1.1.1.1 Examples of Associativity and Commutativity in Numeric Operations#

 (+ 1/3 2/3 1.0d0 1.0 1.0e-15)

One conforming implementation might process the arguments from left to right, first adding 1/3 and 2/3 to get 1, then converting that to a double float for combination with 1.0d0, then successively converting and adding 1.0 and 1.0e-15.

Another conforming implementation might process the arguments from right to left, first performing a single float addition of 1.0 and 1.0e-15 (perhaps losing accuracy in the process), then converting the sum to a double float and adding 1.0d0, then converting 2/3 to a double float and adding it, and then converting 1/3 and adding that.

A third conforming implementation might first scan all the arguments, process all the rationals first to keep that part of the computation exact, then find an argument of the largest floating-point format among all the arguments and add that, and then add in all other arguments, converting each in turn (all in a perhaps misguided attempt to make the computation as accurate as possible).

In any case, all three strategies are legitimate.

A conforming program could control the order by writing, for example,

 (+ (+ 1/3 2/3) (+ 1.0d0 1.0e-15) 1.0)

12.1.1.2 Contagion in Numeric Operations#

For information about the contagion rules for implicit coercions of arguments in numeric operations, see Section 12.1.4.4 (Rule of Float Precision Contagion), Section 12.1.4.1 (Rule of Float and Rational Contagion), and Section 12.1.5.2 (Rule of Complex Contagion).

12.1.1.3 Viewing Integers as Bits and Bytes#

12.1.1.3.1 Logical Operations on Integers#

The next figure shows defined names relating to logical operations on numbers.

12.1.1.3.2 Byte Operations on Integers#

The next figure shows defined names relating to manipulating bytes of numbers.

12.1.2 Implementation-Dependent Numeric Constants#

12.1.3 Rational Computations#

12.1.0 2The rules in this section apply to rational computations.

12.1.3.1 Rule of Unbounded Rational Precision#

12.1.3.2 Rule of Canonical Representation for Rationals#

2.1.2 1 This had been removed, but I couldn't figure out why, so I reinstated it. -kmp 19-Oct-91If the denominator does not evenly divide the numerator, the canonical representation of a rational number is as the ratio that numerator and that denominator, where the greatest common divisor of the numerator and denominator is one, and where the denominator is positive and greater than one.

When used as input (in the default syntax), the notation -0 always denotes the integer 0. A conforming implementation must not have a representation of “minus zero” for integers that is distinct from its representation of zero for integers. However, such a distinction is possible for floats; see the type float.

12.1.3.3 Rule of Float Substitutability#

12.5.0 4When the arguments to an irrational mathematical function Reviewer: Barmar: There should be a table of these functions. are all rational and the true mathematical result is also (mathematically) rational, then unless otherwise noted an implementation is free to return either an accurate rational result or a single float approximation. If the arguments are all rational but the result cannot be expressed as a rational number, then a single float approximation is always returned.

If the arguments to Added "irrational" per Boyer/Kaufmann/Moore #14 (by X3J13 vote at May 4-5, 1994 meeting) -kmp 9-May-94 aan irrational mathematical function are all of type (or rational (complex rational)) and the true mathematical result is (mathematically) a complex number with rational real and imaginary parts, then unless otherwise noted an implementation is free to return either an accurate result of type (or rational (complex rational)) or a single float (permissible only if the imaginary part of the true mathematical result is zero) or (complex single-float). If the arguments are all of type (or rational (complex rational)) but the result cannot be expressed as a rational or complex rational, then the returned value will be of type single-float (permissible only if the imaginary part of the true mathematical result is zero) or (complex single-float).

Added per Boyer/Kaufmann/Moore #14 (by X3J13 vote at May 4-5, 1994 meeting) -kmp 9-May-94Float substitutability applies neither to the rational functions +, -, *, and / nor to the related operators 1+, 1-, incf, decf, and conjugate. For rational functions, if all arguments are rational, then the result is rational; if all arguments are of type (or rational (complex rational)), then the result is of type (or rational (complex rational)).

12.1.4 Floating-point Computations#

The following rules apply to floating point computations.

12.1.4.1 Rule of Float and Rational Contagion#

12.1.0 3When rationals and floats are combined by a numerical function, the rational is first converted to a float of the same format. For functions such as + that take more than two arguments, it is permitted that part of the operation be carried out exactly using rationals and the rest be done using floating-point arithmetic.

When rationals and floats are compared by a numerical function, the function rational is effectively called to convert the float to a rational and then an exact comparison is performed. In the case of complex numbers, the real and imaginary parts are effectively handled individually.

12.1.4.1.1 Examples of Rule of Float and Rational Contagion#

 ;;;; Combining rationals with floats.
 ;;; This example assumes an implementation in which 
 ;;; (float-radix 0.5) is 2 (as in IEEE) or 16 (as in IBM/360),
 ;;; or else some other implementation in which 1/2 has an exact 
 ;;;  representation in floating point.
 (+ 1/2 0.5) → 1.0
 (- 1/2 0.5d0) → 0.0d0
 (+ 0.5 -0.5 1/2) → 0.5

 ;;;; Comparing rationals with floats.
 ;;; This example assumes an implementation in which the default float 
 ;;; format is IEEE single-float, IEEE double-float, or some other format
 ;;; in which 5/7 is rounded upwards by FLOAT.
 (< 5/7 (float 5/7)) → true
 (< 5/7 (rational (float 5/7))) → true
 (< (float 5/7) (float 5/7)) → false

12.1.4.2 Rule of Float Approximation#

12.1.4.3 Rule of Float Underflow and Overflow#

12.1.4.4 Rule of Float Precision Contagion#

The following was said in two different places. I've removed the most casually worded of the two. Hopefully no useful info was lost in the process. -kmp 19-Oct-91 When a shorter \term{float} is combined with a longer one in an operation, the result will be of the \term{type} of the longer of the two \term{floats}.

12.1.0 5The result of a numerical function is a float of the largest format among all the floating-point arguments to the function.

12.1.5 Complex Computations#

12.1.0 6The following rules apply to complex computations:

12.1.5.1 Rule of Complex Substitutability#

12.1.5.2 Rule of Complex Contagion#

12.1.5.3 Rule of Canonical Representation for Complex Rationals#

12.1.0 8If the result of any computation would be a complex number whose real part is of type rational and whose imaginary part is zero, the result is converted to the rational which is the real part. This rule does not apply to complex numbers whose parts are floats. For example, #C(5 0) and 5 are not different objects in Common Lisp (they are always the same under eql); #C(5.0 0.0) and 5.0 are always different objects in Common Lisp (they are never the same under eql, although they are the same under equalp and =).

12.1.5.3.1 Examples of Rule of Canonical Representation for Complex Rationals#

 #c(1.0 1.0) → #C(1.0 1.0)
 #c(0.0 0.0) → #C(0.0 0.0)
 #c(1.0 1) → #C(1.0 1.0)
 #c(0.0 0) → #C(0.0 0.0)
 #c(1 1) → #C(1 1)
 #c(0 0) → 0
 (typep #c(1 1) '(complex (eql 1))) → true
 (typep #c(0 0) '(complex (eql 0))) → false

12.1.5.4 Principal Values and Branch Cuts#

12.5.3 17The next figure lists the identities that are obeyed throughout the applicable portion of the complex domain, even on the branch cuts:

The quadrant numbers referred to in the discussions of branch cuts are as illustrated in the next figure.

JGA requested this. This is amazingly low-tex and the spacing of dots isn't quite right, but I think it's good enough to be intelligible and will suffice until and unless something better is devised. -kmp 3-Feb-92

Quadrant Numbering for Branch Cuts

12.1.6 Interval Designators#

The compound type specifier form of the numeric type specifiers Removed per Boyer/Kaufmann/Moore #15 (by X3J13 vote at May 4-5, 1994 meeting) -kmp 9-May-94 in \thenextfigure\permit the user to specify an interval on the real number line which describe a subtype of the type which would be described by the corresponding atomic type specifier. A subtype of some type T is specified using an ordered pair of objects called interval designators for type T.

The first of the two interval designators for type T can be any of the following:

• a number N of type T

  This denotes a lower inclusive bound of N. That is, elements of the subtype of T will be greater than or equal to N.

• a singleton list whose element is a number M of type T

  This denotes a lower exclusive bound of M. That is, elements of the subtype of T will be greater than M.

• the symbol *

  This denotes the absence of a lower bound on the interval.

The second of the two interval designators for type T can be any of the following:

• a number N of type T

  This denotes an upper inclusive bound of N. That is, elements of the subtype of T will be less than or equal to N.

• a singleton list whose element is a number M of type T

  This denotes an upper exclusive bound of M. That is, elements of the subtype of T will be less than M.

• the symbol *

  This denotes the absence of an upper bound on the interval.

12.1.7 Random-State Operations#

Dictionary

• number System Class
• complex System Class
• real System Class
• float System Class
• short-float, single-float, double-float, long-float Type
• rational System Class
• ratio System Class
• integer System Class
• signed-byte Type
• unsigned-byte Type
• mod Type Specifier
• bit Type
• fixnum Type
• bignum Type
• =, /=, <, >, <=, >= Function
• max, min Function
• minusp, plusp Function
• zerop Function
• floor, ffloor, ceiling, fceiling, truncate, ftruncate, round, fround Function
• sin, cos, tan Function
• asin, acos, atan Function
• pi Constant Variable
• sinh, cosh, tanh, asinh, acosh, atanh Function
• * Function
• + Function
• - Function
• / Function
• 1+, 1- Function
• abs Function
• evenp, oddp Function
• exp, expt Function
• gcd Function
• incf, decf Macro
• lcm Function
• log Function
• mod, rem Function
• signum Function
• sqrt, isqrt Function
• random-state System Class
• make-random-state Function
• random Function
• random-state-p Function
• *random-state* Variable
• numberp Function
• cis Function
• complex Function
• complexp Function
• conjugate Function
• phase Function
• realpart, imagpart Function
• upgraded-complex-part-type Function
• realp Function
• numerator, denominator Function
• rational, rationalize Function
• rationalp Function
• ash Function
• integer-length Function
• integerp Function
• parse-integer Function
• boole Function
• boole-1, boole-2, boole-and, boole-andc1, boole-andc2, boole-c1, boole-c2, boole-clr, boole-eqv, boole-ior, boole-nand, boole-nor, boole-orc1, boole-orc2, boole-set, boole-xor Constant Variable
• logand, logandc1, logandc2, logeqv, logior, lognand, lognor, lognot, logorc1, logorc2, logxor Function
• logbitp Function
• logcount Function
• logtest Function
• byte, byte-size, byte-position Function
• deposit-field Function
• dpb Function
• ldb Accessor
• ldb-test Function
• mask-field Accessor
• most-positive-fixnum, most-negative-fixnum Constant Variable
• decode-float, scale-float, float-radix, float-sign, float-digits, float-precision, integer-decode-float Function
• float Function
• floatp Function
• most-positive-short-float, least-positive-short-float, least-positive-normalized-short-float, most-positive-double-float, least-positive-double-float, least-positive-normalized-double-float, most-positive-long-float, least-positive-long-float, least-positive-normalized-long-float, most-positive-single-float, least-positive-single-float, least-positive-normalized-single-float, most-negative-short-float, least-negative-short-float, least-negative-normalized-short-float, most-negative-single-float, least-negative-single-float, least-negative-normalized-single-float, most-negative-double-float, least-negative-double-float, least-negative-normalized-double-float, most-negative-long-float, least-negative-long-float, least-negative-normalized-long-float Constant Variable
• short-float-epsilon, short-float-negative-epsilon, single-float-epsilon, single-float-negative-epsilon, double-float-epsilon, double-float-negative-epsilon, long-float-epsilon, long-float-negative-epsilon Constant Variable
• arithmetic-error Condition Type
• arithmetic-error-operands, arithmetic-error-operation Function
• division-by-zero Condition Type
• floating-point-invalid-operation Condition Type
• floating-point-inexact Condition Type
• floating-point-overflow Condition Type
• floating-point-underflow Condition Type