@node Numbers (Numbers), Characters, Packages, Top @chapter Numbers @menu * Number Concepts:: * Numbers Dictionary:: @end menu @node Number Concepts, Numbers Dictionary, Numbers (Numbers), Numbers (Numbers) @section Number Concepts @c including concept-numbers @menu * Numeric Operations:: * Implementation-Dependent Numeric Constants:: * Rational Computations:: * Floating-point Computations:: * Complex Computations:: * Interval Designators:: * Random-State Operations:: @end menu @node Numeric Operations, Implementation-Dependent Numeric Constants, Number Concepts, Number Concepts @subsection Numeric Operations @r{Common Lisp} provides a large variety of operations related to @i{numbers}. This section provides an overview of those operations by grouping them into categories that emphasize some of the relationships among them. Figure 12--1 shows @i{operators} relating to arithmetic operations. @group @noindent @w{ * 1+ gcd } @w{ + 1- incf } @w{ - conjugate lcm } @w{ / decf } @noindent @w{ Figure 12--1: Operators relating to Arithmetic.} @end group Figure 12--2 shows @i{defined names} relating to exponential, logarithmic, and trigonometric operations. @group @noindent @w{ abs cos signum } @w{ acos cosh sin } @w{ acosh exp sinh } @w{ asin expt sqrt } @w{ asinh isqrt tan } @w{ atan log tanh } @w{ atanh phase } @w{ cis pi } @noindent @w{ Figure 12--2: Defined names relating to Exponentials, Logarithms, and Trigonometry.} @end group Figure 12--3 shows @i{operators} relating to numeric comparison and predication. @group @noindent @w{ /= >= oddp } @w{ < evenp plusp } @w{ <= max zerop } @w{ = min } @w{ > minusp } @noindent @w{ Figure 12--3: Operators for numeric comparison and predication.} @end group Figure 12--4 shows @i{defined names} relating to numeric type manipulation and coercion. @group @noindent @w{ ceiling float-radix rational } @w{ complex float-sign rationalize } @w{ decode-float floor realpart } @w{ denominator fround rem } @w{ fceiling ftruncate round } @w{ ffloor imagpart scale-float } @w{ float integer-decode-float truncate } @w{ float-digits mod } @w{ float-precision numerator } @noindent @w{ Figure 12--4: Defined names relating to numeric type manipulation and coercion.} @end group @menu * Associativity and Commutativity in Numeric Operations:: * Examples of Associativity and Commutativity in Numeric Operations:: * Contagion in Numeric Operations:: * Viewing Integers as Bits and Bytes:: * Logical Operations on Integers:: * Byte Operations on Integers:: @end menu @node Associativity and Commutativity in Numeric Operations, Examples of Associativity and Commutativity in Numeric Operations, Numeric Operations, Numeric Operations @subsubsection Associativity and Commutativity in Numeric Operations For functions that are mathematically associative (and possibly commutative), a @i{conforming implementation} may process the @i{arguments} in any manner consistent with associative (and possibly commutative) rearrangement. This does not affect the order in which the @i{argument} @i{forms} are @i{evaluated}; for a discussion of evaluation order, see @ref{Function Forms}. What is unspecified is only the order in which the @i{parameter} @i{values} are processed. This implies that @i{implementations} may differ in which automatic @i{coercions} are applied; see @ref{Contagion in Numeric Operations}. A @i{conforming program} can control the order of processing explicitly by separating the operations into separate (possibly nested) @i{function forms}, or by writing explicit calls to @i{functions} that perform coercions. @node Examples of Associativity and Commutativity in Numeric Operations, Contagion in Numeric Operations, Associativity and Commutativity in Numeric Operations, Numeric Operations @subsubsection Examples of Associativity and Commutativity in Numeric Operations Consider the following expression, in which we assume that @t{1.0} and @t{1.0e-15} both denote @i{single floats}: @example (+ 1/3 2/3 1.0d0 1.0 1.0e-15) @end example One @i{conforming implementation} might process the @i{arguments} from left to right, first adding @t{1/3} and @t{2/3} to get @t{1}, then converting that to a @i{double float} for combination with @t{1.0d0}, then successively converting and adding @t{1.0} and @t{1.0e-15}. Another @i{conforming implementation} might process the @i{arguments} from right to left, first performing a @i{single float} addition of @t{1.0} and @t{1.0e-15} (perhaps losing accuracy in the process), then converting the sum to a @i{double float} and adding @t{1.0d0}, then converting @t{2/3} to a @i{double float} and adding it, and then converting @t{1/3} and adding that. A third @i{conforming implementation} might first scan all the @i{arguments}, process all the @i{rationals} first to keep that part of the computation exact, then find an @i{argument} of the largest floating-point format among all the @i{arguments} and add that, and then add in all other @i{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 @i{conforming program} could control the order by writing, for example, @example (+ (+ 1/3 2/3) (+ 1.0d0 1.0e-15) 1.0) @end example @node Contagion in Numeric Operations, Viewing Integers as Bits and Bytes, Examples of Associativity and Commutativity in Numeric Operations, Numeric Operations @subsubsection Contagion in Numeric Operations For information about the contagion rules for implicit coercions of @i{arguments} in numeric operations, see @ref{Rule of Float Precision Contagion}, @ref{Rule of Float and Rational Contagion}, and @ref{Rule of Complex Contagion}. @node Viewing Integers as Bits and Bytes, Logical Operations on Integers, Contagion in Numeric Operations, Numeric Operations @subsubsection Viewing Integers as Bits and Bytes @node Logical Operations on Integers, Byte Operations on Integers, Viewing Integers as Bits and Bytes, Numeric Operations @subsubsection Logical Operations on Integers Logical operations require @i{integers} as arguments; an error of @i{type} @b{type-error} should be signaled if an argument is supplied that is not an @i{integer}. @i{Integer} arguments to logical operations are treated as if they were represented in two's-complement notation. Figure 12--5 shows @i{defined names} relating to logical operations on numbers. @group @noindent @w{ ash boole-ior logbitp } @w{ boole boole-nand logcount } @w{ boole-1 boole-nor logeqv } @w{ boole-2 boole-orc1 logior } @w{ boole-and boole-orc2 lognand } @w{ boole-andc1 boole-set lognor } @w{ boole-andc2 boole-xor lognot } @w{ boole-c1 integer-length logorc1 } @w{ boole-c2 logand logorc2 } @w{ boole-clr logandc1 logtest } @w{ boole-eqv logandc2 logxor } @noindent @w{ Figure 12--5: Defined names relating to logical operations on numbers.} @end group @node Byte Operations on Integers, , Logical Operations on Integers, Numeric Operations @subsubsection Byte Operations on Integers The byte-manipulation @i{functions} use @i{objects} called @i{byte specifiers} to designate the size and position of a specific @i{byte} within an @i{integer}. The representation of a @i{byte specifier} is @i{implementation-dependent}; it might or might not be a @i{number}. The @i{function} @b{byte} will construct a @i{byte specifier}, which various other byte-manipulation @i{functions} will accept. Figure 12--6 shows @i{defined names} relating to manipulating @i{bytes} of @i{numbers}. @group @noindent @w{ byte deposit-field ldb-test } @w{ byte-position dpb mask-field } @w{ byte-size ldb } @noindent @w{ Figure 12--6: Defined names relating to byte manipulation.} @end group @node Implementation-Dependent Numeric Constants, Rational Computations, Numeric Operations, Number Concepts @subsection Implementation-Dependent Numeric Constants Figure 12--7 shows @i{defined names} relating to @i{implementation-dependent} details about @i{numbers}. @group @noindent @w{ double-float-epsilon most-negative-fixnum } @w{ double-float-negative-epsilon most-negative-long-float } @w{ least-negative-double-float most-negative-short-float } @w{ least-negative-long-float most-negative-single-float } @w{ least-negative-short-float most-positive-double-float } @w{ least-negative-single-float most-positive-fixnum } @w{ least-positive-double-float most-positive-long-float } @w{ least-positive-long-float most-positive-short-float } @w{ least-positive-short-float most-positive-single-float } @w{ least-positive-single-float short-float-epsilon } @w{ long-float-epsilon short-float-negative-epsilon } @w{ long-float-negative-epsilon single-float-epsilon } @w{ most-negative-double-float single-float-negative-epsilon } @noindent @w{ Figure 12--7: Defined names relating to implementation-dependent details about numbers.} @end group @node Rational Computations, Floating-point Computations, Implementation-Dependent Numeric Constants, Number Concepts @subsection Rational Computations The rules in this section apply to @i{rational} computations. @menu * Rule of Unbounded Rational Precision:: * Rule of Canonical Representation for Rationals:: * Rule of Float Substitutability:: @end menu @node Rule of Unbounded Rational Precision, Rule of Canonical Representation for Rationals, Rational Computations, Rational Computations @subsubsection Rule of Unbounded Rational Precision Rational computations cannot overflow in the usual sense (though there may not be enough storage to represent a result), since @i{integers} and @i{ratios} may in principle be of any magnitude. @node Rule of Canonical Representation for Rationals, Rule of Float Substitutability, Rule of Unbounded Rational Precision, Rational Computations @subsubsection Rule of Canonical Representation for Rationals If any computation produces a result that is a mathematical ratio of two integers such that the denominator evenly divides the numerator, then the result is converted to the equivalent @i{integer}. If the denominator does not evenly divide the numerator, the canonical representation of a @i{rational} number is as the @i{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 @t{-0} always denotes the @i{integer} @t{0}. A @i{conforming implementation} must not have a representation of ``minus zero'' for @i{integers} that is distinct from its representation of zero for @i{integers}. However, such a distinction is possible for @i{floats}; see the @i{type} @b{float}. @node Rule of Float Substitutability, , Rule of Canonical Representation for Rationals, Rational Computations @subsubsection Rule of Float Substitutability When the arguments to an irrational mathematical @i{function} [Reviewer Note by Barmar: There should be a table of these functions.] are all @i{rational} and the true mathematical result is also (mathematically) rational, then unless otherwise noted an implementation is free to return either an accurate @i{rational} result or a @i{single float} approximation. If the arguments are all @i{rational} but the result cannot be expressed as a @i{rational} number, then a @i{single float} approximation is always returned. If the arguments to a mathematical @i{function} are all of type @t{(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 @t{(or rational (complex rational))} or a @i{single float} (permissible only if the imaginary part of the true mathematical result is zero) or @t{(complex single-float)}. If the arguments are all of type @t{(or rational (complex rational))} but the result cannot be expressed as a @i{rational} or @i{complex rational}, then the returned value will be of @i{type} @b{single-float} (permissible only if the imaginary part of the true mathematical result is zero) or @t{(complex single-float)}. @group @noindent @w{ Function Sample Results } @w{ @b{abs} @t{(abs #c(3 4)) @result{} 5 @i{or} 5.0} } @w{ @b{acos} @t{(acos 1) @result{} 0 @i{or} 0.0} } @w{ @b{acosh} @t{(acosh 1) @result{} 0 @i{or} 0.0} } @w{ @b{asin} @t{(asin 0) @result{} 0 @i{or} 0.0} } @w{ @b{asinh} @t{(asinh 0) @result{} 0 @i{or} 0.0} } @w{ @b{atan} @t{(atan 0) @result{} 0 @i{or} 0.0} } @w{ @b{atanh} @t{(atanh 0) @result{} 0 @i{or} 0.0} } @w{ @b{cis} @t{(cis 0) @result{} #c(1 0) @i{or} #c(1.0 0.0)} } @w{ @b{cos} @t{(cos 0) @result{} 1 @i{or} 1.0} } @w{ @b{cosh} @t{(cosh 0) @result{} 1 @i{or} 1.0} } @w{ @b{exp} @t{(exp 0) @result{} 1 @i{or} 1.0} } @w{ @b{expt} @t{(expt 8 1/3) @result{} 2 @i{or} 2.0} } @w{ @b{log} @t{(log 1) @result{} 0 @i{or} 0.0} } @w{ @t{(log 8 2) @result{} 3 @i{or} 3.0} } @w{ @b{phase} @t{(phase 7) @result{} 0 @i{or} 0.0} } @w{ @b{signum} @t{(signum #c(3 4)) @result{} #c(3/5 4/5) @i{or} #c(0.6 0.8)} } @w{ @b{sin} @t{(sin 0) @result{} 0 @i{or} 0.0} } @w{ @b{sinh} @t{(sinh 0) @result{} 0 @i{or} 0.0} } @w{ @b{sqrt} @t{(sqrt 4) @result{} 2 @i{or} 2.0} } @w{ @t{(sqrt 9/16) @result{} 3/4 @i{or} 0.75} } @w{ @b{tan} @t{(tan 0) @result{} 0 @i{or} 0.0} } @w{ @b{tanh} @t{(tanh 0) @result{} 0 @i{or} 0.0} } @noindent @w{ Figure 12--8: Functions Affected by Rule of Float Substitutability} @end group @node Floating-point Computations, Complex Computations, Rational Computations, Number Concepts @subsection Floating-point Computations The following rules apply to floating point computations. @menu * Rule of Float and Rational Contagion:: * Examples of Rule of Float and Rational Contagion:: * Rule of Float Approximation:: * Rule of Float Underflow and Overflow:: * Rule of Float Precision Contagion:: @end menu @node Rule of Float and Rational Contagion, Examples of Rule of Float and Rational Contagion, Floating-point Computations, Floating-point Computations @subsubsection Rule of Float and Rational Contagion When @i{rationals} and @i{floats} are combined by a numerical function, the @i{rational} is first converted to a @i{float} of the same format. For @i{functions} such as @b{+} that take more than two arguments, it is permitted that part of the operation be carried out exactly using @i{rationals} and the rest be done using floating-point arithmetic. When @i{rationals} and @i{floats} are compared by a numerical function, the @i{function} @b{rational} is effectively called to convert the @i{float} to a @i{rational} and then an exact comparison is performed. In the case of @i{complex} numbers, the real and imaginary parts are effectively handled individually. @node Examples of Rule of Float and Rational Contagion, Rule of Float Approximation, Rule of Float and Rational Contagion, Floating-point Computations @subsubsection Examples of Rule of Float and Rational Contagion @example ;;;; 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) @result{} 1.0 (- 1/2 0.5d0) @result{} 0.0d0 (+ 0.5 -0.5 1/2) @result{} 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)) @result{} @i{true} (< 5/7 (rational (float 5/7))) @result{} @i{true} (< (float 5/7) (float 5/7)) @result{} @i{false} @end example @node Rule of Float Approximation, Rule of Float Underflow and Overflow, Examples of Rule of Float and Rational Contagion, Floating-point Computations @subsubsection Rule of Float Approximation Computations with @i{floats} are only approximate, although they are described as if the results were mathematically accurate. Two mathematically identical expressions may be computationally different because of errors inherent in the floating-point approximation process. The precision of a @i{float} is not necessarily correlated with the accuracy of that number. For instance, 3.142857142857142857 is a more precise approximation to \pi than 3.14159, but the latter is more accurate. The precision refers to the number of bits retained in the representation. When an operation combines a @i{short float} with a @i{long float}, the result will be a @i{long float}. @r{Common Lisp} functions assume that the accuracy of arguments to them does not exceed their precision. Therefore when two @i{small floats} are combined, the result is a @i{small float}. @r{Common Lisp} functions never convert automatically from a larger size to a smaller one. @node Rule of Float Underflow and Overflow, Rule of Float Precision Contagion, Rule of Float Approximation, Floating-point Computations @subsubsection Rule of Float Underflow and Overflow An error of @i{type} @b{floating-point-overflow} or @b{floating-point-underflow} should be signaled if a floating-point computation causes exponent overflow or underflow, respectively. @node Rule of Float Precision Contagion, , Rule of Float Underflow and Overflow, Floating-point Computations @subsubsection Rule of Float Precision Contagion The result of a numerical function is a @i{float} of the largest format among all the floating-point arguments to the @i{function}. @node Complex Computations, Interval Designators, Floating-point Computations, Number Concepts @subsection Complex Computations The following rules apply to @i{complex} computations: @menu * Rule of Complex Substitutability:: * Rule of Complex Contagion:: * Rule of Canonical Representation for Complex Rationals:: * Examples of Rule of Canonical Representation for Complex Rationals:: * Principal Values and Branch Cuts:: @end menu @node Rule of Complex Substitutability, Rule of Complex Contagion, Complex Computations, Complex Computations @subsubsection Rule of Complex Substitutability Except during the execution of irrational and transcendental @i{functions}, no numerical @i{function} ever @i{yields} a @i{complex} unless one or more of its @i{arguments} is a @i{complex}. @node Rule of Complex Contagion, Rule of Canonical Representation for Complex Rationals, Rule of Complex Substitutability, Complex Computations @subsubsection Rule of Complex Contagion When a @i{real} and a @i{complex} are both part of a computation, the @i{real} is first converted to a @i{complex} by providing an imaginary part of @t{0}. @node Rule of Canonical Representation for Complex Rationals, Examples of Rule of Canonical Representation for Complex Rationals, Rule of Complex Contagion, Complex Computations @subsubsection Rule of Canonical Representation for Complex Rationals If the result of any computation would be a @i{complex} number whose real part is of @i{type} @b{rational} and whose imaginary part is zero, the result is converted to the @i{rational} which is the real part. This rule does not apply to @i{complex} numbers whose parts are @i{floats}. For example, @t{#C(5 0)} and @t{5} are not @i{different} @i{objects} in @r{Common Lisp} (they are always the @i{same} under @b{eql}); @t{#C(5.0 0.0)} and @t{5.0} are always @i{different} @i{objects} in @r{Common Lisp} (they are never the @i{same} under @b{eql}, although they are the @i{same} under @b{equalp} and @b{=}). @node Examples of Rule of Canonical Representation for Complex Rationals, Principal Values and Branch Cuts, Rule of Canonical Representation for Complex Rationals, Complex Computations @subsubsection Examples of Rule of Canonical Representation for Complex Rationals @example #c(1.0 1.0) @result{} #C(1.0 1.0) #c(0.0 0.0) @result{} #C(0.0 0.0) #c(1.0 1) @result{} #C(1.0 1.0) #c(0.0 0) @result{} #C(0.0 0.0) #c(1 1) @result{} #C(1 1) #c(0 0) @result{} 0 (typep #c(1 1) '(complex (eql 1))) @result{} @i{true} (typep #c(0 0) '(complex (eql 0))) @result{} @i{false} @end example @node Principal Values and Branch Cuts, , Examples of Rule of Canonical Representation for Complex Rationals, Complex Computations @subsubsection Principal Values and Branch Cuts Many of the irrational and transcendental functions are multiply defined in the complex domain; for example, there are in general an infinite number of complex values for the logarithm function. In each such case, a @i{principal} @i{value} must be chosen for the function to return. In general, such values cannot be chosen so as to make the range continuous; lines in the domain called branch cuts must be defined, which in turn define the discontinuities in the range. @r{Common Lisp} defines the branch cuts, @i{principal} @i{values}, and boundary conditions for the complex functions following ``{Principal Values and Branch Cuts in Complex APL}.'' The branch cut rules that apply to each function are located with the description of that function. Figure 12--9 lists the identities that are obeyed throughout the applicable portion of the complex domain, even on the branch cuts: @group @noindent @w{ sin i z = i sinh z sinh i z = i sin z arctan i z = i arctanh z } @w{ cos i z = cosh z cosh i z = cos z arcsinh i z = i arcsin z } @w{ tan i z = i tanh z arcsin i z = i arcsinh z arctanh i z = i arctan z } @noindent @w{ Figure 12--9: Trigonometric Identities for Complex Domain } @end group The quadrant numbers referred to in the discussions of branch cuts are as illustrated in Figure 12--10. @example Imaginary Axis | | II | I | | | ______________________________________ Real Axis | | | III | IV | | | | @end example @w{ Figure 12--9: Quadrant Numbering for Branch Cuts} @node Interval Designators, Random-State Operations, Complex Computations, Number Concepts @subsection Interval Designators The @i{compound type specifier} form of the numeric @i{type specifiers} in Figure 12--10 permit the user to specify an interval on the real number line which describe a @i{subtype} of the @i{type} which would be described by the corresponding @i{atomic type specifier}. A @i{subtype} of some @i{type} @i{T} is specified using an ordered pair of @i{objects} called @i{interval designators} for @i{type} @i{T}. The first of the two @i{interval designators} for @i{type} @i{T} can be any of the following: @table @asis @item a number @i{N} of @i{type} @i{T} This denotes a lower inclusive bound of @i{N}. That is, @i{elements} of the @i{subtype} of @i{T} will be greater than or equal to @i{N}. @item a @i{singleton} @i{list} whose @i{element} is a number @i{M} of @i{type} @i{T} This denotes a lower exclusive bound of @i{M}. That is, @i{elements} of the @i{subtype} of @i{T} will be greater than @i{M}. @item the symbol @b{*} This denotes the absence of a lower bound on the interval. @end table The second of the two @i{interval designators} for @i{type} @i{T} can be any of the following: @table @asis @item a number @i{N} of @i{type} @i{T} This denotes an upper inclusive bound of @i{N}. That is, @i{elements} of the @i{subtype} of @i{T} will be less than or equal to @i{N}. @item a @i{singleton} @i{list} whose @i{element} is a number @i{M} of @i{type} @i{T} This denotes an upper exclusive bound of @i{M}. That is, @i{elements} of the @i{subtype} of @i{T} will be less than @i{M}. @item the symbol @b{*} This denotes the absence of an upper bound on the interval. @end table @node Random-State Operations, , Interval Designators, Number Concepts @subsection Random-State Operations Figure 12--10 lists some @i{defined names} that are applicable to @i{random states}. @group @noindent @w{ *random-state* random } @w{ make-random-state random-state-p } @noindent @w{ Figure 12--10: Random-state defined names} @end group @c end of including concept-numbers @node Numbers Dictionary, , Number Concepts, Numbers (Numbers) @section Numbers Dictionary @c including dict-numbers @menu * number:: * complex (System Class):: * real:: * float (System Class):: * short-float:: * rational:: * ratio:: * integer:: * signed-byte:: * unsigned-byte:: * mod:: * bit:: * fixnum:: * bignum:: * =:: * max:: * minusp:: * zerop:: * floor:: * sin:: * asin:: * pi:: * sinh:: * *:: * +:: * -:: * /:: * 1+:: * abs:: * evenp:: * exp:: * gcd:: * incf:: * lcm:: * log:: * mod:: * signum:: * sqrt:: * random-state:: * make-random-state:: * random:: * random-state-p:: * *random-state*:: * numberp:: * cis:: * complex:: * complexp:: * conjugate:: * phase:: * realpart:: * upgraded-complex-part-type:: * realp:: * numerator:: * rational:: * rationalp:: * ash:: * integer-length:: * integerp:: * parse-integer:: * boole:: * boole-1:: * logand:: * logbitp:: * logcount:: * logtest:: * byte:: * deposit-field:: * dpb:: * ldb:: * ldb-test:: * mask-field:: * most-positive-fixnum:: * decode-float:: * float:: * floatp:: * most-positive-short-float:: * short-float-epsilon:: * arithmetic-error:: * arithmetic-error-operands:: * division-by-zero:: * floating-point-invalid-operation:: * floating-point-inexact:: * floating-point-overflow:: * floating-point-underflow:: @end menu @node number, complex (System Class), Numbers Dictionary, Numbers Dictionary @subsection number [System Class] @subsubheading Class Precedence List:: @b{number}, @b{t} @subsubheading Description:: The @i{type} @b{number} contains @i{objects} which represent mathematical numbers. The @i{types} @b{real} and @b{complex} are @i{disjoint} @i{subtypes} of @b{number}. The @i{function} @b{=} tests for numerical equality. The @i{function} @b{eql}, when its arguments are both @i{numbers}, tests that they have both the same @i{type} and numerical value. Two @i{numbers} that are the @i{same} under @b{eql} or @b{=} are not necessarily the @i{same} under @b{eq}. @subsubheading Notes:: @r{Common Lisp} differs from mathematics on some naming issues. In mathematics, the set of real numbers is traditionally described as a subset of the complex numbers, but in @r{Common Lisp}, the @i{type} @b{real} and the @i{type} @b{complex} are disjoint. The @r{Common Lisp} type which includes all mathematical complex numbers is called @b{number}. The reasons for these differences include historical precedent, compatibility with most other popular computer languages, and various issues of time and space efficiency. @node complex (System Class), real, number, Numbers Dictionary @subsection complex [System Class] @subsubheading Class Precedence List:: @b{complex}, @b{number}, @b{t} @subsubheading Description:: The @i{type} @b{complex} includes all mathematical complex numbers other than those included in the @i{type} @b{rational}. @i{Complexes} are expressed in Cartesian form with a real part and an imaginary part, each of which is a @i{real}. The real part and imaginary part are either both @i{rational} or both of the same @i{float} @i{type}. The imaginary part can be a @i{float} zero, but can never be a @i{rational} zero, for such a number is always represented by @r{Common Lisp} as a @i{rational} rather than a @i{complex}. @subsubheading Compound Type Specifier Kind:: Specializing. @subsubheading Compound Type Specifier Syntax:: (@code{complex}@{@i{@t{[}typespec | @b{*}@t{]}}@}) @subsubheading Compound Type Specifier Arguments:: @i{typespec}---a @i{type specifier} that denotes a @i{subtype} of @i{type} @b{real}. @subsubheading Compound Type Specifier Description:: [Editorial Note by KMP: If you ask me, this definition is a complete mess. Looking at issue ARRAY-TYPE-ELEMENT-TYPE-SEMANTICS:UNIFY-UPGRADING does not help me figure it out, either. Anyone got any suggestions?] Every element of this @i{type} is a @i{complex} whose real part and imaginary part are each of type @t{(upgraded-complex-part-type @i{typespec})}. This @i{type} encompasses those @i{complexes} that can result by giving numbers of @i{type} @i{typespec} to @b{complex}. @t{(complex @i{type-specifier})} refers to all @i{complexes} that can result from giving @i{numbers} of @i{type} @i{type-specifier} to the @i{function} @b{complex}, plus all other @i{complexes} of the same specialized representation. @subsubheading See Also:: @ref{Rule of Canonical Representation for Complex Rationals}, @ref{Constructing Numbers from Tokens}, @ref{Printing Complexes} @subsubheading Notes:: The input syntax for a @i{complex} with real part r and imaginary part i is @t{#C(r i)}. For further details, see @ref{Standard Macro Characters}. For every @i{float}, n, there is a @i{complex} which represents the same mathematical number and which can be obtained by @t{(COERCE n 'COMPLEX)}. @node real, float (System Class), complex (System Class), Numbers Dictionary @subsection real [System Class] @subsubheading Class Precedence List:: @b{real}, @b{number}, @b{t} @subsubheading Description:: The @i{type} @b{real} includes all @i{numbers} that represent mathematical real numbers, though there are mathematical real numbers (@i{e.g.}, irrational numbers) that do not have an exact representation in @r{Common Lisp}. Only @i{reals} can be ordered using the @b{<}, @b{>}, @b{<=}, and @b{>=} functions. The @i{types} @b{rational} and @b{float} are @i{disjoint} @i{subtypes} of @i{type} @b{real}. @subsubheading Compound Type Specifier Kind:: Abbreviating. @subsubheading Compound Type Specifier Syntax:: (@code{real}@{@i{@t{[}lower-limit @r{[}upper-limit@r{]}@t{]}}@}) @subsubheading Compound Type Specifier Arguments:: @i{lower-limit}, @i{upper-limit}---@i{interval designators} for @i{type} @b{real}. The defaults for each of @i{lower-limit} and @i{upper-limit} is the @i{symbol} @b{*}. @subsubheading Compound Type Specifier Description:: This denotes the @i{reals} on the interval described by @i{lower-limit} and @i{upper-limit}. @node float (System Class), short-float, real, Numbers Dictionary @subsection float [System Class] @subsubheading Class Precedence List:: @b{float}, @b{real}, @b{number}, @b{t} @subsubheading Description:: A @i{float} is a mathematical rational (but @i{not} a @r{Common Lisp} @i{rational}) of the form s\cdot f\cdot b^{e-p}, where s is +1 or -1, the @i{sign}; b is an @i{integer} greater than~1, the @i{base} or @i{radix} of the representation; p is a positive @i{integer}, the @i{precision} (in base-b digits) of the @i{float}; f is a positive @i{integer} between b^{p-1} and b^p-1 (inclusive), the significand; and e is an @i{integer}, the exponent. The value of p and the range of~e depends on the implementation and on the type of @i{float} within that implementation. In addition, there is a floating-point zero; depending on the implementation, there can also be a ``minus zero''. If there is no minus zero, then 0.0 and~-0.0 are both interpreted as simply a floating-point zero. @t{(= 0.0 -0.0)} is always true. If there is a minus zero, @t{(eql -0.0 0.0)} is @i{false}, otherwise it is @i{true}. [Reviewer Note by Barmar: What about IEEE NaNs and infinities?] [Reviewer Note by RWK: In the following, what is the ``ordering''? precision? range? Can there be additional subtypes of float or does ``others'' in the list of four?] The @i{types} @b{short-float}, @b{single-float}, @b{double-float}, and @b{long-float} are @i{subtypes} of @i{type} @b{float}. Any two of them must be either @i{disjoint} @i{types} or the @i{same} @i{type}; if the @i{same} @i{type}, then any other @i{types} between them in the above ordering must also be the @i{same} @i{type}. For example, if the @i{type} @b{single-float} and the @i{type} @b{long-float} are the @i{same} @i{type}, then the @i{type} @b{double-float} must be the @i{same} @i{type} also. @subsubheading Compound Type Specifier Kind:: Abbreviating. @subsubheading Compound Type Specifier Syntax:: (@code{float}@{@i{@t{[}lower-limit @r{[}upper-limit@r{]}@t{]}}@}) @subsubheading Compound Type Specifier Arguments:: @i{lower-limit}, @i{upper-limit}---@i{interval designators} for @i{type} @b{float}. The defaults for each of @i{lower-limit} and @i{upper-limit} is the @i{symbol} @b{*}. @subsubheading Compound Type Specifier Description:: This denotes the @i{floats} on the interval described by @i{lower-limit} and @i{upper-limit}. @subsubheading See Also:: {@i{Figure~2--9}}, @ref{Constructing Numbers from Tokens}, @ref{Printing Floats} @subsubheading Notes:: Note that all mathematical integers are representable not only as @r{Common Lisp} @i{reals}, but also as @i{complex floats}. For example, possible representations of the mathematical number 1 include the @i{integer} @t{1}, the @i{float} @t{1.0}, or the @i{complex} @t{#C(1.0 0.0)}. @node short-float, rational, float (System Class), Numbers Dictionary @subsection short-float, single-float, double-float, long-float [Type] @subsubheading Supertypes:: @b{short-float}: @b{short-float}, @b{float}, @b{real}, @b{number}, @b{t} @b{single-float}: @b{single-float}, @b{float}, @b{real}, @b{number}, @b{t} @b{double-float}: @b{double-float}, @b{float}, @b{real}, @b{number}, @b{t} @b{long-float}: @b{long-float}, @b{float}, @b{real}, @b{number}, @b{t} @subsubheading Description:: For the four defined @i{subtypes} of @i{type} @b{float}, it is true that intermediate between the @i{type} @b{short-float} and the @i{type} @b{long-float} are the @i{type} @b{single-float} and the @i{type} @b{double-float}. The precise definition of these categories is @i{implementation-defined}. The precision (measured in ``bits'', computed as p\log_2b) and the exponent size (also measured in ``bits,'' computed as \log_2(n+1), where n is the maximum exponent value) is recommended to be at least as great as the values in Figure 12--11. Each of the defined @i{subtypes} of @i{type} @b{float} might or might not have a minus zero. @group @noindent @w{ @b{Format} @b{Minimum Precision} @b{Minimum Exponent Size} } @w{ __________________________________________________} @w{ Short 13 bits 5 bits } @w{ Single 24 bits 8 bits } @w{ Double 50 bits 8 bits } @w{ Long 50 bits 8 bits } @noindent @w{ Figure 12--11: Recommended Minimum Floating-Point Precision and Exponent Size} @end group There can be fewer than four internal representations for @i{floats}. If there are fewer distinct representations, the following rules apply: @table @asis @item -- If there is only one, it is the @i{type} @b{single-float}. In this representation, an @i{object} is simultaneously of @i{types} @b{single-float}, @b{double-float}, @b{short-float}, and @b{long-float}. @item -- Two internal representations can be arranged in either of the following ways: @table @asis @item @t{*} Two @i{types} are provided: @b{single-float} and @b{short-float}. An @i{object} is simultaneously of @i{types} @b{single-float}, @b{double-float}, and @b{long-float}. @item @t{*} Two @i{types} are provided: @b{single-float} and @b{double-float}. An @i{object} is simultaneously of @i{types} @b{single-float} and @b{short-float}, or @b{double-float} and @b{long-float}. @end table @item -- Three internal representations can be arranged in either of the following ways: @table @asis @item @t{*} Three @i{types} are provided: @b{short-float}, @b{single-float}, and @b{double-float}. An @i{object} can simultaneously be of @i{type} @b{double-float} and @b{long-float}. @item @t{*} Three @i{types} are provided: @b{single-float}, @b{double-float}, and @b{long-float}. An @i{object} can simultaneously be of @i{types} @b{single-float} and @b{short-float}. @end table @end table @subsubheading Compound Type Specifier Kind:: Abbreviating. @subsubheading Compound Type Specifier Syntax:: (@code{short-float}@{@i{@t{[}short-lower-limit @r{[}short-upper-limit@r{]}@t{]}}@}) (@code{single-float}@{@i{@t{[}single-lower-limit @r{[}single-upper-limit@r{]}@t{]}}@}) (@code{double-float}@{@i{@t{[}double-lower-limit @r{[}double-upper-limit@r{]}@t{]}}@}) (@code{long-float}@{@i{@t{[}long-lower-limit @r{[}long-upper-limit@r{]}@t{]}}@}) @subsubheading Compound Type Specifier Arguments:: @i{short-lower-limit}, @i{short-upper-limit}---@i{interval designators} for @i{type} @b{short-float}. The defaults for each of @i{lower-limit} and @i{upper-limit} is the @i{symbol} @b{*}. @i{single-lower-limit}, @i{single-upper-limit}---@i{interval designators} for @i{type} @b{single-float}. The defaults for each of @i{lower-limit} and @i{upper-limit} is the @i{symbol} @b{*}. @i{double-lower-limit}, @i{double-upper-limit}---@i{interval designators} for @i{type} @b{double-float}. The defaults for each of @i{lower-limit} and @i{upper-limit} is the @i{symbol} @b{*}. @i{long-lower-limit}, @i{long-upper-limit}---@i{interval designators} for @i{type} @b{long-float}. The defaults for each of @i{lower-limit} and @i{upper-limit} is the @i{symbol} @b{*}. @subsubheading Compound Type Specifier Description:: Each of these denotes the set of @i{floats} of the indicated @i{type} that are on the interval specified by the @i{interval designators}. @node rational, ratio, short-float, Numbers Dictionary @subsection rational [System Class] @subsubheading Class Precedence List:: @b{rational}, @b{real}, @b{number}, @b{t} @subsubheading Description:: The canonical representation of a @i{rational} is as an @i{integer} if its value is integral, and otherwise as a @i{ratio}. The @i{types} @b{integer} and @b{ratio} are @i{disjoint} @i{subtypes} of @i{type} @b{rational}. @subsubheading Compound Type Specifier Kind:: Abbreviating. @subsubheading Compound Type Specifier Syntax:: (@code{rational}@{@i{@t{[}lower-limit @r{[}upper-limit@r{]}@t{]}}@}) @subsubheading Compound Type Specifier Arguments:: @i{lower-limit}, @i{upper-limit}---@i{interval designators} for @i{type} @b{rational}. The defaults for each of @i{lower-limit} and @i{upper-limit} is the @i{symbol} @b{*}. @subsubheading Compound Type Specifier Description:: This denotes the @i{rationals} on the interval described by @i{lower-limit} and @i{upper-limit}. @node ratio, integer, rational, Numbers Dictionary @subsection ratio [System Class] @subsubheading Class Precedence List:: @b{ratio}, @b{rational}, @b{real}, @b{number}, @b{t} @subsubheading Description:: A @i{ratio} is a @i{number} representing the mathematical ratio of two non-zero integers, the numerator and denominator, whose greatest common divisor is one, and of which the denominator is positive and greater than one. @subsubheading See Also:: {@i{Figure~2--9}}, @ref{Constructing Numbers from Tokens}, @ref{Printing Ratios} @node integer, signed-byte, ratio, Numbers Dictionary @subsection integer [System Class] @subsubheading Class Precedence List:: @b{integer}, @b{rational}, @b{real}, @b{number}, @b{t} @subsubheading Description:: An @i{integer} is a mathematical integer. There is no limit on the magnitude of an @i{integer}. The @i{types} @b{fixnum} and @b{bignum} form an @i{exhaustive partition} of @i{type} @b{integer}. @subsubheading Compound Type Specifier Kind:: Abbreviating. @subsubheading Compound Type Specifier Syntax:: (@code{integer}@{@i{@t{[}lower-limit @r{[}upper-limit@r{]}@t{]}}@}) @subsubheading Compound Type Specifier Arguments:: @i{lower-limit}, @i{upper-limit}---@i{interval designators} for @i{type} @b{integer}. The defaults for each of @i{lower-limit} and @i{upper-limit} is the @i{symbol} @b{*}. @subsubheading Compound Type Specifier Description:: This denotes the @i{integers} on the interval described by @i{lower-limit} and @i{upper-limit}. @subsubheading See Also:: {@i{Figure~2--9}}, @ref{Constructing Numbers from Tokens}, @ref{Printing Integers} @subsubheading Notes:: The @i{type} @t{(integer @i{lower} @i{upper})}, where @i{lower} and @i{upper} are @b{most-negative-fixnum} and @b{most-positive-fixnum}, respectively, is also called @b{fixnum}. The @i{type} @t{(integer 0 1)} is also called @b{bit}. The @i{type} @t{(integer 0 *)} is also called @b{unsigned-byte}. @node signed-byte, unsigned-byte, integer, Numbers Dictionary @subsection signed-byte [Type] @subsubheading Supertypes:: @b{signed-byte}, @b{integer}, @b{rational}, @b{real}, @b{number}, @b{t} @subsubheading Description:: The atomic @i{type specifier} @b{signed-byte} denotes the same type as is denoted by the @i{type specifier} @b{integer}; however, the list forms of these two @i{type specifiers} have different semantics. @subsubheading Compound Type Specifier Kind:: Abbreviating. @subsubheading Compound Type Specifier Syntax:: (@code{signed-byte}@{@i{@t{[}s | @b{*}@t{]}}@}) @subsubheading Compound Type Specifier Arguments:: @i{s}---a positive @i{integer}. @subsubheading Compound Type Specifier Description:: This denotes the set of @i{integers} that can be represented in two's-complement form in a @i{byte} of @i{s} bits. This is equivalent to @t{(integer -2^{s-1} 2^{s-1}-1)}. The type @b{signed-byte} or the type @t{(signed-byte *)} is the same as the @i{type} @b{integer}. @node unsigned-byte, mod, signed-byte, Numbers Dictionary @subsection unsigned-byte [Type] @subsubheading Supertypes:: @b{unsigned-byte}, @b{signed-byte}, @b{integer}, @b{rational}, @b{real}, @b{number}, @b{t} @subsubheading Description:: The atomic @i{type specifier} @b{unsigned-byte} denotes the same type as is denoted by the @i{type specifier} @t{(integer 0 *)}. @subsubheading Compound Type Specifier Kind:: Abbreviating. @subsubheading Compound Type Specifier Syntax:: (@code{unsigned-byte}@{@i{@t{[}@i{s} | @b{*}@t{]}}@}) @subsubheading Compound Type Specifier Arguments:: @i{s}---a positive @i{integer}. @subsubheading Compound Type Specifier Description:: This denotes the set of non-negative @i{integers} that can be represented in a byte of size @i{s} (bits). This is equivalent to @t{(mod @i{m})} for @i{m}=2^s, or to @t{(integer 0 @i{n})} for @i{n}=2^s-1. The @i{type} @b{unsigned-byte} or the type @t{(unsigned-byte *)} is the same as the type @t{(integer 0 *)}, the set of non-negative @i{integers}. @subsubheading Notes:: The @i{type} @t{(unsigned-byte 1)} is also called @b{bit}. @node mod, bit, unsigned-byte, Numbers Dictionary @subsection mod [Type Specifier] @subsubheading Compound Type Specifier Kind:: Abbreviating. @subsubheading Compound Type Specifier Syntax:: (@code{mod}@{@i{n}@}) @subsubheading Compound Type Specifier Arguments:: @i{n}---a positive @i{integer}. @subsubheading Compound Type Specifier Description:: This denotes the set of non-negative @i{integers} less than @i{n}. This is equivalent to @t{(integer 0 (@i{n}))} or to @t{(integer 0 @i{m})}, where @i{m}=@i{n}-1. The argument is required, and cannot be @b{*}. The symbol @b{mod} is not valid as a @i{type specifier}. @node bit, fixnum, mod, Numbers Dictionary @subsection bit [Type] @subsubheading Supertypes:: @b{bit}, @b{unsigned-byte}, @b{signed-byte}, @b{integer}, @b{rational}, @b{real}, @b{number}, @b{t} @subsubheading Description:: The @i{type} @b{bit} is equivalent to the @i{type} @t{(integer 0 1)} and @t{(unsigned-byte 1)}. @node fixnum, bignum, bit, Numbers Dictionary @subsection fixnum [Type] @subsubheading Supertypes:: @b{fixnum}, @b{integer}, @b{rational}, @b{real}, @b{number}, @b{t} @subsubheading Description:: A @i{fixnum} is an @i{integer} whose value is between @b{most-negative-fixnum} and @b{most-positive-fixnum} inclusive. Exactly which @i{integers} are @i{fixnums} is @i{implementation-defined}. The @i{type} @b{fixnum} is required to be a supertype of @t{(signed-byte 16)}. @node bignum, =, fixnum, Numbers Dictionary @subsection bignum [Type] @subsubheading Supertypes:: @b{bignum}, @b{integer}, @b{rational}, @b{real}, @b{number}, @b{t} @subsubheading Description:: The @i{type} @b{bignum} is defined to be exactly @t{(and integer (not fixnum))}. @node =, max, bignum, Numbers Dictionary @subsection =, /=, <, >, <=, >= [Function] @code{=} @i{{&rest} numbers^+} @result{} @i{generalized-boolean} @code{/=} @i{{&rest} numbers^+} @result{} @i{generalized-boolean} @code{<} @i{{&rest} numbers^+} @result{} @i{generalized-boolean} @code{>} @i{{&rest} numbers^+} @result{} @i{generalized-boolean} @code{<=} @i{{&rest} numbers^+} @result{} @i{generalized-boolean} @code{>=} @i{{&rest} numbers^+} @result{} @i{generalized-boolean} @subsubheading Arguments and Values:: @i{number}---for @b{<}, @b{>}, @b{<=}, @b{>=}: a @i{real}; for @b{=}, @b{/=}: a @i{number}. @i{generalized-boolean}---a @i{generalized boolean}. @subsubheading Description:: @b{=}, @b{/=}, @b{<}, @b{>}, @b{<=}, and @b{>=} perform arithmetic comparisons on their arguments as follows: @table @asis @item @b{=} The value of @b{=} is @i{true} if all @i{numbers} are the same in value; otherwise it is @i{false}. Two @i{complexes} are considered equal by @b{=} if their real and imaginary parts are equal according to @b{=}. @item @b{/=} The value of @b{/=} is @i{true} if no two @i{numbers} are the same in value; otherwise it is @i{false}. @item @b{<} The value of @b{<} is @i{true} if the @i{numbers} are in monotonically increasing order; otherwise it is @i{false}. @item @b{>} The value of @b{>} is @i{true} if the @i{numbers} are in monotonically decreasing order; otherwise it is @i{false}. @item @b{<=} The value of @b{<=} is @i{true} if the @i{numbers} are in monotonically nondecreasing order; otherwise it is @i{false}. @item @b{>=} The value of @b{>=} is @i{true} if the @i{numbers} are in monotonically nonincreasing order; otherwise it is @i{false}. @end table @b{=}, @b{/=}, @b{<}, @b{>}, @b{<=}, and @b{>=} perform necessary type conversions. @subsubheading Examples:: The uses of these functions are illustrated in Figure 12--12. @group @noindent @w{ @t{(= 3 3)} is @i{true}. @t{(/= 3 3)} is @i{false}. } @w{ @t{(= 3 5)} is @i{false}. @t{(/= 3 5)} is @i{true}. } @w{ @t{(= 3 3 3 3)} is @i{true}. @t{(/= 3 3 3 3)} is @i{false}. } @w{ @t{(= 3 3 5 3)} is @i{false}. @t{(/= 3 3 5 3)} is @i{false}. } @w{ @t{(= 3 6 5 2)} is @i{false}. @t{(/= 3 6 5 2)} is @i{true}. } @w{ @t{(= 3 2 3)} is @i{false}. @t{(/= 3 2 3)} is @i{false}. } @w{ @t{(< 3 5)} is @i{true}. @t{(<= 3 5)} is @i{true}. } @w{ @t{(< 3 -5)} is @i{false}. @t{(<= 3 -5)} is @i{false}. } @w{ @t{(< 3 3)} is @i{false}. @t{(<= 3 3)} is @i{true}. } @w{ @t{(< 0 3 4 6 7)} is @i{true}. @t{(<= 0 3 4 6 7)} is @i{true}. } @w{ @t{(< 0 3 4 4 6)} is @i{false}. @t{(<= 0 3 4 4 6)} is @i{true}. } @w{ @t{(> 4 3)} is @i{true}. @t{(>= 4 3)} is @i{true}. } @w{ @t{(> 4 3 2 1 0)} is @i{true}. @t{(>= 4 3 2 1 0)} is @i{true}. } @w{ @t{(> 4 3 3 2 0)} is @i{false}. @t{(>= 4 3 3 2 0)} is @i{true}. } @w{ @t{(> 4 3 1 2 0)} is @i{false}. @t{(>= 4 3 1 2 0)} is @i{false}. } @w{ @t{(= 3)} is @i{true}. @t{(/= 3)} is @i{true}. } @w{ @t{(< 3)} is @i{true}. @t{(<= 3)} is @i{true}. } @w{ @t{(= 3.0 #c(3.0 0.0))} is @i{true}. @t{(/= 3.0 #c(3.0 1.0))} is @i{true}. } @w{ @t{(= 3 3.0)} is @i{true}. @t{(= 3.0s0 3.0d0)} is @i{true}. } @w{ @t{(= 0.0 -0.0)} is @i{true}. @t{(= 5/2 2.5)} is @i{true}. } @w{ @t{(> 0.0 -0.0)} is @i{false}. @t{(= 0 -0.0)} is @i{true}. } @w{ @t{(<= 0 x 9)} is @i{true} if @t{x} is between @t{0} and @t{9}, inclusive} @w{ @t{(< 0.0 x 1.0)} is @i{true} if @t{x} is between @t{0.0} and @t{1.0}, exclusive} @w{ @t{(< -1 j (length v))} is @i{true} if @t{j} is a @i{valid array index} for a @i{vector} @t{v}} @noindent @w{ Figure 12--12: Uses of /=, =, <, >, <=, and >= } @end group @subsubheading Exceptional Situations:: Might signal @b{type-error} if some @i{argument} is not a @i{real}. Might signal @b{arithmetic-error} if otherwise unable to fulfill its contract. @subsubheading Notes:: @b{=} differs from @b{eql} in that @t{(= 0.0 -0.0)} is always true, because @b{=} compares the mathematical values of its operands, whereas @b{eql} compares the representational values, so to speak. @node max, minusp, =, Numbers Dictionary @subsection max, min [Function] @code{max} @i{{&rest} reals^+} @result{} @i{max-real} @code{min} @i{{&rest} reals^+} @result{} @i{min-real} @subsubheading Arguments and Values:: @i{real}---a @i{real}. @i{max-real}, @i{min-real}---a @i{real}. @subsubheading Description:: @b{max} returns the @i{real} that is greatest (closest to positive infinity). @b{min} returns the @i{real} that is least (closest to negative infinity). For @b{max}, the implementation has the choice of returning the largest argument as is or applying the rules of floating-point @i{contagion}, taking all the arguments into consideration for @i{contagion} purposes. Also, if one or more of the arguments are @b{=}, then any one of them may be chosen as the value to return. For example, if the @i{reals} are a mixture of @i{rationals} and @i{floats}, and the largest argument is a @i{rational}, then the implementation is free to produce either that @i{rational} or its @i{float} approximation; if the largest argument is a @i{float} of a smaller format than the largest format of any @i{float} argument, then the implementation is free to return the argument in its given format or expanded to the larger format. Similar remarks apply to @b{min} (replacing ``largest argument'' by ``smallest argument''). @subsubheading Examples:: @example (max 3) @result{} 3 (min 3) @result{} 3 (max 6 12) @result{} 12 (min 6 12) @result{} 6 (max -6 -12) @result{} -6 (min -6 -12) @result{} -12 (max 1 3 2 -7) @result{} 3 (min 1 3 2 -7) @result{} -7 (max -2 3 0 7) @result{} 7 (min -2 3 0 7) @result{} -2 (max 5.0 2) @result{} 5.0 (min 5.0 2) @result{} 2 @i{OR}@result{} 2.0 (max 3.0 7 1) @result{} 7 @i{OR}@result{} 7.0 (min 3.0 7 1) @result{} 1 @i{OR}@result{} 1.0 (max 1.0s0 7.0d0) @result{} 7.0d0 (min 1.0s0 7.0d0) @result{} 1.0s0 @i{OR}@result{} 1.0d0 (max 3 1 1.0s0 1.0d0) @result{} 3 @i{OR}@result{} 3.0d0 (min 3 1 1.0s0 1.0d0) @result{} 1 @i{OR}@result{} 1.0s0 @i{OR}@result{} 1.0d0 @end example @subsubheading Exceptional Situations:: Should signal an error of @i{type} @b{type-error} if any @i{number} is not a @i{real}. @node minusp, zerop, max, Numbers Dictionary @subsection minusp, plusp [Function] @code{minusp} @i{real} @result{} @i{generalized-boolean} @code{plusp} @i{real} @result{} @i{generalized-boolean} @subsubheading Arguments and Values:: @i{real}---a @i{real}. @i{generalized-boolean}---a @i{generalized boolean}. @subsubheading Description:: @b{minusp} returns @i{true} if @i{real} is less than zero; otherwise, returns @i{false}. @b{plusp} returns @i{true} if @i{real} is greater than zero; otherwise, returns @i{false}. Regardless of whether an @i{implementation} provides distinct representations for positive and negative @i{float} zeros, @t{(minusp -0.0)} always returns @i{false}. @subsubheading Examples:: @example (minusp -1) @result{} @i{true} (plusp 0) @result{} @i{false} (plusp least-positive-single-float) @result{} @i{true} @end example @subsubheading Exceptional Situations:: Should signal an error of @i{type} @b{type-error} if @i{real} is not a @i{real}. @node zerop, floor, minusp, Numbers Dictionary @subsection zerop [Function] @code{zerop} @i{number} @result{} @i{generalized-boolean} @subsubheading Pronunciation:: pronounced 'z\=e (, )r\=o{}(, )p\=e @subsubheading Arguments and Values:: @i{number}---a @i{number}. @i{generalized-boolean}---a @i{generalized boolean}. @subsubheading Description:: Returns @i{true} if @i{number} is zero (@i{integer}, @i{float}, or @i{complex}); otherwise, returns @i{false}. Regardless of whether an @i{implementation} provides distinct representations for positive and negative floating-point zeros, @t{(zerop -0.0)} always returns @i{true}. @subsubheading Examples:: @example (zerop 0) @result{} @i{true} (zerop 1) @result{} @i{false} (zerop -0.0) @result{} @i{true} (zerop 0/100) @result{} @i{true} (zerop #c(0 0.0)) @result{} @i{true} @end example @subsubheading Exceptional Situations:: Should signal an error of @i{type} @b{type-error} if @i{number} is not a @i{number}. @subsubheading Notes:: @example (zerop @i{number}) @equiv{} (= @i{number} 0) @end example @node floor, sin, zerop, Numbers Dictionary @subsection floor, ffloor, ceiling, fceiling, @subheading truncate, ftruncate, round, fround @flushright @i{[Function]} @end flushright @code{floor} @i{number {&optional} divisor} @result{} @i{quotient, remainder} @code{ffloor} @i{number {&optional} divisor} @result{} @i{quotient, remainder} @code{ceiling} @i{number {&optional} divisor} @result{} @i{quotient, remainder} @code{fceiling} @i{number {&optional} divisor} @result{} @i{quotient, remainder} @code{truncate} @i{number {&optional} divisor} @result{} @i{quotient, remainder} @code{ftruncate} @i{number {&optional} divisor} @result{} @i{quotient, remainder} @code{round} @i{number {&optional} divisor} @result{} @i{quotient, remainder} @code{fround} @i{number {&optional} divisor} @result{} @i{quotient, remainder} @subsubheading Arguments and Values:: @i{number}---a @i{real}. @i{divisor}---a non-zero @i{real}. The default is the @i{integer} @t{1}. @i{quotient}---for @b{floor}, @b{ceiling}, @b{truncate}, and @b{round}: an @i{integer}; for @b{ffloor}, @b{fceiling}, @b{ftruncate}, and @b{fround}: a @i{float}. @i{remainder}---a @i{real}. @subsubheading Description:: These functions divide @i{number} by @i{divisor}, returning a @i{quotient} and @i{remainder}, such that @i{quotient}{\cdot} @i{divisor}+@i{remainder}=@i{number} The @i{quotient} always represents a mathematical integer. When more than one mathematical integer might be possible (@i{i.e.}, when the remainder is not zero), the kind of rounding or truncation depends on the @i{operator}: @table @asis @item @b{floor}, @b{ffloor} @b{floor} and @b{ffloor} produce a @i{quotient} that has been truncated toward negative infinity; that is, the @i{quotient} represents the largest mathematical integer that is not larger than the mathematical quotient. @item @b{ceiling}, @b{fceiling} @b{ceiling} and @b{fceiling} produce a @i{quotient} that has been truncated toward positive infinity; that is, the @i{quotient} represents the smallest mathematical integer that is not smaller than the mathematical result. @item @b{truncate}, @b{ftruncate} @b{truncate} and @b{ftruncate} produce a @i{quotient} that has been truncated towards zero; that is, the @i{quotient} represents the mathematical integer of the same sign as the mathematical quotient, and that has the greatest integral magnitude not greater than that of the mathematical quotient. @item @b{round}, @b{fround} @b{round} and @b{fround} produce a @i{quotient} that has been rounded to the nearest mathematical integer; if the mathematical quotient is exactly halfway between two integers, (that is, it has the form @i{integer}+1\over2), then the @i{quotient} has been rounded to the even (divisible by two) integer. @end table All of these functions perform type conversion operations on @i{numbers}. The @i{remainder} is an @i{integer} if both @t{x} and @t{y} are @i{integers}, is a @i{rational} if both @t{x} and @t{y} are @i{rationals}, and is a @i{float} if either @t{x} or @t{y} is a @i{float}. @b{ffloor}, @b{fceiling}, @b{ftruncate}, and @b{fround} handle arguments of different @i{types} in the following way: If @i{number} is a @i{float}, and @i{divisor} is not a @i{float} of longer format, then the first result is a @i{float} of the same @i{type} as @i{number}. Otherwise, the first result is of the @i{type} determined by @i{contagion} rules; see @ref{Contagion in Numeric Operations}. @subsubheading Examples:: @example (floor 3/2) @result{} 1, 1/2 (ceiling 3 2) @result{} 2, -1 (ffloor 3 2) @result{} 1.0, 1 (ffloor -4.7) @result{} -5.0, 0.3 (ffloor 3.5d0) @result{} 3.0d0, 0.5d0 (fceiling 3/2) @result{} 2.0, -1/2 (truncate 1) @result{} 1, 0 (truncate .5) @result{} 0, 0.5 (round .5) @result{} 0, 0.5 (ftruncate -7 2) @result{} -3.0, -1 (fround -7 2) @result{} -4.0, 1 (dolist (n '(2.6 2.5 2.4 0.7 0.3 -0.3 -0.7 -2.4 -2.5 -2.6)) (format t "~&~4,1@@F ~2,' D ~2,' D ~2,' D ~2,' D" n (floor n) (ceiling n) (truncate n) (round n))) @t{ |> } +2.6 2 3 2 3 @t{ |> } +2.5 2 3 2 2 @t{ |> } +2.4 2 3 2 2 @t{ |> } +0.7 0 1 0 1 @t{ |> } +0.3 0 1 0 0 @t{ |> } -0.3 -1 0 0 0 @t{ |> } -0.7 -1 0 0 -1 @t{ |> } -2.4 -3 -2 -2 -2 @t{ |> } -2.5 -3 -2 -2 -2 @t{ |> } -2.6 -3 -2 -2 -3 @result{} NIL @end example @subsubheading Notes:: When only @i{number} is given, the two results are exact; the mathematical sum of the two results is always equal to the mathematical value of @i{number}. @t{(@i{function} @i{number} @i{divisor})} and @t{(@i{function} (/ @i{number} @i{divisor}))} (where @i{function} is any of one of @b{floor}, @b{ceiling}, @b{ffloor}, @b{fceiling}, @b{truncate}, @b{round}, @b{ftruncate}, and @b{fround}) return the same first value, but they return different remainders as the second value. For example: @example (floor 5 2) @result{} 2, 1 (floor (/ 5 2)) @result{} 2, 1/2 @end example If an effect is desired that is similar to @b{round}, but that always rounds up or down (rather than toward the nearest even integer) if the mathematical quotient is exactly halfway between two integers, the programmer should consider a construction such as @t{(floor (+ x 1/2))} or @t{(ceiling (- x 1/2))}. @node sin, asin, floor, Numbers Dictionary @subsection sin, cos, tan [Function] @code{sin} @i{radians} @result{} @i{number} @code{cos} @i{radians} @result{} @i{number} @code{tan} @i{radians} @result{} @i{number} @subsubheading Arguments and Values:: @i{radians}---a @i{number} given in radians. @i{number}---a @i{number}. @subsubheading Description:: @b{sin}, @b{cos}, and @b{tan} return the sine, cosine, and tangent, respectively, of @i{radians}. @subsubheading Examples:: @example (sin 0) @result{} 0.0 (cos 0.7853982) @result{} 0.707107 (tan #c(0 1)) @result{} #C(0.0 0.761594) @end example @subsubheading Exceptional Situations:: Should signal an error of @i{type} @b{type-error} if @i{radians} is not a @i{number}. Might signal @b{arithmetic-error}. @subsubheading See Also:: @ref{asin; acos; atan} , @b{acos}, @b{atan}, @ref{Rule of Float Substitutability} @node asin, pi, sin, Numbers Dictionary @subsection asin, acos, atan [Function] @code{asin} @i{number} @result{} @i{radians} @code{acos} @i{number} @result{} @i{radians} @code{atan} @i{number1 {&optional} number2} @result{} @i{radians} @subsubheading Arguments and Values:: @i{number}---a @i{number}. @i{number1}---a @i{number} if @i{number2} is not supplied, or a @i{real} if @i{number2} is supplied. @i{number2}---a @i{real}. @i{radians}---a @i{number} (of radians). @subsubheading Description:: @b{asin}, @b{acos}, and @b{atan} compute the arc sine, arc cosine, and arc tangent respectively. The arc sine, arc cosine, and arc tangent (with only @i{number1} supplied) functions can be defined mathematically for @i{number} or @i{number1} specified as @i{x} as in Figure 12--13. @group @noindent @w{ Function Definition } @w{ Arc sine -i @t{log} (ix+ \sqrt{1-x^2} ) } @w{ Arc cosine (\pi/2) - @t{arcsin} x } @w{ Arc tangent -i @t{log} ((1+ix) \sqrt{1/(1+x^2)} ) } @noindent @w{ Figure 12--13: Mathematical definition of arc sine, arc cosine, and arc tangent} @end group These formulae are mathematically correct, assuming completely accurate computation. They are not necessarily the simplest ones for real-valued computations. If both @i{number1} and @i{number2} are supplied for @b{atan}, the result is the arc tangent of @i{number1}/@i{number2}. The value of @b{atan} is always between -\pi (exclusive) and~\pi (inclusive) when minus zero is not supported. The range of the two-argument arc tangent when minus zero is supported includes -\pi. For a @i{real} @i{number1}, the result is a @i{real} and lies between -\pi/2 and~\pi/2 (both exclusive). @i{number1} can be a @i{complex} if @i{number2} is not supplied. If both are supplied, @i{number2} can be zero provided @i{number1} is not zero. [Reviewer Note by Barmar: Should add ``However, if the implementation distinguishes positive and negative zero, both may be signed zeros, and limits are used to define the result.''] The following definition for arc sine determines the range and branch cuts: @center @t{arcsin} z = -i @t{log} (iz+\sqrt{1-z^2}\Bigr) The branch cut for the arc sine function is in two pieces: one along the negative real axis to the left of~-1 (inclusive), continuous with quadrant II, and one along the positive real axis to the right of~1 (inclusive), continuous with quadrant IV. The range is that strip of the complex plane containing numbers whose real part is between -\pi/2 and~\pi/2. A number with real part equal to -\pi/2 is in the range if and only if its imaginary part is non-negative; a number with real part equal to \pi/2 is in the range if and only if its imaginary part is non-positive. The following definition for arc cosine determines the range and branch cuts: @center @t{arccos} z = {\pi\over2}- @t{arcsin} z or, which are equivalent, @center @t{arccos} z = -i @t{log} (z+i \sqrt{1-z^2}\Bigr) @center @t{arccos} z = {{2 @t{log} (\sqrt{(1+z)/2} + i \sqrt{(1-z)/2})}\over{i}} The branch cut for the arc cosine function is in two pieces: one along the negative real axis to the left of~-1 (inclusive), continuous with quadrant II, and one along the positive real axis to the right of~1 (inclusive), continuous with quadrant IV. This is the same branch cut as for arc sine. The range is that strip of the complex plane containing numbers whose real part is between 0 and~\pi. A number with real part equal to 0 is in the range if and only if its imaginary part is non-negative; a number with real part equal to \pi is in the range if and only if its imaginary part is non-positive. The following definition for (one-argument) arc tangent determines the range and branch cuts: @center @t{arctan} z = {{@t{log} (1+iz) - @t{log} (1-iz)}\over{2i}} Beware of simplifying this formula; ``obvious'' simplifications are likely to alter the branch cuts or the values on the branch cuts incorrectly. The branch cut for the arc tangent function is in two pieces: one along the positive imaginary axis above i (exclusive), continuous with quadrant II, and one along the negative imaginary axis below -i (exclusive), continuous with quadrant IV. The points i and~-i are excluded from the domain. The range is that strip of the complex plane containing numbers whose real part is between -\pi/2 and~\pi/2. A number with real part equal to -\pi/2 is in the range if and only if its imaginary part is strictly positive; a number with real part equal to \pi/2 is in the range if and only if its imaginary part is strictly negative. Thus the range of arc tangent is identical to that of arc sine with the points -\pi/2 and~\pi/2 excluded. For @b{atan}, the signs of @i{number1} (indicated as @i{x}) and @i{number2} (indicated as @i{y}) are used to derive quadrant information. Figure 12--14 details various special cases. The asterisk (*) indicates that the entry in the figure applies to implementations that support minus zero. @group @noindent @w{ to 1pc{}@i{y} Condition @i{x} Condition Cartesian locus Range of result } @w{ to 1pc{} y = 0 x > 0 Positive x-axis 0 } @w{ to 1pc{*} y = +0 x > 0 Positive x-axis +0 } @w{ to 1pc{*} y = -0 x > 0 Positive x-axis -0 } @w{ to 1pc{} y > 0 x > 0 Quadrant I 0 < result < \pi/2 } @w{ to 1pc{} y > 0 x = 0 Positive y-axis \pi/2 } @w{ to 1pc{} y > 0 x < 0 Quadrant II \pi/2 < result < \pi } @w{ to 1pc{} y = 0 x < 0 Negative x-axis \pi } @w{ to 1pc{*} y = +0 x < 0 Negative x-axis +\pi } @w{ to 1pc{*} y = -0 x < 0 Negative x-axis -\pi } @w{ to 1pc{} y < 0 x < 0 Quadrant III -\pi < result < -\pi/2 } @w{ to 1pc{} y < 0 x = 0 Negative y-axis -\pi/2 } @w{ to 1pc{} y < 0 x > 0 Quadrant IV -\pi/2 < result < 0 } @w{ to 1pc{} y = 0 x = 0 Origin undefined consequences } @w{ to 1pc{*} y = +0 x = +0 Origin +0 } @w{ to 1pc{*} y = -0 x = +0 Origin -0 } @w{ to 1pc{*} y = +0 x = -0 Origin +\pi } @w{ to 1pc{*} y = -0 x = -0 Origin -\pi } @noindent @w{ Figure 12--14: Quadrant information for arc tangent } @end group @subsubheading Examples:: @example (asin 0) @result{} 0.0 (acos #c(0 1)) @result{} #C(1.5707963267948966 -0.8813735870195432) (/ (atan 1 (sqrt 3)) 6) @result{} 0.087266 (atan #c(0 2)) @result{} #C(-1.5707964 0.54930615) @end example @subsubheading Exceptional Situations:: @b{acos} and @b{asin} should signal an error of @i{type} @b{type-error} if @i{number} is not a @i{number}. @b{atan} should signal @b{type-error} if one argument is supplied and that argument is not a @i{number}, or if two arguments are supplied and both of those arguments are not @i{reals}. @b{acos}, @b{asin}, and @b{atan} might signal @b{arithmetic-error}. @subsubheading See Also:: @ref{log} , @ref{sqrt; isqrt} , @ref{Rule of Float Substitutability} @subsubheading Notes:: The result of either @b{asin} or @b{acos} can be a @i{complex} even if @i{number} is not a @i{complex}; this occurs when the absolute value of @i{number} is greater than one. @node pi, sinh, asin, Numbers Dictionary @subsection pi [Constant Variable] @subsubheading Value:: an @i{implementation-dependent} @i{long float}. @subsubheading Description:: The best @i{long float} approximation to the mathematical constant \pi. @subsubheading Examples:: @example ;; In each of the following computations, the precision depends ;; on the implementation. Also, if `long float' is treated by ;; the implementation as equivalent to some other float format ;; (e.g., `double float') the exponent marker might be the marker ;; for that equivalent (e.g., `D' instead of `L'). pi @result{} 3.141592653589793L0 (cos pi) @result{} -1.0L0 (defun sin-of-degrees (degrees) (let ((x (if (floatp degrees) degrees (float degrees pi)))) (sin (* x (/ (float pi x) 180))))) @end example @subsubheading Notes:: An approximation to \pi in some other precision can be obtained by writing @t{(float pi x)}, where @t{x} is a @i{float} of the desired precision, or by writing @t{(coerce pi @i{type})}, where @i{type} is the desired type, such as @b{short-float}. @node sinh, *, pi, Numbers Dictionary @subsection sinh, cosh, tanh, asinh, acosh, atanh [Function] @code{sinh} @i{number} @result{} @i{result} @code{cosh} @i{number} @result{} @i{result} @code{tanh} @i{number} @result{} @i{result} @code{asinh} @i{number} @result{} @i{result} @code{acosh} @i{number} @result{} @i{result} @code{atanh} @i{number} @result{} @i{result} @subsubheading Arguments and Values:: @i{number}---a @i{number}. @i{result}---a @i{number}. @subsubheading Description:: These functions compute the hyperbolic sine, cosine, tangent, arc sine, arc cosine, and arc tangent functions, which are mathematically defined for an argument @i{x} as given in Figure 12--15. @group @noindent @w{ Function Definition } @w{ Hyperbolic sine (e^x-e^{-x})/2 } @w{ Hyperbolic cosine (e^x+e^{-x})/2 } @w{ Hyperbolic tangent (e^x-e^{-x})/(e^x+e^{-x}) } @w{ Hyperbolic arc sine @t{log} (x+\sqrt{1+x^2}) } @w{ Hyperbolic arc cosine 2 @t{log} (\sqrt{(x+1)/2} + \sqrt{(x-1)/2}) } @w{ Hyperbolic arc tangent (@t{log} (1+x) - @t{log} (1-x))/2 } @noindent @w{ Figure 12--15: Mathematical definitions for hyperbolic functions } @end group The following definition for the inverse hyperbolic cosine determines the range and branch cuts: @center @t{arccosh} z = 2 @t{log} (\sqrt{(z+1)/2} + \sqrt{(z-1)/2}\Bigr). The branch cut for the inverse hyperbolic cosine function lies along the real axis to the left of~1 (inclusive), extending indefinitely along the negative real axis, continuous with quadrant II and (between 0 and~1) with quadrant I. The range is that half-strip of the complex plane containing numbers whose real part is non-negative and whose imaginary part is between -\pi (exclusive) and~\pi (inclusive). A number with real part zero is in the range if its imaginary part is between zero (inclusive) and~\pi (inclusive). The following definition for the inverse hyperbolic sine determines the range and branch cuts: @center @t{arcsinh} z = @t{log} (z+\sqrt{1+z^2}\Bigr). The branch cut for the inverse hyperbolic sine function is in two pieces: one along the positive imaginary axis above i (inclusive), continuous with quadrant I, and one along the negative imaginary axis below -i (inclusive), continuous with quadrant III. The range is that strip of the complex plane containing numbers whose imaginary part is between -\pi/2 and~\pi/2. A number with imaginary part equal to -\pi/2 is in the range if and only if its real part is non-positive; a number with imaginary part equal to \pi/2 is in the range if and only if its imaginary part is non-negative. The following definition for the inverse hyperbolic tangent determines the range and branch cuts: @center @t{arctanh} z = {{@t{log} (1+z) - @t{log} (1-z)}\over{2}}. Note that: @center i @t{arctan} z = @t{arctanh} iz. The branch cut for the inverse hyperbolic tangent function is in two pieces: one along the negative real axis to the left of -1 (inclusive), continuous with quadrant III, and one along the positive real axis to the right of~1 (inclusive), continuous with quadrant I. The points -1 and~1 are excluded from the domain. The range is that strip of the complex plane containing numbers whose imaginary part is between -\pi/2 and \pi/2. A number with imaginary part equal to -\pi/2 is in the range if and only if its real part is strictly negative; a number with imaginary part equal to \pi/2 is in the range if and only if its imaginary part is strictly positive. Thus the range of the inverse hyperbolic tangent function is identical to that of the inverse hyperbolic sine function with the points -\pi i/2 and~\pi i/2 excluded. @subsubheading Examples:: @example (sinh 0) @result{} 0.0 (cosh (complex 0 -1)) @result{} #C(0.540302 -0.0) @end example @subsubheading Exceptional Situations:: Should signal an error of @i{type} @b{type-error} if @i{number} is not a @i{number}. Might signal @b{arithmetic-error}. @subsubheading See Also:: @ref{log} , @ref{sqrt; isqrt} , @ref{Rule of Float Substitutability} @subsubheading Notes:: The result of @b{acosh} may be a @i{complex} even if @i{number} is not a @i{complex}; this occurs when @i{number} is less than one. Also, the result of @b{atanh} may be a @i{complex} even if @i{number} is not a @i{complex}; this occurs when the absolute value of @i{number} is greater than one. The branch cut formulae are mathematically correct, assuming completely accurate computation. Implementors should consult a good text on numerical analysis. The formulae given above are not necessarily the simplest ones for real-valued computations; they are chosen to define the branch cuts in desirable ways for the complex case. @node *, +, sinh, Numbers Dictionary @subsection * [Function] @code{*} @i{{&rest} numbers} @result{} @i{product} @subsubheading Arguments and Values:: @i{number}---a @i{number}. @i{product}---a @i{number}. @subsubheading Description:: Returns the product of @i{numbers}, performing any necessary type conversions in the process. If no @i{numbers} are supplied, @t{1} is returned. @subsubheading Examples:: @example (*) @result{} 1 (* 3 5) @result{} 15 (* 1.0 #c(22 33) 55/98) @result{} #C(12.346938775510203 18.520408163265305) @end example @subsubheading Exceptional Situations:: Might signal @b{type-error} if some @i{argument} is not a @i{number}. Might signal @b{arithmetic-error}. @subsubheading See Also:: @ref{Numeric Operations}, @ref{Rational Computations}, @ref{Floating-point Computations}, @ref{Complex Computations} @node +, -, *, Numbers Dictionary @subsection + [Function] @code{+} @i{{&rest} numbers} @result{} @i{sum} @subsubheading Arguments and Values:: @i{number}---a @i{number}. @i{sum}---a @i{number}. @subsubheading Description:: Returns the sum of @i{numbers}, performing any necessary type conversions in the process. If no @i{numbers} are supplied, @t{0} is returned. @subsubheading Examples:: @example (+) @result{} 0 (+ 1) @result{} 1 (+ 31/100 69/100) @result{} 1 (+ 1/5 0.8) @result{} 1.0 @end example @subsubheading Exceptional Situations:: Might signal @b{type-error} if some @i{argument} is not a @i{number}. Might signal @b{arithmetic-error}. @subsubheading See Also:: @ref{Numeric Operations}, @ref{Rational Computations}, @ref{Floating-point Computations}, @ref{Complex Computations} @node -, /, +, Numbers Dictionary @subsection - [Function] @code{-} @i{number} @result{} @i{negation} @code{-} @i{minuend {&rest} subtrahends^+} @result{} @i{difference} @subsubheading Arguments and Values:: @i{number}, @i{minuend}, @i{subtrahend}---a @i{number}. @i{negation}, @i{difference}---a @i{number}. @subsubheading Description:: The @i{function} @b{-} performs arithmetic subtraction and negation. If only one @i{number} is supplied, the negation of that @i{number} is returned. If more than one @i{argument} is given, it subtracts all of the @i{subtrahends} from the @i{minuend} and returns the result. The @i{function} @b{-} performs necessary type conversions. @subsubheading Examples:: @example (- 55.55) @result{} -55.55 (- #c(3 -5)) @result{} #C(-3 5) (- 0) @result{} 0 (eql (- 0.0) -0.0) @result{} @i{true} (- #c(100 45) #c(0 45)) @result{} 100 (- 10 1 2 3 4) @result{} 0 @end example @subsubheading Exceptional Situations:: Might signal @b{type-error} if some @i{argument} is not a @i{number}. Might signal @b{arithmetic-error}. @subsubheading See Also:: @ref{Numeric Operations}, @ref{Rational Computations}, @ref{Floating-point Computations}, @ref{Complex Computations} @node /, 1+, -, Numbers Dictionary @subsection / [Function] @code{/} @i{number} @result{} @i{reciprocal} @code{/} @i{numerator {&rest} denominators^+} @result{} @i{quotient} @subsubheading Arguments and Values:: @i{number}, @i{denominator}---a non-zero @i{number}. @i{numerator}, @i{quotient}, @i{reciprocal}---a @i{number}. @subsubheading Description:: The @i{function} @b{/} performs division or reciprocation. If no @i{denominators} are supplied, the @i{function} @b{/} returns the reciprocal of @i{number}. If at least one @i{denominator} is supplied, the @i{function} @b{/} divides the @i{numerator} by all of the @i{denominators} and returns the resulting @i{quotient}. If each @i{argument} is either an @i{integer} or a @i{ratio}, and the result is not an @i{integer}, then it is a @i{ratio}. The @i{function} @b{/} performs necessary type conversions. If any @i{argument} is a @i{float} then the rules of floating-point contagion apply; see @ref{Floating-point Computations}. @subsubheading Examples:: @example (/ 12 4) @result{} 3 (/ 13 4) @result{} 13/4 (/ -8) @result{} -1/8 (/ 3 4 5) @result{} 3/20 (/ 0.5) @result{} 2.0 (/ 20 5) @result{} 4 (/ 5 20) @result{} 1/4 (/ 60 -2 3 5.0) @result{} -2.0 (/ 2 #c(2 2)) @result{} #C(1/2 -1/2) @end example @subsubheading Exceptional Situations:: The consequences are unspecified if any @i{argument} other than the first is zero. If there is only one @i{argument}, the consequences are unspecified if it is zero. Might signal @b{type-error} if some @i{argument} is not a @i{number}. Might signal @b{division-by-zero} if division by zero is attempted. Might signal @b{arithmetic-error}. @subsubheading See Also:: @ref{floor; ffloor; ceiling; fceiling; truncate; ftruncate; round; fround} , @b{ceiling}, @b{truncate}, @b{round} @node 1+, abs, /, Numbers Dictionary @subsection 1+, 1- [Function] @code{1} @i{+} @result{} @i{number} {successor} @code{1} @i{-} @result{} @i{number} {predecessor} @subsubheading Arguments and Values:: @i{number}---a @i{number}. @i{successor}, @i{predecessor}---a @i{number}. @subsubheading Description:: @b{1+} returns a @i{number} that is one more than its argument @i{number}. @b{1-} returns a @i{number} that is one less than its argument @i{number}. @subsubheading Examples:: @example (1+ 99) @result{} 100 (1- 100) @result{} 99 (1+ (complex 0.0)) @result{} #C(1.0 0.0) (1- 5/3) @result{} 2/3 @end example @subsubheading Exceptional Situations:: Might signal @b{type-error} if its @i{argument} is not a @i{number}. Might signal @b{arithmetic-error}. @subsubheading See Also:: @ref{incf; decf} , @b{decf} @subsubheading Notes:: @example (1+ @i{number}) @equiv{} (+ @i{number} 1) (1- @i{number}) @equiv{} (- @i{number} 1) @end example Implementors are encouraged to make the performance of both the previous expressions be the same. @node abs, evenp, 1+, Numbers Dictionary @subsection abs [Function] @code{abs} @i{number} @result{} @i{absolute-value} @subsubheading Arguments and Values:: @i{number}---a @i{number}. @i{absolute-value}---a non-negative @i{real}. @subsubheading Description:: @b{abs} returns the absolute value of @i{number}. If @i{number} is a @i{real}, the result is of the same @i{type} as @i{number}. If @i{number} is a @i{complex}, the result is a positive @i{real} with the same magnitude as @i{number}. The result can be a @i{float} [Reviewer Note by Barmar: Single-float.] even if @i{number}'s components are @i{rationals} and an exact rational result would have been possible. Thus the result of @t{(abs #c(3 4))} can be either @t{5} or @t{5.0}, depending on the implementation. @subsubheading Examples:: @example (abs 0) @result{} 0 (abs 12/13) @result{} 12/13 (abs -1.09) @result{} 1.09 (abs #c(5.0 -5.0)) @result{} 7.071068 (abs #c(5 5)) @result{} 7.071068 (abs #c(3/5 4/5)) @result{} 1 or approximately 1.0 (eql (abs -0.0) -0.0) @result{} @i{true} @end example @subsubheading See Also:: @ref{Rule of Float Substitutability} @subsubheading Notes:: If @i{number} is a @i{complex}, the result is equivalent to the following: @t{(sqrt (+ (expt (realpart @i{number}) 2) (expt (imagpart @i{number}) 2)))} An implementation should not use this formula directly for all @i{complexes} but should handle very large or very small components specially to avoid intermediate overflow or underflow. @node evenp, exp, abs, Numbers Dictionary @subsection evenp, oddp [Function] @code{evenp} @i{integer} @result{} @i{generalized-boolean} @code{oddp} @i{integer} @result{} @i{generalized-boolean} @subsubheading Arguments and Values:: @i{integer}---an @i{integer}. @i{generalized-boolean}---a @i{generalized boolean}. @subsubheading Description:: @b{evenp} returns @i{true} if @i{integer} is even (divisible by two); otherwise, returns @i{false}. @b{oddp} returns @i{true} if @i{integer} is odd (not divisible by two); otherwise, returns @i{false}. @subsubheading Examples:: @example (evenp 0) @result{} @i{true} (oddp 10000000000000000000000) @result{} @i{false} (oddp -1) @result{} @i{true} @end example @subsubheading Exceptional Situations:: Should signal an error of @i{type} @b{type-error} if @i{integer} is not an @i{integer}. @subsubheading Notes:: @example (evenp @i{integer}) @equiv{} (not (oddp @i{integer})) (oddp @i{integer}) @equiv{} (not (evenp @i{integer})) @end example @node exp, gcd, evenp, Numbers Dictionary @subsection exp, expt [Function] @code{exp} @i{number} @result{} @i{result} @code{expt} @i{base-number power-number} @result{} @i{result} @subsubheading Arguments and Values:: @i{number}---a @i{number}. @i{base-number}---a @i{number}. @i{power-number}---a @i{number}. @i{result}---a @i{number}. @subsubheading Description:: @b{exp} and @b{expt} perform exponentiation. @b{exp} returns @i{e} raised to the power @i{number}, where @i{e} is the base of the natural logarithms. @b{exp} has no branch cut. @b{expt} returns @i{base-number} raised to the power @i{power-number}. If the @i{base-number} is a @i{rational} and @i{power-number} is an @i{integer}, the calculation is exact and the result will be of @i{type} @b{rational}; otherwise a floating-point approximation might result. For @b{expt} of a @i{complex rational} to an @i{integer} power, the calculation must be exact and the result is of type @t{(or rational (complex rational))}. The result of @b{expt} can be a @i{complex}, even when neither argument is a @i{complex}, if @i{base-number} is negative and @i{power-number} is not an @i{integer}. The result is always the @i{principal} @i{complex} @i{value}. For example, @t{(expt -8 1/3)} is not permitted to return @t{-2}, even though @t{-2} is one of the cube roots of @t{-8}. The @i{principal} cube root is a @i{complex} approximately equal to @t{#C(1.0 1.73205)}, not @t{-2}. @b{expt} is defined as @i{b^x = e^{x log b\/}}. This defines the @i{principal} @i{values} precisely. The range of @b{expt} is the entire complex plane. Regarded as a function of @i{x}, with @i{b} fixed, there is no branch cut. Regarded as a function of @i{b}, with @i{x} fixed, there is in general a branch cut along the negative real axis, continuous with quadrant II. The domain excludes the origin. By definition, 0^0=1. If @i{b}=0 and the real part of @i{x} is strictly positive, then @i{b^x}=0. For all other values of @i{x}, 0^@i{x} is an error. When @i{power-number} is an @i{integer} @t{0}, then the result is always the value one in the @i{type} of @i{base-number}, even if the @i{base-number} is zero (of any @i{type}). That is: @example (expt x 0) @equiv{} (coerce 1 (type-of x)) @end example If @i{power-number} is a zero of any other @i{type}, then the result is also the value one, in the @i{type} of the arguments after the application of the contagion rules in @ref{Contagion in Numeric Operations}, with one exception: the consequences are undefined if @i{base-number} is zero when @i{power-number} is zero and not of @i{type} @b{integer}. @subsubheading Examples:: @example (exp 0) @result{} 1.0 (exp 1) @result{} 2.718282 (exp (log 5)) @result{} 5.0 (expt 2 8) @result{} 256 (expt 4 .5) @result{} 2.0 (expt #c(0 1) 2) @result{} -1 (expt #c(2 2) 3) @result{} #C(-16 16) (expt #c(2 2) 4) @result{} -64 @end example @subsubheading See Also:: @ref{log} , @ref{Rule of Float Substitutability} @subsubheading Notes:: Implementations of @b{expt} are permitted to use different algorithms for the cases of a @i{power-number} of @i{type} @b{rational} and a @i{power-number} of @i{type} @b{float}. Note that by the following logic, @t{(sqrt (expt @i{x} 3))} is not equivalent to @t{(expt @i{x} 3/2)}. @example (setq x (exp (/ (* 2 pi #c(0 1)) 3))) ;exp(2.pi.i/3) (expt x 3) @result{} 1 ;except for round-off error (sqrt (expt x 3)) @result{} 1 ;except for round-off error (expt x 3/2) @result{} -1 ;except for round-off error @end example @node gcd, incf, exp, Numbers Dictionary @subsection gcd [Function] @code{gcd} @i{{&rest} integers} @result{} @i{greatest-common-denominator} @subsubheading Arguments and Values:: @i{integer}---an @i{integer}. @i{greatest-common-denominator}---a non-negative @i{integer}. @subsubheading Description:: Returns the greatest common divisor of @i{integers}. If only one @i{integer} is supplied, its absolute value is returned. If no @i{integers} are given, @b{gcd} returns @t{0}, which is an identity for this operation. @subsubheading Examples:: @example (gcd) @result{} 0 (gcd 60 42) @result{} 6 (gcd 3333 -33 101) @result{} 1 (gcd 3333 -33 1002001) @result{} 11 (gcd 91 -49) @result{} 7 (gcd 63 -42 35) @result{} 7 (gcd 5) @result{} 5 (gcd -4) @result{} 4 @end example @subsubheading Exceptional Situations:: Should signal an error of @i{type} @b{type-error} if any @i{integer} is not an @i{integer}. @subsubheading See Also:: @ref{lcm} @subsubheading Notes:: For three or more arguments, @example (gcd b c ... z) @equiv{} (gcd (gcd a b) c ... z) @end example @node incf, lcm, gcd, Numbers Dictionary @subsection incf, decf [Macro] @code{incf} @i{place @r{[}delta-form@r{]}} @result{} @i{new-value} @code{decf} @i{place @r{[}delta-form@r{]}} @result{} @i{new-value} @subsubheading Arguments and Values:: @i{place}---a @i{place}. @i{delta-form}---a @i{form}; evaluated to produce a @i{delta}. The default is @t{1}. @i{delta}---a @i{number}. @i{new-value}---a @i{number}. @subsubheading Description:: @b{incf} and @b{decf} are used for incrementing and decrementing the @i{value} of @i{place}, respectively. The @i{delta} is added to (in the case of @b{incf}) or subtracted from (in the case of @b{decf}) the number in @i{place} and the result is stored in @i{place}. Any necessary type conversions are performed automatically. For information about the @i{evaluation} of @i{subforms} of @i{places}, see @ref{Evaluation of Subforms to Places}. @subsubheading Examples:: @example (setq n 0) (incf n) @result{} 1 n @result{} 1 (decf n 3) @result{} -2 n @result{} -2 (decf n -5) @result{} 3 (decf n) @result{} 2 (incf n 0.5) @result{} 2.5 (decf n) @result{} 1.5 n @result{} 1.5 @end example @subsubheading Side Effects:: @i{Place} is modified. @subsubheading See Also:: @b{+}, @ref{-} , @b{1+}, @b{1-}, @ref{setf; psetf} @node lcm, log, incf, Numbers Dictionary @subsection lcm [Function] @code{lcm} @i{{&rest} integers} @result{} @i{least-common-multiple} @subsubheading Arguments and Values:: @i{integer}---an @i{integer}. @i{least-common-multiple}---a non-negative @i{integer}. @subsubheading Description:: @b{lcm} returns the least common multiple of the @i{integers}. If no @i{integer} is supplied, the @i{integer} @t{1} is returned. If only one @i{integer} is supplied, the absolute value of that @i{integer} is returned. For two arguments that are not both zero, @example (lcm a b) @equiv{} (/ (abs (* a b)) (gcd a b)) @end example If one or both arguments are zero, @example (lcm a 0) @equiv{} (lcm 0 a) @equiv{} 0 @end example For three or more arguments, @example (lcm a b c ... z) @equiv{} (lcm (lcm a b) c ... z) @end example @subsubheading Examples:: @example (lcm 10) @result{} 10 (lcm 25 30) @result{} 150 (lcm -24 18 10) @result{} 360 (lcm 14 35) @result{} 70 (lcm 0 5) @result{} 0 (lcm 1 2 3 4 5 6) @result{} 60 @end example @subsubheading Exceptional Situations:: Should signal @b{type-error} if any argument is not an @i{integer}. @subsubheading See Also:: @ref{gcd} @node log, mod, lcm, Numbers Dictionary @subsection log [Function] @code{log} @i{number {&optional} base} @result{} @i{logarithm} @subsubheading Arguments and Values:: @i{number}---a non-zero @i{number}. @i{base}---a @i{number}. @i{logarithm}---a @i{number}. @subsubheading Description:: @b{log} returns the logarithm of @i{number} in base @i{base}. If @i{base} is not supplied its value is @i{e}, the base of the natural logarithms. @b{log} may return a @i{complex} when given a @i{real} negative @i{number}. @example (log -1.0) @equiv{} (complex 0.0 (float pi 0.0)) @end example If @i{base} is zero, @b{log} returns zero. The result of @t{(log 8 2)} may be either @t{3} or @t{3.0}, depending on the implementation. An implementation can use floating-point calculations even if an exact integer result is possible. The branch cut for the logarithm function of one argument (natural logarithm) lies along the negative real axis, continuous with quadrant II. The domain excludes the origin. The mathematical definition of a complex logarithm is as follows, whether or not minus zero is supported by the implementation: @example (log @i{x}) @equiv{} (complex (log (abs @i{x})) (phase @i{x})) @end example Therefore the range of the one-argument logarithm function is that strip of the complex plane containing numbers with imaginary parts between -\pi (exclusive) and~\pi (inclusive) if minus zero is not supported, or -\pi (inclusive) and~\pi (inclusive) if minus zero is supported. The two-argument logarithm function is defined as @example (log @i{base} @i{number}) @equiv{} (/ (log @i{number}) (log @i{base})) @end example This defines the @i{principal} @i{values} precisely. The range of the two-argument logarithm function is the entire complex plane. @subsubheading Examples:: @example (log 100 10) @result{} 2.0 @result{} 2 (log 100.0 10) @result{} 2.0 (log #c(0 1) #c(0 -1)) @result{} #C(-1.0 0.0) @i{OR}@result{} #C(-1 0) (log 8.0 2) @result{} 3.0 @end example @example (log #c(-16 16) #c(2 2)) @result{} 3 or approximately #c(3.0 0.0) or approximately 3.0 (unlikely) @end example @subsubheading Affected By:: The implementation. @subsubheading See Also:: @ref{exp; expt} , @b{expt}, @ref{Rule of Float Substitutability} @node mod, signum, log, Numbers Dictionary @subsection mod, rem [Function] @code{mod} @i{number divisor} @result{} @i{modulus} @code{rem} @i{number divisor} @result{} @i{remainder} @subsubheading Arguments and Values:: @i{number}---a @i{real}. @i{divisor}---a @i{real}. @i{modulus}, @i{remainder}---a @i{real}. @subsubheading Description:: @b{mod} and @b{rem} are generalizations of the modulus and remainder functions respectively. @b{mod} performs the operation @b{floor} on @i{number} and @i{divisor} and returns the remainder of the @b{floor} operation. @b{rem} performs the operation @b{truncate} on @i{number} and @i{divisor} and returns the remainder of the @b{truncate} operation. @b{mod} and @b{rem} are the modulus and remainder functions when @i{number} and @i{divisor} are @i{integers}. @subsubheading Examples:: @example (rem -1 5) @result{} -1 (mod -1 5) @result{} 4 (mod 13 4) @result{} 1 (rem 13 4) @result{} 1 (mod -13 4) @result{} 3 (rem -13 4) @result{} -1 (mod 13 -4) @result{} -3 (rem 13 -4) @result{} 1 (mod -13 -4) @result{} -1 (rem -13 -4) @result{} -1 (mod 13.4 1) @result{} 0.4 (rem 13.4 1) @result{} 0.4 (mod -13.4 1) @result{} 0.6 (rem -13.4 1) @result{} -0.4 @end example @subsubheading See Also:: @ref{floor; ffloor; ceiling; fceiling; truncate; ftruncate; round; fround} , @b{truncate} @subsubheading Notes:: The result of @b{mod} is either zero or a @i{real} with the same sign as @i{divisor}. @node signum, sqrt, mod, Numbers Dictionary @subsection signum [Function] @code{signum} @i{number} @result{} @i{signed-prototype} @subsubheading Arguments and Values:: @i{number}---a @i{number}. @i{signed-prototype}---a @i{number}. @subsubheading Description:: @b{signum} determines a numerical value that indicates whether @i{number} is negative, zero, or positive. For a @i{rational}, @b{signum} returns one of @t{-1}, @t{0}, or @t{1} according to whether @i{number} is negative, zero, or positive. For a @i{float}, the result is a @i{float} of the same format whose value is minus one, zero, or one. For a @i{complex} number @t{z}, @t{(signum @i{z})} is a complex number of the same phase but with unit magnitude, unless @t{z} is a complex zero, in which case the result is @t{z}. For @i{rational} @i{arguments}, @b{signum} is a rational function, but it may be irrational for @i{complex} @i{arguments}. If @i{number} is a @i{float}, the result is a @i{float}. If @i{number} is a @i{rational}, the result is a @i{rational}. If @i{number} is a @i{complex float}, the result is a @i{complex float}. If @i{number} is a @i{complex rational}, the result is a @i{complex}, but it is @i{implementation-dependent} whether that result is a @i{complex rational} or a @i{complex float}. @subsubheading Examples:: @example (signum 0) @result{} 0 (signum 99) @result{} 1 (signum 4/5) @result{} 1 (signum -99/100) @result{} -1 (signum 0.0) @result{} 0.0 (signum #c(0 33)) @result{} #C(0.0 1.0) (signum #c(7.5 10.0)) @result{} #C(0.6 0.8) (signum #c(0.0 -14.7)) @result{} #C(0.0 -1.0) (eql (signum -0.0) -0.0) @result{} @i{true} @end example @subsubheading See Also:: @ref{Rule of Float Substitutability} @subsubheading Notes:: @example (signum x) @equiv{} (if (zerop x) x (/ x (abs x))) @end example @node sqrt, random-state, signum, Numbers Dictionary @subsection sqrt, isqrt [Function] @code{sqrt} @i{number} @result{} @i{root} @code{isqrt} @i{natural} @result{} @i{natural-root} @subsubheading Arguments and Values:: @i{number}, @i{root}---a @i{number}. @i{natural}, @i{natural-root}---a non-negative @i{integer}. @subsubheading Description:: @b{sqrt} and @b{isqrt} compute square roots. @b{sqrt} returns the @i{principal} square root of @i{number}. If the @i{number} is not a @i{complex} but is negative, then the result is a @i{complex}. @b{isqrt} returns the greatest @i{integer} less than or equal to the exact positive square root of @i{natural}. If @i{number} is a positive @i{rational}, it is @i{implementation-dependent} whether @i{root} is a @i{rational} or a @i{float}. If @i{number} is a negative @i{rational}, it is @i{implementation-dependent} whether @i{root} is a @i{complex rational} or a @i{complex float}. The mathematical definition of complex square root (whether or not minus zero is supported) follows: @t{(sqrt @i{x}) = (exp (/ (log @i{x}) 2))} The branch cut for square root lies along the negative real axis, continuous with quadrant II. The range consists of the right half-plane, including the non-negative imaginary axis and excluding the negative imaginary axis. @subsubheading Examples:: @example (sqrt 9.0) @result{} 3.0 (sqrt -9.0) @result{} #C(0.0 3.0) (isqrt 9) @result{} 3 (sqrt 12) @result{} 3.4641016 (isqrt 12) @result{} 3 (isqrt 300) @result{} 17 (isqrt 325) @result{} 18 (sqrt 25) @result{} 5 @i{OR}@result{} 5.0 (isqrt 25) @result{} 5 (sqrt -1) @result{} #C(0.0 1.0) (sqrt #c(0 2)) @result{} #C(1.0 1.0) @end example @subsubheading Exceptional Situations:: The @i{function} @b{sqrt} should signal @b{type-error} if its argument is not a @i{number}. The @i{function} @b{isqrt} should signal @b{type-error} if its argument is not a non-negative @i{integer}. The functions @b{sqrt} and @b{isqrt} might signal @b{arithmetic-error}. @subsubheading See Also:: @ref{exp; expt} , @ref{log} , @ref{Rule of Float Substitutability} @subsubheading Notes:: @example (isqrt x) @equiv{} (values (floor (sqrt x))) @end example but it is potentially more efficient. @node random-state, make-random-state, sqrt, Numbers Dictionary @subsection random-state [System Class] @subsubheading Class Precedence List:: @b{random-state}, @b{t} @subsubheading Description:: A @i{random state} @i{object} contains state information used by the pseudo-random number generator. The nature of a @i{random state} @i{object} is @i{implementation-dependent}. It can be printed out and successfully read back in by the same @i{implementation}, but might not function correctly as a @i{random state} in another @i{implementation}. @i{Implementations} are required to provide a read syntax for @i{objects} of @i{type} @b{random-state}, but the specific nature of that syntax is @i{implementation-dependent}. @subsubheading See Also:: @ref{random-state} , @ref{random} , @ref{Printing Random States} @node make-random-state, random, random-state, Numbers Dictionary @subsection make-random-state [Function] @code{make-random-state} @i{{&optional} state} @result{} @i{new-state} @subsubheading Arguments and Values:: @i{state}---a @i{random state}, or @b{nil}, or @b{t}. The default is @b{nil}. @i{new-state}---a @i{random state} @i{object}. @subsubheading Description:: Creates a @i{fresh} @i{object} of @i{type} @b{random-state} suitable for use as the @i{value} of @b{*random-state*}. If @i{state} is a @i{random state} @i{object}, the @i{new-state} is a @i{copy}_5 of that @i{object}. If @i{state} is @b{nil}, the @i{new-state} is a @i{copy}_5 of the @i{current random state}. If @i{state} is @b{t}, the @i{new-state} is a @i{fresh} @i{random state} @i{object} that has been randomly initialized by some means. @subsubheading Examples:: @example (let* ((rs1 (make-random-state nil)) (rs2 (make-random-state t)) (rs3 (make-random-state rs2)) (rs4 nil)) (list (loop for i from 1 to 10 collect (random 100) when (= i 5) do (setq rs4 (make-random-state))) (loop for i from 1 to 10 collect (random 100 rs1)) (loop for i from 1 to 10 collect (random 100 rs2)) (loop for i from 1 to 10 collect (random 100 rs3)) (loop for i from 1 to 10 collect (random 100 rs4)))) @result{} ((29 25 72 57 55 68 24 35 54 65) (29 25 72 57 55 68 24 35 54 65) (93 85 53 99 58 62 2 23 23 59) (93 85 53 99 58 62 2 23 23 59) (68 24 35 54 65 54 55 50 59 49)) @end example @subsubheading Exceptional Situations:: Should signal an error of @i{type} @b{type-error} if @i{state} is not a @i{random state}, or @b{nil}, or @b{t}. @subsubheading See Also:: @ref{random} , @ref{random-state} @subsubheading Notes:: One important use of @b{make-random-state} is to allow the same series of pseudo-random @i{numbers} to be generated many times within a single program. @node random, random-state-p, make-random-state, Numbers Dictionary @subsection random [Function] @code{random} @i{limit {&optional} random-state} @result{} @i{random-number} @subsubheading Arguments and Values:: @i{limit}---a positive @i{integer}, or a positive @i{float}. @i{random-state}---a @i{random state}. The default is the @i{current random state}. @i{random-number}---a non-negative @i{number} less than @i{limit} and of the same @i{type} as @i{limit}. @subsubheading Description:: Returns a pseudo-random number that is a non-negative @i{number} less than @i{limit} and of the same @i{type} as @i{limit}. The @i{random-state}, which is modified by this function, encodes the internal state maintained by the random number generator. An approximately uniform choice distribution is used. If @i{limit} is an @i{integer}, each of the possible results occurs with (approximate) probability 1/@i{limit}. @subsubheading Examples:: @example (<= 0 (random 1000) 1000) @result{} @i{true} (let ((state1 (make-random-state)) (state2 (make-random-state))) (= (random 1000 state1) (random 1000 state2))) @result{} @i{true} @end example @subsubheading Side Effects:: The @i{random-state} is modified. @subsubheading Exceptional Situations:: Should signal an error of @i{type} @b{type-error} if @i{limit} is not a positive @i{integer} or a positive @i{real}. @subsubheading See Also:: @ref{make-random-state} , @ref{random-state} @subsubheading Notes:: See @i{Common Lisp: The Language} for information about generating random numbers. @node random-state-p, *random-state*, random, Numbers Dictionary @subsection random-state-p [Function] @code{random-state-p} @i{object} @result{} @i{generalized-boolean} @subsubheading Arguments and Values:: @i{object}---an @i{object}. @i{generalized-boolean}---a @i{generalized boolean}. @subsubheading Description:: Returns @i{true} if @i{object} is of @i{type} @b{random-state}; otherwise, returns @i{false}. @subsubheading Examples:: @example (random-state-p *random-state*) @result{} @i{true} (random-state-p (make-random-state)) @result{} @i{true} (random-state-p 'test-function) @result{} @i{false} @end example @subsubheading See Also:: @ref{make-random-state} , @ref{random-state} @subsubheading Notes:: @example (random-state-p @i{object}) @equiv{} (typep @i{object} 'random-state) @end example @node *random-state*, numberp, random-state-p, Numbers Dictionary @subsection *random-state* [Variable] @subsubheading Value Type:: a @i{random state}. @subsubheading Initial Value:: @i{implementation-dependent}. @subsubheading Description:: The @i{current random state}, which is used, for example, by the @i{function} @b{random} when a @i{random state} is not explicitly supplied. @subsubheading Examples:: @example (random-state-p *random-state*) @result{} @i{true} (setq snap-shot (make-random-state)) ;; The series from any given point is random, ;; but if you backtrack to that point, you get the same series. (list (loop for i from 1 to 10 collect (random)) (let ((*random-state* snap-shot)) (loop for i from 1 to 10 collect (random))) (loop for i from 1 to 10 collect (random)) (let ((*random-state* snap-shot)) (loop for i from 1 to 10 collect (random)))) @result{} ((19 16 44 19 96 15 76 96 13 61) (19 16 44 19 96 15 76 96 13 61) (16 67 0 43 70 79 58 5 63 50) (16 67 0 43 70 79 58 5 63 50)) @end example @subsubheading Affected By:: The @i{implementation}. @b{random}. @subsubheading See Also:: @ref{make-random-state} , @ref{random} , @b{random-state} @subsubheading Notes:: @i{Binding} @b{*random-state*} to a different @i{random state} @i{object} correctly saves and restores the old @i{random state} @i{object}. @node numberp, cis, *random-state*, Numbers Dictionary @subsection numberp [Function] @code{numberp} @i{object} @result{} @i{generalized-boolean} @subsubheading Arguments and Values:: @i{object}---an @i{object}. @i{generalized-boolean}---a @i{generalized boolean}. @subsubheading Description:: Returns @i{true} if @i{object} is of @i{type} @b{number}; otherwise, returns @i{false}. @subsubheading Examples:: @example (numberp 12) @result{} @i{true} (numberp (expt 2 130)) @result{} @i{true} (numberp #c(5/3 7.2)) @result{} @i{true} (numberp nil) @result{} @i{false} (numberp (cons 1 2)) @result{} @i{false} @end example @subsubheading Notes:: @example (numberp @i{object}) @equiv{} (typep @i{object} 'number) @end example @node cis, complex, numberp, Numbers Dictionary @subsection cis [Function] @code{cis} @i{radians} @result{} @i{number} @subsubheading Arguments and Values:: @i{radians}---a @i{real}. @i{number}---a @i{complex}. @subsubheading Description:: @b{cis} returns the value of~@i{e}^{i\cdot @i{radians}}, which is a @i{complex} in which the real part is equal to the cosine of @i{radians}, and the imaginary part is equal to the sine of @i{radians}. @subsubheading Examples:: @example (cis 0) @result{} #C(1.0 0.0) @end example @subsubheading See Also:: @ref{Rule of Float Substitutability} @node complex, complexp, cis, Numbers Dictionary @subsection complex [Function] @code{complex} @i{realpart {&optional} imagpart} @result{} @i{complex} @subsubheading Arguments and Values:: @i{realpart}---a @i{real}. @i{imagpart}---a @i{real}. @i{complex}---a @i{rational} or a @i{complex}. @subsubheading Description:: @b{complex} returns a @i{number} whose real part is @i{realpart} and whose imaginary part is @i{imagpart}. If @i{realpart} is a @i{rational} and @i{imagpart} is the @i{rational} number zero, the result of @b{complex} is @i{realpart}, a @i{rational}. Otherwise, the result is a @i{complex}. If either @i{realpart} or @i{imagpart} is a @i{float}, the non-@i{float} is converted to a @i{float} before the @i{complex} is created. If @i{imagpart} is not supplied, the imaginary part is a zero of the same @i{type} as @i{realpart}; @i{i.e.}, @t{(coerce 0 (type-of @i{realpart}))} is effectively used. Type upgrading implies a movement upwards in the type hierarchy lattice. In the case of @i{complexes}, the @i{type-specifier} [Reviewer Note by Barmar: What type specifier?] must be a subtype of @t{(upgraded-complex-part-type @i{type-specifier})}. If @i{type-specifier1} is a subtype of @i{type-specifier2}, then @t{(upgraded-complex-element-type '@i{type-specifier1})} must also be a subtype of @t{(upgraded-complex-element-type '@i{type-specifier2})}. Two disjoint types can be upgraded into the same thing. @subsubheading Examples:: @example (complex 0) @result{} 0 (complex 0.0) @result{} #C(0.0 0.0) (complex 1 1/2) @result{} #C(1 1/2) (complex 1 .99) @result{} #C(1.0 0.99) (complex 3/2 0.0) @result{} #C(1.5 0.0) @end example @subsubheading See Also:: @ref{realpart; imagpart} , @b{imagpart} @subsubheading Notes:: @example #c(a b) @equiv{} #.(complex a b) @end example @node complexp, conjugate, complex, Numbers Dictionary @subsection complexp [Function] @code{complexp} @i{object} @result{} @i{generalized-boolean} @subsubheading Arguments and Values:: @i{object}---an @i{object}. @i{generalized-boolean}---a @i{generalized boolean}. @subsubheading Description:: Returns @i{true} if @i{object} is of @i{type} @b{complex}; otherwise, returns @i{false}. @subsubheading Examples:: @example (complexp 1.2d2) @result{} @i{false} (complexp #c(5/3 7.2)) @result{} @i{true} @end example @subsubheading See Also:: @ref{complex} (@i{function} and @i{type}), @ref{typep} @subsubheading Notes:: @example (complexp @i{object}) @equiv{} (typep @i{object} 'complex) @end example @node conjugate, phase, complexp, Numbers Dictionary @subsection conjugate [Function] @code{conjugate} @i{number} @result{} @i{conjugate} @subsubheading Arguments and Values:: @i{number}---a @i{number}. @i{conjugate}---a @i{number}. @subsubheading Description:: Returns the complex conjugate of @i{number}. The conjugate of a @i{real} number is itself. @subsubheading Examples:: @example (conjugate #c(0 -1)) @result{} #C(0 1) (conjugate #c(1 1)) @result{} #C(1 -1) (conjugate 1.5) @result{} 1.5 (conjugate #C(3/5 4/5)) @result{} #C(3/5 -4/5) (conjugate #C(0.0D0 -1.0D0)) @result{} #C(0.0D0 1.0D0) (conjugate 3.7) @result{} 3.7 @end example @subsubheading Notes:: For a @i{complex} number @t{z}, @example (conjugate z) @equiv{} (complex (realpart z) (- (imagpart z))) @end example @node phase, realpart, conjugate, Numbers Dictionary @subsection phase [Function] @code{phase} @i{number} @result{} @i{phase} @subsubheading Arguments and Values:: @i{number}---a @i{number}. @i{phase}---a @i{number}. @subsubheading Description:: @b{phase} returns the phase of @i{number} (the angle part of its polar representation) in radians, in the range -\pi (exclusive) if minus zero is not supported, or -\pi (inclusive) if minus zero is supported, to \pi (inclusive). The phase of a positive @i{real} number is zero; that of a negative @i{real} number is \pi. The phase of zero is defined to be zero. If @i{number} is a @i{complex float}, the result is a @i{float} of the same @i{type} as the components of @i{number}. If @i{number} is a @i{float}, the result is a @i{float} of the same @i{type}. If @i{number} is a @i{rational} or a @i{complex rational}, the result is a @i{single float}. The branch cut for @b{phase} lies along the negative real axis, continuous with quadrant II. The range consists of that portion of the real axis between -\pi (exclusive) and~\pi (inclusive). The mathematical definition of @b{phase} is as follows: @t{(phase @i{x}) = (atan (imagpart @i{x}) (realpart @i{x}))} @subsubheading Examples:: @example (phase 1) @result{} 0.0s0 (phase 0) @result{} 0.0s0 (phase (cis 30)) @result{} -1.4159266 (phase #c(0 1)) @result{} 1.5707964 @end example @subsubheading Exceptional Situations:: Should signal @b{type-error} if its argument is not a @i{number}. Might signal @b{arithmetic-error}. @subsubheading See Also:: @ref{Rule of Float Substitutability} @node realpart, upgraded-complex-part-type, phase, Numbers Dictionary @subsection realpart, imagpart [Function] @code{realpart} @i{number} @result{} @i{real} @code{imagpart} @i{number} @result{} @i{real} @subsubheading Arguments and Values:: @i{number}---a @i{number}. @i{real}---a @i{real}. @subsubheading Description:: @b{realpart} and @b{imagpart} return the real and imaginary parts of @i{number} respectively. If @i{number} is @i{real}, then @b{realpart} returns @i{number} and @b{imagpart} returns @t{(* 0 @i{number})}, which has the effect that the imaginary part of a @i{rational} is @t{0} and that of a @i{float} is a floating-point zero of the same format. @subsubheading Examples:: @example (realpart #c(23 41)) @result{} 23 (imagpart #c(23 41.0)) @result{} 41.0 (realpart #c(23 41.0)) @result{} 23.0 (imagpart 23.0) @result{} 0.0 @end example @subsubheading Exceptional Situations:: Should signal an error of @i{type} @b{type-error} if @i{number} is not a @i{number}. @subsubheading See Also:: @ref{complex} @node upgraded-complex-part-type, realp, realpart, Numbers Dictionary @subsection upgraded-complex-part-type [Function] @code{upgraded-complex-part-type} @i{typespec {&optional} environment} @result{} @i{upgraded-typespec} @subsubheading Arguments and Values:: @i{typespec}---a @i{type specifier}. @i{environment}---an @i{environment} @i{object}. The default is @b{nil}, denoting the @i{null lexical environment} and the and current @i{global environment}. @i{upgraded-typespec}---a @i{type specifier}. @subsubheading Description:: @b{upgraded-complex-part-type} returns the part type of the most specialized @i{complex} number representation that can hold parts of @i{type} @i{typespec}. The @i{typespec} is a @i{subtype} of (and possibly @i{type equivalent} to) the @i{upgraded-typespec}. The purpose of @b{upgraded-complex-part-type} is to reveal how an implementation does its @i{upgrading}. @subsubheading See Also:: @ref{complex} (@i{function} and @i{type}) @subsubheading Notes:: @node realp, numerator, upgraded-complex-part-type, Numbers Dictionary @subsection realp [Function] @code{realp} @i{object} @result{} @i{generalized-boolean} @subsubheading Arguments and Values:: @i{object}---an @i{object}. @i{generalized-boolean}---a @i{generalized boolean}. @subsubheading Description:: Returns @i{true} if @i{object} is of @i{type} @b{real}; otherwise, returns @i{false}. @subsubheading Examples:: @example (realp 12) @result{} @i{true} (realp #c(5/3 7.2)) @result{} @i{false} (realp nil) @result{} @i{false} (realp (cons 1 2)) @result{} @i{false} @end example @subsubheading Notes:: @example (realp @i{object}) @equiv{} (typep @i{object} 'real) @end example @node numerator, rational, realp, Numbers Dictionary @subsection numerator, denominator [Function] @code{numerator} @i{rational} @result{} @i{numerator} @code{denominator} @i{rational} @result{} @i{denominator} @subsubheading Arguments and Values:: @i{rational}---a @i{rational}. @i{numerator}---an @i{integer}. @i{denominator}---a positive @i{integer}. @subsubheading Description:: @b{numerator} and @b{denominator} reduce @i{rational} to canonical form and compute the numerator or denominator of that number. @b{numerator} and @b{denominator} return the numerator or denominator of the canonical form of @i{rational}. If @i{rational} is an @i{integer}, @b{numerator} returns @i{rational} and @b{denominator} returns 1. @subsubheading Examples:: @example (numerator 1/2) @result{} 1 (denominator 12/36) @result{} 3 (numerator -1) @result{} -1 (denominator (/ -33)) @result{} 33 (numerator (/ 8 -6)) @result{} -4 (denominator (/ 8 -6)) @result{} 3 @end example @subsubheading See Also:: @ref{/} @subsubheading Notes:: @example (gcd (numerator x) (denominator x)) @result{} 1 @end example @node rational, rationalp, numerator, Numbers Dictionary @subsection rational, rationalize [Function] @code{rational} @i{number} @result{} @i{rational} @code{rationalize} @i{number} @result{} @i{rational} @subsubheading Arguments and Values:: @i{number}---a @i{real}. @i{rational}---a @i{rational}. @subsubheading Description:: @b{rational} and @b{rationalize} convert @i{reals} to @i{rationals}. If @i{number} is already @i{rational}, it is returned. If @i{number} is a @i{float}, @b{rational} returns a @i{rational} that is mathematically equal in value to the @i{float}. @b{rationalize} returns a @i{rational} that approximates the @i{float} to the accuracy of the underlying floating-point representation. @b{rational} assumes that the @i{float} is completely accurate. @b{rationalize} assumes that the @i{float} is accurate only to the precision of the floating-point representation. @subsubheading Examples:: @example (rational 0) @result{} 0 (rationalize -11/100) @result{} -11/100 (rational .1) @result{} 13421773/134217728 ;implementation-dependent (rationalize .1) @result{} 1/10 @end example @subsubheading Affected By:: The @i{implementation}. @subsubheading Exceptional Situations:: Should signal an error of @i{type} @b{type-error} if @i{number} is not a @i{real}. Might signal @b{arithmetic-error}. @subsubheading Notes:: It is always the case that @example (float (rational x) x) @equiv{} x @end example and @example (float (rationalize x) x) @equiv{} x @end example That is, rationalizing a @i{float} by either method and then converting it back to a @i{float} of the same format produces the original @i{number}. @node rationalp, ash, rational, Numbers Dictionary @subsection rationalp [Function] @code{rationalp} @i{object} @result{} @i{generalized-boolean} @subsubheading Arguments and Values:: @i{object}---an @i{object}. @i{generalized-boolean}---a @i{generalized boolean}. @subsubheading Description:: Returns @i{true} if @i{object} is of @i{type} @b{rational}; otherwise, returns @i{false}. @subsubheading Examples:: @example (rationalp 12) @result{} @i{true} (rationalp 6/5) @result{} @i{true} (rationalp 1.212) @result{} @i{false} @end example @subsubheading See Also:: @ref{rational} @subsubheading Notes:: @example (rationalp @i{object}) @equiv{} (typep @i{object} 'rational) @end example @node ash, integer-length, rationalp, Numbers Dictionary @subsection ash [Function] @code{ash} @i{integer count} @result{} @i{shifted-integer} @subsubheading Arguments and Values:: @i{integer}---an @i{integer}. @i{count}---an @i{integer}. @i{shifted-integer}---an @i{integer}. @subsubheading Description:: @b{ash} performs the arithmetic shift operation on the binary representation of @i{integer}, which is treated as if it were binary. @b{ash} shifts @i{integer} arithmetically left by @i{count} bit positions if @i{count} is positive, or right @i{count} bit positions if @i{count} is negative. The shifted value of the same sign as @i{integer} is returned. Mathematically speaking, @b{ash} performs the computation @t{floor}(@i{integer}{\cdot} 2^@i{count}). Logically, @b{ash} moves all of the bits in @i{integer} to the left, adding zero-bits at the right, or moves them to the right, discarding bits. @b{ash} is defined to behave as if @i{integer} were represented in two's complement form, regardless of how @i{integers} are represented internally. @subsubheading Examples:: @example (ash 16 1) @result{} 32 (ash 16 0) @result{} 16 (ash 16 -1) @result{} 8 (ash -100000000000000000000000000000000 -100) @result{} -79 @end example @subsubheading Exceptional Situations:: Should signal an error of @i{type} @b{type-error} if @i{integer} is not an @i{integer}. Should signal an error of @i{type} @b{type-error} if @i{count} is not an @i{integer}. Might signal @b{arithmetic-error}. @subsubheading Notes:: @example (logbitp @i{j} (ash @i{n} @i{k})) @equiv{} (and (>= @i{j} @i{k}) (logbitp (- @i{j} @i{k}) @i{n})) @end example @node integer-length, integerp, ash, Numbers Dictionary @subsection integer-length [Function] @code{integer-length} @i{integer} @result{} @i{number-of-bits} @subsubheading Arguments and Values:: @i{integer}---an @i{integer}. @i{number-of-bits}---a non-negative @i{integer}. @subsubheading Description:: Returns the number of bits needed to represent @i{integer} in binary two's-complement format. @subsubheading Examples:: @example (integer-length 0) @result{} 0 (integer-length 1) @result{} 1 (integer-length 3) @result{} 2 (integer-length 4) @result{} 3 (integer-length 7) @result{} 3 (integer-length -1) @result{} 0 (integer-length -4) @result{} 2 (integer-length -7) @result{} 3 (integer-length -8) @result{} 3 (integer-length (expt 2 9)) @result{} 10 (integer-length (1- (expt 2 9))) @result{} 9 (integer-length (- (expt 2 9))) @result{} 9 (integer-length (- (1+ (expt 2 9)))) @result{} 10 @end example @subsubheading Exceptional Situations:: Should signal an error of @i{type} @b{type-error} if @i{integer} is not an @i{integer}. @subsubheading Notes:: This function could have been defined by: @example (defun integer-length (integer) (ceiling (log (if (minusp integer) (- integer) (1+ integer)) 2))) @end example If @i{integer} is non-negative, then its value can be represented in unsigned binary form in a field whose width in bits is no smaller than @t{(integer-length @i{integer})}. Regardless of the sign of @i{integer}, its value can be represented in signed binary two's-complement form in a field whose width in bits is no smaller than @t{(+ (integer-length @i{integer}) 1)}. @node integerp, parse-integer, integer-length, Numbers Dictionary @subsection integerp [Function] @code{integerp} @i{object} @result{} @i{generalized-boolean} @subsubheading Arguments and Values:: @i{object}---an @i{object}. @i{generalized-boolean}---a @i{generalized boolean}. @subsubheading Description:: Returns @i{true} if @i{object} is of @i{type} @b{integer}; otherwise, returns @i{false}. @subsubheading Examples:: @example (integerp 1) @result{} @i{true} (integerp (expt 2 130)) @result{} @i{true} (integerp 6/5) @result{} @i{false} (integerp nil) @result{} @i{false} @end example @subsubheading Notes:: @example (integerp @i{object}) @equiv{} (typep @i{object} 'integer) @end example @node parse-integer, boole, integerp, Numbers Dictionary @subsection parse-integer [Function] @code{parse-integer} @i{string {&key} start end radix junk-allowed} @result{} @i{integer, pos} @subsubheading Arguments and Values:: @i{string}---a @i{string}. @i{start}, @i{end}---@i{bounding index designators} of @i{string}. The defaults for @i{start} and @i{end} are @t{0} and @b{nil}, respectively. @i{radix}---a @i{radix}. The default is @t{10}. @i{junk-allowed}---a @i{generalized boolean}. The default is @i{false}. @i{integer}---an @i{integer} or @i{false}. @i{pos}---a @i{bounding index} of @i{string}. @subsubheading Description:: @b{parse-integer} parses an @i{integer} in the specified @i{radix} from the substring of @i{string} delimited by @i{start} and @i{end}. @b{parse-integer} expects an optional sign (@t{+} or @t{-}) followed by a a non-empty sequence of digits to be interpreted in the specified @i{radix}. Optional leading and trailing @i{whitespace}_1 is ignored. @b{parse-integer} does not recognize the syntactic radix-specifier prefixes @t{#O}, @t{#B}, @t{#X}, and @t{#@i{n}R}, nor does it recognize a trailing decimal point. If @i{junk-allowed} is @i{false}, an error of @i{type} @b{parse-error} is signaled if substring does not consist entirely of the representation of a signed @i{integer}, possibly surrounded on either side by @i{whitespace}_1 @i{characters}. The first @i{value} returned is either the @i{integer} that was parsed, or else @b{nil} if no syntactically correct @i{integer} was seen but @i{junk-allowed} was @i{true}. The second @i{value} is either the index into the @i{string} of the delimiter that terminated the parse, or the upper @i{bounding index} of the substring if the parse terminated at the end of the substring (as is always the case if @i{junk-allowed} is @i{false}). @subsubheading Examples:: @example (parse-integer "123") @result{} 123, 3 (parse-integer "123" :start 1 :radix 5) @result{} 13, 3 (parse-integer "no-integer" :junk-allowed t) @result{} NIL, 0 @end example @subsubheading Exceptional Situations:: If @i{junk-allowed} is @i{false}, an error is signaled if substring does not consist entirely of the representation of an @i{integer}, possibly surrounded on either side by @i{whitespace}_1 characters. @node boole, boole-1, parse-integer, Numbers Dictionary @subsection boole [Function] @code{boole} @i{op integer-1 integer-2} @result{} @i{result-integer} @subsubheading Arguments and Values:: @i{Op}---a @i{bit-wise logical operation specifier}. @i{integer-1}---an @i{integer}. @i{integer-2}---an @i{integer}. @i{result-integer}---an @i{integer}. @subsubheading Description:: @b{boole} performs bit-wise logical operations on @i{integer-1} and @i{integer-2}, which are treated as if they were binary and in two's complement representation. The operation to be performed and the return value are determined by @i{op}. @b{boole} returns the values specified for any @i{op} in Figure 12--16. { @group @noindent @w{ Op Result } @w{ @b{boole-1} @i{integer-1} } @w{ @b{boole-2} @i{integer-2} } @w{ @b{boole-andc1} and complement of @i{integer-1} with @i{integer-2} } @w{ @b{boole-andc2} and @i{integer-1} with complement of @i{integer-2} } @w{ @b{boole-and} and } @w{ @b{boole-c1} complement of @i{integer-1} } @w{ @b{boole-c2} complement of @i{integer-2} } @w{ @b{boole-clr} always 0 (all zero bits) } @w{ @b{boole-eqv} equivalence (exclusive nor) } @w{ @b{boole-ior} inclusive or } @w{ @b{boole-nand} not-and } @w{ @b{boole-nor} not-or } @w{ @b{boole-orc1} or complement of @i{integer-1} with @i{integer-2} } @w{ @b{boole-orc2} or @i{integer-1} with complement of @i{integer-2} } @w{ @b{boole-set} always -1 (all one bits) } @w{ @b{boole-xor} exclusive or } @noindent @w{ Figure 12--16: Bit-Wise Logical Operations } @end group } @subsubheading Examples:: @example (boole boole-ior 1 16) @result{} 17 (boole boole-and -2 5) @result{} 4 (boole boole-eqv 17 15) @result{} -31 ;;; These examples illustrate the result of applying BOOLE and each ;;; of the possible values of OP to each possible combination of bits. (progn (format t "~&Results of (BOOLE #b0011 #b0101) ...~ ~ (dolist (symbol '(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)) (let ((result (boole (symbol-value symbol) #b0011 #b0101))) (format t "~& ~A~13T~3,' D~23T~:*~5,' B~31T ...~4,'0B~ symbol result (logand result #b1111))))) @t{ |> } Results of (BOOLE #b0011 #b0101) ... @t{ |> } ---Op-------Decimal-----Binary----Bits--- @t{ |> } BOOLE-1 3 11 ...0011 @t{ |> } BOOLE-2 5 101 ...0101 @t{ |> } BOOLE-AND 1 1 ...0001 @t{ |> } BOOLE-ANDC1 4 100 ...0100 @t{ |> } BOOLE-ANDC2 2 10 ...0010 @t{ |> } BOOLE-C1 -4 -100 ...1100 @t{ |> } BOOLE-C2 -6 -110 ...1010 @t{ |> } BOOLE-CLR 0 0 ...0000 @t{ |> } BOOLE-EQV -7 -111 ...1001 @t{ |> } BOOLE-IOR 7 111 ...0111 @t{ |> } BOOLE-NAND -2 -10 ...1110 @t{ |> } BOOLE-NOR -8 -1000 ...1000 @t{ |> } BOOLE-ORC1 -3 -11 ...1101 @t{ |> } BOOLE-ORC2 -5 -101 ...1011 @t{ |> } BOOLE-SET -1 -1 ...1111 @t{ |> } BOOLE-XOR 6 110 ...0110 @result{} NIL @end example @subsubheading Exceptional Situations:: Should signal @b{type-error} if its first argument is not a @i{bit-wise logical operation specifier} or if any subsequent argument is not an @i{integer}. @subsubheading See Also:: @ref{logand; logandc1; logandc2; logeqv; logior; lognand; lognor; lognot; logorc1; logorc2; logxor} @subsubheading Notes:: In general, @example (boole boole-and x y) @equiv{} (logand x y) @end example @i{Programmers} who would prefer to use numeric indices rather than @i{bit-wise logical operation specifiers} can get an equivalent effect by a technique such as the following: @example ;; The order of the values in this `table' are such that ;; (logand (boole (elt boole-n-vector n) #b0101 #b0011) #b1111) => n (defconstant boole-n-vector (vector boole-clr boole-and boole-andc1 boole-2 boole-andc2 boole-1 boole-xor boole-ior boole-nor boole-eqv boole-c1 boole-orc1 boole-c2 boole-orc2 boole-nand boole-set)) @result{} BOOLE-N-VECTOR (proclaim '(inline boole-n)) @result{} @i{implementation-dependent} (defun boole-n (n integer &rest more-integers) (apply #'boole (elt boole-n-vector n) integer more-integers)) @result{} BOOLE-N (boole-n #b0111 5 3) @result{} 7 (boole-n #b0001 5 3) @result{} 1 (boole-n #b1101 5 3) @result{} -3 (loop for n from #b0000 to #b1111 collect (boole-n n 5 3)) @result{} (0 1 2 3 4 5 6 7 -8 -7 -6 -5 -4 -3 -2 -1) @end example @node boole-1, logand, boole, Numbers Dictionary @subsection boole-1, boole-2, boole-and, boole-andc1, boole-andc2, @subheading boole-c1, boole-c2, boole-clr, boole-eqv, boole-ior, @subheading boole-nand, boole-nor, boole-orc1, boole-orc2, boole-set, @subheading boole-xor @flushright @i{[Constant Variable]} @end flushright @subsubheading Constant Value:: The identity and nature of the @i{values} of each of these @i{variables} is @i{implementation-dependent}, except that it must be @i{distinct} from each of the @i{values} of the others, and it must be a valid first @i{argument} to the @i{function} @b{boole}. @subsubheading Description:: Each of these @i{constants} has a @i{value} which is one of the sixteen possible @i{bit-wise logical operation specifiers}. @subsubheading Examples:: @example (boole boole-ior 1 16) @result{} 17 (boole boole-and -2 5) @result{} 4 (boole boole-eqv 17 15) @result{} -31 @end example @subsubheading See Also:: @ref{boole} @node logand, logbitp, boole-1, Numbers Dictionary @subsection logand, logandc1, logandc2, logeqv, logior, @subheading lognand, lognor, lognot, logorc1, logorc2, @subheading logxor @flushright @i{[Function]} @end flushright @code{logand} @i{{&rest} integers} @result{} @i{result-integer} @code{logandc} @i{1} @result{} @i{integer-1 integer-2} {result-integer} @code{logandc} @i{2} @result{} @i{integer-1 integer-2} {result-integer} @code{logeqv} @i{{&rest} integers} @result{} @i{result-integer} @code{logior} @i{{&rest} integers} @result{} @i{result-integer} @code{lognand} @i{integer-1 integer-2} @result{} @i{result-integer} @code{lognor} @i{integer-1 integer-2} @result{} @i{result-integer} @code{lognot} @i{integer} @result{} @i{result-integer} @code{logorc} @i{1} @result{} @i{integer-1 integer-2} {result-integer} @code{logorc} @i{2} @result{} @i{integer-1 integer-2} {result-integer} @code{logxor} @i{{&rest} integers} @result{} @i{result-integer} @subsubheading Arguments and Values:: @i{integers}---@i{integers}. @i{integer}---an @i{integer}. @i{integer-1}---an @i{integer}. @i{integer-2}---an @i{integer}. @i{result-integer}---an @i{integer}. @subsubheading Description:: The @i{functions} @b{logandc1}, @b{logandc2}, @b{logand}, @b{logeqv}, @b{logior}, @b{lognand}, @b{lognor}, @b{lognot}, @b{logorc1}, @b{logorc2}, and @b{logxor} perform bit-wise logical operations on their @i{arguments}, that are treated as if they were binary. Figure 12--17 lists the meaning of each of the @i{functions}. Where an `identity' is shown, it indicates the @i{value} @i{yielded} by the @i{function} when no @i{arguments} are supplied. @group @noindent @w{ Function Identity Operation performed } @w{ @b{logandc1} --- and complement of @i{integer-1} with @i{integer-2} } @w{ @b{logandc2} --- and @i{integer-1} with complement of @i{integer-2} } @w{ @b{logand} @t{-1} and } @w{ @b{logeqv} @t{-1} equivalence (exclusive nor) } @w{ @b{logior} @t{0} inclusive or } @w{ @b{lognand} --- complement of @i{integer-1} and @i{integer-2} } @w{ @b{lognor} --- complement of @i{integer-1} or @i{integer-2} } @w{ @b{lognot} --- complement } @w{ @b{logorc1} --- or complement of @i{integer-1} with @i{integer-2} } @w{ @b{logorc2} --- or @i{integer-1} with complement of @i{integer-2} } @w{ @b{logxor} @t{0} exclusive or } @noindent @w{ Figure 12--17: Bit-wise Logical Operations on Integers } @end group Negative @i{integers} are treated as if they were in two's-complement notation. @subsubheading Examples:: @example (logior 1 2 4 8) @result{} 15 (logxor 1 3 7 15) @result{} 10 (logeqv) @result{} -1 (logand 16 31) @result{} 16 (lognot 0) @result{} -1 (lognot 1) @result{} -2 (lognot -1) @result{} 0 (lognot (1+ (lognot 1000))) @result{} 999 ;;; In the following example, m is a mask. For each bit in ;;; the mask that is a 1, the corresponding bits in x and y are ;;; exchanged. For each bit in the mask that is a 0, the ;;; corresponding bits of x and y are left unchanged. (flet ((show (m x y) (format t "~ m x y))) (let ((m #o007750) (x #o452576) (y #o317407)) (show m x y) (let ((z (logand (logxor x y) m))) (setq x (logxor z x)) (setq y (logxor z y)) (show m x y)))) @t{ |> } m = #o007750 @t{ |> } x = #o452576 @t{ |> } y = #o317407 @t{ |> } @t{ |> } m = #o007750 @t{ |> } x = #o457426 @t{ |> } y = #o312557 @result{} NIL @end example @subsubheading Exceptional Situations:: Should signal @b{type-error} if any argument is not an @i{integer}. @subsubheading See Also:: @ref{boole} @subsubheading Notes:: @t{(logbitp @i{k} -1)} returns @i{true} for all values of @i{k}. Because the following functions are not associative, they take exactly two arguments rather than any number of arguments. @example (lognand @i{n1} @i{n2}) @equiv{} (lognot (logand @i{n1} @i{n2})) (lognor @i{n1} @i{n2}) @equiv{} (lognot (logior @i{n1} @i{n2})) (logandc1 @i{n1} @i{n2}) @equiv{} (logand (lognot @i{n1}) @i{n2}) (logandc2 @i{n1} @i{n2}) @equiv{} (logand @i{n1} (lognot @i{n2})) (logiorc1 @i{n1} @i{n2}) @equiv{} (logior (lognot @i{n1}) @i{n2}) (logiorc2 @i{n1} @i{n2}) @equiv{} (logior @i{n1} (lognot @i{n2})) (logbitp @i{j} (lognot @i{x})) @equiv{} (not (logbitp @i{j} @i{x})) @end example @node logbitp, logcount, logand, Numbers Dictionary @subsection logbitp [Function] @code{logbitp} @i{index integer} @result{} @i{generalized-boolean} @subsubheading Arguments and Values:: @i{index}---a non-negative @i{integer}. @i{integer}---an @i{integer}. @i{generalized-boolean}---a @i{generalized boolean}. @subsubheading Description:: @b{logbitp} is used to test the value of a particular bit in @i{integer}, that is treated as if it were binary. The value of @b{logbitp} is @i{true} if the bit in @i{integer} whose index is @i{index} (that is, its weight is 2^@i{index}) is a one-bit; otherwise it is @i{false}. Negative @i{integers} are treated as if they were in two's-complement notation. @subsubheading Examples:: @example (logbitp 1 1) @result{} @i{false} (logbitp 0 1) @result{} @i{true} (logbitp 3 10) @result{} @i{true} (logbitp 1000000 -1) @result{} @i{true} (logbitp 2 6) @result{} @i{true} (logbitp 0 6) @result{} @i{false} @end example @subsubheading Exceptional Situations:: Should signal an error of @i{type} @b{type-error} if @i{index} is not a non-negative @i{integer}. Should signal an error of @i{type} @b{type-error} if @i{integer} is not an @i{integer}. @subsubheading Notes:: @example (logbitp @i{k} @i{n}) @equiv{} (ldb-test (byte 1 @i{k}) @i{n}) @end example @node logcount, logtest, logbitp, Numbers Dictionary @subsection logcount [Function] @code{logcount} @i{integer} @result{} @i{number-of-on-bits} @subsubheading Arguments and Values:: @i{integer}---an @i{integer}. @i{number-of-on-bits}---a non-negative @i{integer}. @subsubheading Description:: Computes and returns the number of bits in the two's-complement binary representation of @i{integer} that are `on' or `set'. If @i{integer} is negative, the @t{0} bits are counted; otherwise, the @t{1} bits are counted. @subsubheading Examples:: @example (logcount 0) @result{} 0 (logcount -1) @result{} 0 (logcount 7) @result{} 3 (logcount 13) @result{} 3 ;Two's-complement binary: ...0001101 (logcount -13) @result{} 2 ;Two's-complement binary: ...1110011 (logcount 30) @result{} 4 ;Two's-complement binary: ...0011110 (logcount -30) @result{} 4 ;Two's-complement binary: ...1100010 (logcount (expt 2 100)) @result{} 1 (logcount (- (expt 2 100))) @result{} 100 (logcount (- (1+ (expt 2 100)))) @result{} 1 @end example @subsubheading Exceptional Situations:: Should signal @b{type-error} if its argument is not an @i{integer}. @subsubheading Notes:: Even if the @i{implementation} does not represent @i{integers} internally in two's complement binary, @b{logcount} behaves as if it did. The following identity always holds: @example (logcount @i{x}) @equiv{} (logcount (- (+ @i{x} 1))) @equiv{} (logcount (lognot @i{x})) @end example @node logtest, byte, logcount, Numbers Dictionary @subsection logtest [Function] @code{logtest} @i{integer-1 integer-2} @result{} @i{generalized-boolean} @subsubheading Arguments and Values:: @i{integer-1}---an @i{integer}. @i{integer-2}---an @i{integer}. @i{generalized-boolean}---a @i{generalized boolean}. @subsubheading Description:: Returns @i{true} if any of the bits designated by the 1's in @i{integer-1} is 1 in @i{integer-2}; otherwise it is @i{false}. @i{integer-1} and @i{integer-2} are treated as if they were binary. Negative @i{integer-1} and @i{integer-2} are treated as if they were represented in two's-complement binary. @subsubheading Examples:: @example (logtest 1 7) @result{} @i{true} (logtest 1 2) @result{} @i{false} (logtest -2 -1) @result{} @i{true} (logtest 0 -1) @result{} @i{false} @end example @subsubheading Exceptional Situations:: Should signal an error of @i{type} @b{type-error} if @i{integer-1} is not an @i{integer}. Should signal an error of @i{type} @b{type-error} if @i{integer-2} is not an @i{integer}. @subsubheading Notes:: @example (logtest @i{x} @i{y}) @equiv{} (not (zerop (logand @i{x} @i{y}))) @end example @node byte, deposit-field, logtest, Numbers Dictionary @subsection byte, byte-size, byte-position [Function] @code{byte} @i{size position} @result{} @i{bytespec} @code{byte-size} @i{bytespec} @result{} @i{size} @code{byte-position} @i{bytespec} @result{} @i{position} @subsubheading Arguments and Values:: @i{size}, @i{position}---a non-negative @i{integer}. @i{bytespec}---a @i{byte specifier}. @subsubheading Description:: @b{byte} returns a @i{byte specifier} that indicates a @i{byte} of width @i{size} and whose bits have weights 2^{@i{position} + @i{size} - 1\/} through 2^@i{position}, and whose representation is @i{implementation-dependent}. @b{byte-size} returns the number of bits specified by @i{bytespec}. @b{byte-position} returns the position specified by @i{bytespec}. @subsubheading Examples:: @example (setq b (byte 100 200)) @result{} # (byte-size b) @result{} 100 (byte-position b) @result{} 200 @end example @subsubheading See Also:: @ref{ldb} , @ref{dpb} @subsubheading Notes:: @example (byte-size (byte @i{j} @i{k})) @equiv{} @i{j} (byte-position (byte @i{j} @i{k})) @equiv{} @i{k} @end example A @i{byte} of @i{size} of @t{0} is permissible; it refers to a @i{byte} of width zero. For example, @example (ldb (byte 0 3) #o7777) @result{} 0 (dpb #o7777 (byte 0 3) 0) @result{} 0 @end example @node deposit-field, dpb, byte, Numbers Dictionary @subsection deposit-field [Function] @code{deposit-field} @i{newbyte bytespec integer} @result{} @i{result-integer} @subsubheading Arguments and Values:: @i{newbyte}---an @i{integer}. @i{bytespec}---a @i{byte specifier}. @i{integer}---an @i{integer}. @i{result-integer}---an @i{integer}. @subsubheading Description:: Replaces a field of bits within @i{integer}; specifically, returns an @i{integer} that contains the bits of @i{newbyte} within the @i{byte} specified by @i{bytespec}, and elsewhere contains the bits of @i{integer}. @subsubheading Examples:: @example (deposit-field 7 (byte 2 1) 0) @result{} 6 (deposit-field -1 (byte 4 0) 0) @result{} 15 (deposit-field 0 (byte 2 1) -3) @result{} -7 @end example @subsubheading See Also:: @ref{byte; byte-size; byte-position} , @ref{dpb} @subsubheading Notes:: @example (logbitp @i{j} (deposit-field @i{m} (byte @i{s} @i{p}) @i{n})) @equiv{} (if (and (>= @i{j} @i{p}) (< @i{j} (+ @i{p} @i{s}))) (logbitp @i{j} @i{m}) (logbitp @i{j} @i{n})) @end example @b{deposit-field} is to @b{mask-field} as @b{dpb} is to @b{ldb}. @node dpb, ldb, deposit-field, Numbers Dictionary @subsection dpb [Function] @code{dpb} @i{newbyte bytespec integer} @result{} @i{result-integer} @subsubheading Pronunciation:: pronounced ,de 'pib or pronounced ,de 'pe b or pronounced 'd\=e 'p\=e 'b\=e @subsubheading Arguments and Values:: @i{newbyte}---an @i{integer}. @i{bytespec}---a @i{byte specifier}. @i{integer}---an @i{integer}. @i{result-integer}---an @i{integer}. @subsubheading Description:: @b{dpb} (deposit byte) is used to replace a field of bits within @i{integer}. @b{dpb} returns an @i{integer} that is the same as @i{integer} except in the bits specified by @i{bytespec}. Let @t{s} be the size specified by @i{bytespec}; then the low @t{s} bits of @i{newbyte} appear in the result in the byte specified by @i{bytespec}. @i{Newbyte} is interpreted as being right-justified, as if it were the result of @b{ldb}. @subsubheading Examples:: @example (dpb 1 (byte 1 10) 0) @result{} 1024 (dpb -2 (byte 2 10) 0) @result{} 2048 (dpb 1 (byte 2 10) 2048) @result{} 1024 @end example @subsubheading See Also:: @ref{byte; byte-size; byte-position} , @ref{deposit-field} , @ref{ldb} @subsubheading Notes:: @example (logbitp @i{j} (dpb @i{m} (byte @i{s} @i{p}) @i{n})) @equiv{} (if (and (>= @i{j} @i{p}) (< @i{j} (+ @i{p} @i{s}))) (logbitp (- @i{j} @i{p}) @i{m}) (logbitp @i{j} @i{n})) @end example In general, @example (dpb @i{x} (byte 0 @i{y}) @i{z}) @result{} @i{z} @end example for all valid values of @i{x}, @i{y}, and @i{z}. Historically, the name ``dpb'' comes from a DEC PDP-10 assembly language instruction meaning ``deposit byte.'' @node ldb, ldb-test, dpb, Numbers Dictionary @subsection ldb [Accessor] @code{ldb} @i{bytespec integer} @result{} @i{byte} (setf (@code{ ldb} @i{bytespec place}) new-byte)@* @subsubheading Pronunciation:: pronounced 'lid ib or pronounced 'lid e b or pronounced 'el 'd\=e 'b\=e @subsubheading Arguments and Values:: @i{bytespec}---a @i{byte specifier}. @i{integer}---an @i{integer}. @i{byte}, @i{new-byte}---a non-negative @i{integer}. @subsubheading Description:: @b{ldb} extracts and returns the @i{byte} of @i{integer} specified by @i{bytespec}. @b{ldb} returns an @i{integer} in which the bits with weights 2^{(@i{s}-1)} through 2^{0} are the same as those in @i{integer} with weights 2^{(@i{p}+@i{s}-1)} through 2^@i{p}, and all other bits zero; @i{s} is @t{(byte-size @i{bytespec})} and @i{p} is @t{(byte-position @i{bytespec})}. @b{setf} may be used with @b{ldb} to modify a byte within the @i{integer} that is stored in a given @i{place}. The order of evaluation, when an @b{ldb} form is supplied to @b{setf}, is exactly left-to-right. @ITindex{order of evaluation} @ITindex{evaluation order} The effect is to perform a @b{dpb} operation and then store the result back into the @i{place}. @subsubheading Examples:: @example (ldb (byte 2 1) 10) @result{} 1 (setq a (list 8)) @result{} (8) (setf (ldb (byte 2 1) (car a)) 1) @result{} 1 a @result{} (10) @end example @subsubheading See Also:: @ref{byte; byte-size; byte-position} , @b{byte-position}, @b{byte-size}, @ref{dpb} @subsubheading Notes:: @example (logbitp @i{j} (ldb (byte @i{s} @i{p}) @i{n})) @equiv{} (and (< @i{j} @i{s}) (logbitp (+ @i{j} @i{p}) @i{n})) @end example In general, @example (ldb (byte 0 @i{x}) @i{y}) @result{} 0 @end example for all valid values of @i{x} and @i{y}. Historically, the name ``ldb'' comes from a DEC PDP-10 assembly language instruction meaning ``load byte.'' @node ldb-test, mask-field, ldb, Numbers Dictionary @subsection ldb-test [Function] @code{ldb-test} @i{bytespec integer} @result{} @i{generalized-boolean} @subsubheading Arguments and Values:: @i{bytespec}---a @i{byte specifier}. @i{integer}---an @i{integer}. @i{generalized-boolean}---a @i{generalized boolean}. @subsubheading Description:: Returns @i{true} if any of the bits of the byte in @i{integer} specified by @i{bytespec} is non-zero; otherwise returns @i{false}. @subsubheading Examples:: @example (ldb-test (byte 4 1) 16) @result{} @i{true} (ldb-test (byte 3 1) 16) @result{} @i{false} (ldb-test (byte 3 2) 16) @result{} @i{true} @end example @subsubheading See Also:: @ref{byte; byte-size; byte-position} , @ref{ldb} , @ref{zerop} @subsubheading Notes:: @example (ldb-test bytespec n) @equiv{} (not (zerop (ldb bytespec n))) @equiv{} (logtest (ldb bytespec -1) n) @end example @node mask-field, most-positive-fixnum, ldb-test, Numbers Dictionary @subsection mask-field [Accessor] @code{mask-field} @i{bytespec integer} @result{} @i{masked-integer} (setf (@code{ mask-field} @i{bytespec place}) new-masked-integer)@* @subsubheading Arguments and Values:: @i{bytespec}---a @i{byte specifier}. @i{integer}---an @i{integer}. @i{masked-integer}, @i{new-masked-integer}---a non-negative @i{integer}. @subsubheading Description:: @b{mask-field} performs a ``mask'' operation on @i{integer}. It returns an @i{integer} that has the same bits as @i{integer} in the @i{byte} specified by @i{bytespec}, but that has zero-bits everywhere else. @b{setf} may be used with @b{mask-field} to modify a byte within the @i{integer} that is stored in a given @i{place}. The effect is to perform a @b{deposit-field} operation and then store the result back into the @i{place}. @subsubheading Examples:: @example (mask-field (byte 1 5) -1) @result{} 32 (setq a 15) @result{} 15 (mask-field (byte 2 0) a) @result{} 3 a @result{} 15 (setf (mask-field (byte 2 0) a) 1) @result{} 1 a @result{} 13 @end example @subsubheading See Also:: @ref{byte; byte-size; byte-position} , @ref{ldb} @subsubheading Notes:: @example (ldb @i{bs} (mask-field @i{bs} @i{n})) @equiv{} (ldb @i{bs} @i{n}) (logbitp @i{j} (mask-field (byte @i{s} @i{p}) @i{n})) @equiv{} (and (>= @i{j} @i{p}) (< @i{j} @i{s}) (logbitp @i{j} @i{n})) (mask-field @i{bs} @i{n}) @equiv{} (logand @i{n} (dpb -1 @i{bs} 0)) @end example @node most-positive-fixnum, decode-float, mask-field, Numbers Dictionary @subsection most-positive-fixnum, most-negative-fixnum [Constant Variable] @subsubheading Constant Value:: @i{implementation-dependent}. @subsubheading Description:: @b{most-positive-fixnum} is that @i{fixnum} closest in value to positive infinity provided by the implementation, and greater than or equal to both 2^{15} - 1 and @b{array-dimension-limit}. @b{most-negative-fixnum} is that @i{fixnum} closest in value to negative infinity provided by the implementation, and less than or equal to -2^{15}. @node decode-float, float, most-positive-fixnum, Numbers Dictionary @subsection decode-float, scale-float, float-radix, float-sign, @subheading float-digits, float-precision, integer-decode-float @flushright @i{[Function]} @end flushright @code{decode-float} @i{float} @result{} @i{significand, exponent, sign} @code{scale-float} @i{float integer} @result{} @i{scaled-float} @code{float-radix} @i{float} @result{} @i{float-radix} @code{float-sign} @i{float-1 {&optional} float-2} @result{} @i{signed-float} @code{float-digits} @i{float} @result{} @i{digits1} @code{float-precision} @i{float} @result{} @i{digits2} @code{integer-decode-float} @i{float} @result{} @i{significand, exponent, integer-sign} @subsubheading Arguments and Values:: @i{digits1}---a non-negative @i{integer}. @i{digits2}---a non-negative @i{integer}. @i{exponent}---an @i{integer}. @i{float}---a @i{float}. @i{float-1}---a @i{float}. @i{float-2}---a @i{float}. @i{float-radix}---an @i{integer}. @i{integer}---a non-negative @i{integer}. @i{integer-sign}---the @i{integer} @t{-1}, or the @i{integer} @t{1}. @i{scaled-float}---a @i{float}. @i{sign}---A @i{float} of the same @i{type} as @i{float} but numerically equal to @t{1.0} or @t{-1.0}. @i{signed-float}---a @i{float}. @i{significand}---a @i{float}. @subsubheading Description:: @b{decode-float} computes three values that characterize @i{float}. The first value is of the same @i{type} as @i{float} and represents the significand. The second value represents the exponent to which the radix (notated in this description by @i{b}) must be raised to obtain the value that, when multiplied with the first result, produces the absolute value of @i{float}. If @i{float} is zero, any @i{integer} value may be returned, provided that the identity shown for @b{scale-float} holds. The third value is of the same @i{type} as @i{float} and is 1.0 if @i{float} is greater than or equal to zero or -1.0 otherwise. @b{decode-float} divides @i{float} by an integral power of @i{b} so as to bring its value between 1/@i{b} (inclusive) and~1 (exclusive), and returns the quotient as the first value. If @i{float} is zero, however, the result equals the absolute value of @i{float} (that is, if there is a negative zero, its significand is considered to be a positive zero). @b{scale-float} returns @t{(* @i{float} (expt (float @i{b} @i{float}) @i{integer}))\/}, where @i{b} is the radix of the floating-point representation. @i{float} is not necessarily between 1/@i{b} and~1. @b{float-radix} returns the radix of @i{float}. @b{float-sign} returns a number @t{z} such that @t{z} and @i{float-1} have the same sign and also such that @t{z} and @i{float-2} have the same absolute value. If @i{float-2} is not supplied, its value is @t{(float 1 @i{float-1})}. If an implementation has distinct representations for negative zero and positive zero, then @t{(float-sign -0.0)} @result{} @t{-1.0}. @b{float-digits} returns the number of radix @i{b} digits used in the representation of @i{float} (including any implicit digits, such as a ``hidden bit''). @b{float-precision} returns the number of significant radix @i{b} digits present in @i{float}; if @i{float} is a @i{float} zero, then the result is an @i{integer} zero. For @i{normalized} @i{floats}, the results of @b{float-digits} and @b{float-precision} are the same, but the precision is less than the number of representation digits for a @i{denormalized} or zero number. @b{integer-decode-float} computes three values that characterize @i{float} - the significand scaled so as to be an @i{integer}, and the same last two values that are returned by @b{decode-float}. If @i{float} is zero, @b{integer-decode-float} returns zero as the first value. The second value bears the same relationship to the first value as for @b{decode-float}: @example (multiple-value-bind (signif expon sign) (integer-decode-float f) (scale-float (float signif f) expon)) @equiv{} (abs f) @end example @subsubheading Examples:: @example ;; Note that since the purpose of this functionality is to expose ;; details of the implementation, all of these examples are necessarily ;; very implementation-dependent. Results may vary widely. ;; Values shown here are chosen consistently from one particular implementation. (decode-float .5) @result{} 0.5, 0, 1.0 (decode-float 1.0) @result{} 0.5, 1, 1.0 (scale-float 1.0 1) @result{} 2.0 (scale-float 10.01 -2) @result{} 2.5025 (scale-float 23.0 0) @result{} 23.0 (float-radix 1.0) @result{} 2 (float-sign 5.0) @result{} 1.0 (float-sign -5.0) @result{} -1.0 (float-sign 0.0) @result{} 1.0 (float-sign 1.0 0.0) @result{} 0.0 (float-sign 1.0 -10.0) @result{} 10.0 (float-sign -1.0 10.0) @result{} -10.0 (float-digits 1.0) @result{} 24 (float-precision 1.0) @result{} 24 (float-precision least-positive-single-float) @result{} 1 (integer-decode-float 1.0) @result{} 8388608, -23, 1 @end example @subsubheading Affected By:: The implementation's representation for @i{floats}. @subsubheading Exceptional Situations:: The functions @b{decode-float}, @b{float-radix}, @b{float-digits}, @b{float-precision}, and @b{integer-decode-float} should signal an error if their only argument is not a @i{float}. The @i{function} @b{scale-float} should signal an error if its first argument is not a @i{float} or if its second argument is not an @i{integer}. The @i{function} @b{float-sign} should signal an error if its first argument is not a @i{float} or if its second argument is supplied but is not a @i{float}. @subsubheading Notes:: The product of the first result of @b{decode-float} or @b{integer-decode-float}, of the radix raised to the power of the second result, and of the third result is exactly equal to the value of @i{float}. @example (multiple-value-bind (signif expon sign) (decode-float f) (scale-float signif expon)) @equiv{} (abs f) @end example and @example (multiple-value-bind (signif expon sign) (decode-float f) (* (scale-float signif expon) sign)) @equiv{} f @end example @node float, floatp, decode-float, Numbers Dictionary @subsection float [Function] @code{float} @i{number {&optional} prototype} @result{} @i{float} @subsubheading Arguments and Values:: @i{number}---a @i{real}. @i{prototype}---a @i{float}. @i{float}---a @i{float}. @subsubheading Description:: @b{float} converts a @i{real} number to a @i{float}. If a @i{prototype} is supplied, a @i{float} is returned that is mathematically equal to @i{number} but has the same format as @i{prototype}. If @i{prototype} is not supplied, then if the @i{number} is already a @i{float}, it is returned; otherwise, a @i{float} is returned that is mathematically equal to @i{number} but is a @i{single float}. @subsubheading Examples:: @example (float 0) @result{} 0.0 (float 1 .5) @result{} 1.0 (float 1.0) @result{} 1.0 (float 1/2) @result{} 0.5 @result{} 1.0d0 @i{OR}@result{} 1.0 (eql (float 1.0 1.0d0) 1.0d0) @result{} @i{true} @end example @subsubheading See Also:: @ref{coerce} @node floatp, most-positive-short-float, float, Numbers Dictionary @subsection floatp [Function] @code{floatp} @i{object} {generalized-boolean} @subsubheading Arguments and Values:: @i{object}---an @i{object}. @i{generalized-boolean}---a @i{generalized boolean}. @subsubheading Description:: Returns @i{true} if @i{object} is of @i{type} @b{float}; otherwise, returns @i{false}. @subsubheading Examples:: @example (floatp 1.2d2) @result{} @i{true} (floatp 1.212) @result{} @i{true} (floatp 1.2s2) @result{} @i{true} (floatp (expt 2 130)) @result{} @i{false} @end example @subsubheading Notes:: @example (floatp @i{object}) @equiv{} (typep @i{object} 'float) @end example @node most-positive-short-float, short-float-epsilon, floatp, Numbers Dictionary @subsection most-positive-short-float, least-positive-short-float, @subheading least-positive-normalized-short-float, @subheading most-positive-double-float, least-positive-double-float, @subheading least-positive-normalized-double-float, @subheading most-positive-long-float, least-positive-long-float, @subheading least-positive-normalized-long-float, @subheading most-positive-single-float, least-positive-single-float, @subheading least-positive-normalized-single-float, @subheading most-negative-short-float, least-negative-short-float, @subheading least-negative-normalized-short-float, @subheading most-negative-single-float, least-negative-single-float, @subheading least-negative-normalized-single-float, @subheading most-negative-double-float, least-negative-double-float, @subheading least-negative-normalized-double-float, @subheading most-negative-long-float, least-negative-long-float, @subheading least-negative-normalized-long-float @flushright @i{[Constant Variable]} @end flushright @subsubheading Constant Value:: @i{implementation-dependent}. @subsubheading Description:: These @i{constant variables} provide a way for programs to examine the @i{implementation-defined} limits for the various float formats. Of these @i{variables}, each which has ``@t{-normalized}'' in its @i{name} must have a @i{value} which is a @i{normalized} @i{float}, and each which does not have ``@t{-normalized}'' in its name may have a @i{value} which is either a @i{normalized} @i{float} or a @i{denormalized} @i{float}, as appropriate. Of these @i{variables}, each which has ``@t{short-float}'' in its name must have a @i{value} which is a @i{short float}, each which has ``@t{single-float}'' in its name must have a @i{value} which is a @i{single float}, each which has ``@t{double-float}'' in its name must have a @i{value} which is a @i{double float}, and each which has ``@t{long-float}'' in its name must have a @i{value} which is a @i{long float}. @table @asis @item @t{*} @b{most-positive-short-float}, @b{most-positive-single-float}, @b{most-positive-double-float}, @b{most-positive-long-float} Each of these @i{constant variables} has as its @i{value} the positive @i{float} of the largest magnitude (closest in value to, but not equal to, positive infinity) for the float format implied by its name. @item @t{*} @b{least-positive-short-float}, @b{least-positive-normalized-short-float}, @b{least-positive-single-float}, @b{least-positive-normalized-single-float}, @b{least-positive-double-float}, @b{least-positive-normalized-double-float}, @b{least-positive-long-float}, @b{least-positive-normalized-long-float} Each of these @i{constant variables} has as its @i{value} the smallest positive (nonzero) @i{float} for the float format implied by its name. @item @t{*} @b{least-negative-short-float}, @b{least-negative-normalized-short-float}, @b{least-negative-single-float}, @b{least-negative-normalized-single-float}, @b{least-negative-double-float}, @b{least-negative-normalized-double-float}, @b{least-negative-long-float}, @b{least-negative-normalized-long-float} Each of these @i{constant variables} has as its @i{value} the negative (nonzero) @i{float} of the smallest magnitude for the float format implied by its name. (If an implementation supports minus zero as a @i{different} @i{object} from positive zero, this value must not be minus zero.) @item @t{*} @b{most-negative-short-float}, @b{most-negative-single-float}, @b{most-negative-double-float}, @b{most-negative-long-float} Each of these @i{constant variables} has as its @i{value} the negative @i{float} of the largest magnitude (closest in value to, but not equal to, negative infinity) for the float format implied by its name. @end table @subsubheading Notes:: @node short-float-epsilon, arithmetic-error, most-positive-short-float, Numbers Dictionary @subsection short-float-epsilon, short-float-negative-epsilon, @subheading single-float-epsilon, single-float-negative-epsilon, @subheading double-float-epsilon, double-float-negative-epsilon, @subheading long-float-epsilon, long-float-negative-epsilon @flushright @i{[Constant Variable]} @end flushright @subsubheading Constant Value:: @i{implementation-dependent}. @subsubheading Description:: The value of each of the constants @b{short-float-epsilon}, @b{single-float-epsilon}, @b{double-float-epsilon}, and @b{long-float-epsilon} is the smallest positive @i{float} \epsilon of the given format, such that the following expression is @i{true} when evaluated: @t{(not (= (float 1 \epsilon) (+ (float 1 \epsilon) \epsilon)))\/} The value of each of the constants @b{short-float-negative-epsilon}, @b{single-float-negative-epsilon}, @b{double-float-negative-epsilon}, and @b{long-float-negative-epsilon} is the smallest positive @i{float} \epsilon of the given format, such that the following expression is @i{true} when evaluated: @t{(not (= (float 1 \epsilon) (- (float 1 \epsilon) \epsilon)))\/} @node arithmetic-error, arithmetic-error-operands, short-float-epsilon, Numbers Dictionary @subsection arithmetic-error [Condition Type] @subsubheading Class Precedence List:: @b{arithmetic-error}, @b{error}, @b{serious-condition}, @b{condition}, @b{t} @subsubheading Description:: The @i{type} @b{arithmetic-error} consists of error conditions that occur during arithmetic operations. The operation and operands are initialized with the initialization arguments named @t{:operation} and @t{:operands} to @b{make-condition}, and are @i{accessed} by the functions @b{arithmetic-error-operation} and @b{arithmetic-error-operands}. @subsubheading See Also:: @b{arithmetic-error-operation}, @ref{arithmetic-error-operands; arithmetic-error-operation} @node arithmetic-error-operands, division-by-zero, arithmetic-error, Numbers Dictionary @subsection arithmetic-error-operands, arithmetic-error-operation [Function] @code{arithmetic-error-operands} @i{condition} @result{} @i{operands} @code{arithmetic-error-operation} @i{condition} @result{} @i{operation} @subsubheading Arguments and Values:: @i{condition}---a @i{condition} of @i{type} @b{arithmetic-error}. @i{operands}---a @i{list}. @i{operation}---a @i{function designator}. @subsubheading Description:: @b{arithmetic-error-operands} returns a @i{list} of the operands which were used in the offending call to the operation that signaled the @i{condition}. @b{arithmetic-error-operation} returns a @i{list} of the offending operation in the offending call that signaled the @i{condition}. @subsubheading See Also:: @b{arithmetic-error}, {@ref{Conditions}} @subsubheading Notes:: @node division-by-zero, floating-point-invalid-operation, arithmetic-error-operands, Numbers Dictionary @subsection division-by-zero [Condition Type] @subsubheading Class Precedence List:: @b{division-by-zero}, @b{arithmetic-error}, @b{error}, @b{serious-condition}, @b{condition}, @b{t} @subsubheading Description:: The @i{type} @b{division-by-zero} consists of error conditions that occur because of division by zero. @node floating-point-invalid-operation, floating-point-inexact, division-by-zero, Numbers Dictionary @subsection floating-point-invalid-operation [Condition Type] @subsubheading Class Precedence List:: @b{floating-point-invalid-operation}, @b{arithmetic-error}, @b{error}, @b{serious-condition}, @b{condition}, @b{t} @subsubheading Description:: The @i{type} @b{floating-point-invalid-operation} consists of error conditions that occur because of certain floating point traps. It is @i{implementation-dependent} whether floating point traps occur, and whether or how they may be enabled or disabled. Therefore, conforming code may establish handlers for this condition, but must not depend on its being @i{signaled}. @node floating-point-inexact, floating-point-overflow, floating-point-invalid-operation, Numbers Dictionary @subsection floating-point-inexact [Condition Type] @subsubheading Class Precedence List:: @b{floating-point-inexact}, @b{arithmetic-error}, @b{error}, @b{serious-condition}, @b{condition}, @b{t} @subsubheading Description:: The @i{type} @b{floating-point-inexact} consists of error conditions that occur because of certain floating point traps. It is @i{implementation-dependent} whether floating point traps occur, and whether or how they may be enabled or disabled. Therefore, conforming code may establish handlers for this condition, but must not depend on its being @i{signaled}. @node floating-point-overflow, floating-point-underflow, floating-point-inexact, Numbers Dictionary @subsection floating-point-overflow [Condition Type] @subsubheading Class Precedence List:: @b{floating-point-overflow}, @b{arithmetic-error}, @b{error}, @b{serious-condition}, @b{condition}, @b{t} @subsubheading Description:: The @i{type} @b{floating-point-overflow} consists of error conditions that occur because of floating-point overflow. @node floating-point-underflow, , floating-point-overflow, Numbers Dictionary @subsection floating-point-underflow [Condition Type] @subsubheading Class Precedence List:: @b{floating-point-underflow}, @b{arithmetic-error}, @b{error}, @b{serious-condition}, @b{condition}, @b{t} @subsubheading Description:: The @i{type} @b{floating-point-underflow} consists of error conditions that occur because of floating-point underflow. @c end of including dict-numbers @c %**end of chapter