3
@node Numbers (Numbers), Characters, Packages, Top
11
@node Number Concepts, Numbers Dictionary, Numbers (Numbers), Numbers (Numbers)
12
@section Number Concepts
14
@c including concept-numbers
17
* Numeric Operations::
18
* Implementation-Dependent Numeric Constants::
19
* Rational Computations::
20
* Floating-point Computations::
21
* Complex Computations::
22
* Interval Designators::
23
* Random-State Operations::
26
@node Numeric Operations, Implementation-Dependent Numeric Constants, Number Concepts, Number Concepts
27
@subsection Numeric Operations
29
@r{Common Lisp} provides a large variety of operations related to @i{numbers}.
30
This section provides an overview of those operations by grouping them
31
into categories that emphasize some of the relationships among them.
33
Figure 12--1 shows @i{operators} relating to
34
arithmetic operations.
45
@w{ Figure 12--1: Operators relating to Arithmetic.}
50
Figure 12--2 shows @i{defined names} relating to
51
exponential, logarithmic, and trigonometric operations.
66
@w{ Figure 12--2: Defined names relating to Exponentials, Logarithms, and Trigonometry.}
71
Figure 12--3 shows @i{operators} relating to
72
numeric comparison and predication.
84
@w{ Figure 12--3: Operators for numeric comparison and predication.}
89
Figure 12--4 shows @i{defined names} relating to
90
numeric type manipulation and coercion.
95
@w{ ceiling float-radix rational }
96
@w{ complex float-sign rationalize }
97
@w{ decode-float floor realpart }
98
@w{ denominator fround rem }
99
@w{ fceiling ftruncate round }
100
@w{ ffloor imagpart scale-float }
101
@w{ float integer-decode-float truncate }
102
@w{ float-digits mod }
103
@w{ float-precision numerator }
106
@w{ Figure 12--4: Defined names relating to numeric type manipulation and coercion.}
112
* Associativity and Commutativity in Numeric Operations::
113
* Examples of Associativity and Commutativity in Numeric Operations::
114
* Contagion in Numeric Operations::
115
* Viewing Integers as Bits and Bytes::
116
* Logical Operations on Integers::
117
* Byte Operations on Integers::
120
@node Associativity and Commutativity in Numeric Operations, Examples of Associativity and Commutativity in Numeric Operations, Numeric Operations, Numeric Operations
121
@subsubsection Associativity and Commutativity in Numeric Operations
123
For functions that are mathematically associative (and possibly commutative),
124
a @i{conforming implementation} may process the @i{arguments} in any manner
125
consistent with associative (and possibly commutative) rearrangement. This does not
126
affect the order in which the @i{argument} @i{forms} are @i{evaluated};
127
for a discussion of evaluation order, see @ref{Function Forms}.
128
What is unspecified is only the order in which the @i{parameter} @i{values}
129
are processed. This implies that @i{implementations} may differ in which
130
automatic @i{coercions} are applied; see @ref{Contagion in Numeric Operations}.
132
A @i{conforming program} can control the order of processing explicitly by
133
separating the operations into separate (possibly nested) @i{function forms},
134
or by writing explicit calls to @i{functions} that perform coercions.
136
@node Examples of Associativity and Commutativity in Numeric Operations, Contagion in Numeric Operations, Associativity and Commutativity in Numeric Operations, Numeric Operations
137
@subsubsection Examples of Associativity and Commutativity in Numeric Operations
139
Consider the following expression, in which we assume that @t{1.0} and
140
@t{1.0e-15} both denote @i{single floats}:
143
(+ 1/3 2/3 1.0d0 1.0 1.0e-15)
146
One @i{conforming implementation} might
147
process the @i{arguments} from left to right,
148
first adding @t{1/3} and @t{2/3} to get @t{1},
149
then converting that to a @i{double float}
150
for combination with @t{1.0d0},
151
then successively converting and adding @t{1.0} and @t{1.0e-15}.
153
Another @i{conforming implementation} might process the @i{arguments} from
154
right to left, first performing a @i{single float} addition of @t{1.0} and
155
@t{1.0e-15} (perhaps losing accuracy in the process), then converting the sum to
156
a @i{double float} and adding @t{1.0d0}, then converting @t{2/3} to a
157
@i{double float} and adding it, and then converting @t{1/3} and adding that.
159
A third @i{conforming implementation} might first scan all the @i{arguments},
160
process all the @i{rationals} first to keep that part of the computation exact,
161
then find an @i{argument} of the largest floating-point format among all the
162
@i{arguments} and add that, and then add in all other @i{arguments}, converting
163
each in turn (all in a perhaps misguided attempt to make the computation as accurate
166
In any case, all three strategies are legitimate.
168
A @i{conforming program} could control the order by writing, for example,
171
(+ (+ 1/3 2/3) (+ 1.0d0 1.0e-15) 1.0)
174
@node Contagion in Numeric Operations, Viewing Integers as Bits and Bytes, Examples of Associativity and Commutativity in Numeric Operations, Numeric Operations
175
@subsubsection Contagion in Numeric Operations
177
For information about the contagion rules for implicit coercions of @i{arguments}
178
in numeric operations, see
179
@ref{Rule of Float Precision Contagion},
180
@ref{Rule of Float and Rational Contagion},
181
and @ref{Rule of Complex Contagion}.
183
@node Viewing Integers as Bits and Bytes, Logical Operations on Integers, Contagion in Numeric Operations, Numeric Operations
184
@subsubsection Viewing Integers as Bits and Bytes
186
@node Logical Operations on Integers, Byte Operations on Integers, Viewing Integers as Bits and Bytes, Numeric Operations
187
@subsubsection Logical Operations on Integers
189
Logical operations require @i{integers} as arguments;
190
an error of @i{type} @b{type-error} should be signaled
191
if an argument is supplied that is not an @i{integer}.
192
@i{Integer} arguments to logical operations are treated as if
193
they were represented in two's-complement notation.
195
Figure 12--5 shows @i{defined names} relating to
196
logical operations on numbers.
201
@w{ ash boole-ior logbitp }
202
@w{ boole boole-nand logcount }
203
@w{ boole-1 boole-nor logeqv }
204
@w{ boole-2 boole-orc1 logior }
205
@w{ boole-and boole-orc2 lognand }
206
@w{ boole-andc1 boole-set lognor }
207
@w{ boole-andc2 boole-xor lognot }
208
@w{ boole-c1 integer-length logorc1 }
209
@w{ boole-c2 logand logorc2 }
210
@w{ boole-clr logandc1 logtest }
211
@w{ boole-eqv logandc2 logxor }
214
@w{ Figure 12--5: Defined names relating to logical operations on numbers.}
219
@node Byte Operations on Integers, , Logical Operations on Integers, Numeric Operations
220
@subsubsection Byte Operations on Integers
222
The byte-manipulation @i{functions} use @i{objects}
223
called @i{byte specifiers} to designate the size and position
224
of a specific @i{byte} within an @i{integer}.
225
The representation of a @i{byte specifier} is @i{implementation-dependent};
226
it might or might not be a @i{number}.
227
The @i{function} @b{byte} will construct a @i{byte specifier},
228
which various other byte-manipulation @i{functions} will accept.
230
Figure 12--6 shows @i{defined names} relating to
231
manipulating @i{bytes} of @i{numbers}.
236
@w{ byte deposit-field ldb-test }
237
@w{ byte-position dpb mask-field }
241
@w{ Figure 12--6: Defined names relating to byte manipulation.}
246
@node Implementation-Dependent Numeric Constants, Rational Computations, Numeric Operations, Number Concepts
247
@subsection Implementation-Dependent Numeric Constants
249
Figure 12--7 shows @i{defined names} relating to
250
@i{implementation-dependent} details about @i{numbers}.
255
@w{ double-float-epsilon most-negative-fixnum }
256
@w{ double-float-negative-epsilon most-negative-long-float }
257
@w{ least-negative-double-float most-negative-short-float }
258
@w{ least-negative-long-float most-negative-single-float }
259
@w{ least-negative-short-float most-positive-double-float }
260
@w{ least-negative-single-float most-positive-fixnum }
261
@w{ least-positive-double-float most-positive-long-float }
262
@w{ least-positive-long-float most-positive-short-float }
263
@w{ least-positive-short-float most-positive-single-float }
264
@w{ least-positive-single-float short-float-epsilon }
265
@w{ long-float-epsilon short-float-negative-epsilon }
266
@w{ long-float-negative-epsilon single-float-epsilon }
267
@w{ most-negative-double-float single-float-negative-epsilon }
270
@w{ Figure 12--7: Defined names relating to implementation-dependent details about numbers.}
275
@node Rational Computations, Floating-point Computations, Implementation-Dependent Numeric Constants, Number Concepts
276
@subsection Rational Computations
278
The rules in this section apply to @i{rational} computations.
281
* Rule of Unbounded Rational Precision::
282
* Rule of Canonical Representation for Rationals::
283
* Rule of Float Substitutability::
286
@node Rule of Unbounded Rational Precision, Rule of Canonical Representation for Rationals, Rational Computations, Rational Computations
287
@subsubsection Rule of Unbounded Rational Precision
289
Rational computations cannot overflow in the usual sense
290
(though there may not be enough storage to represent a result),
291
since @i{integers} and @i{ratios} may in principle be of any magnitude.
293
@node Rule of Canonical Representation for Rationals, Rule of Float Substitutability, Rule of Unbounded Rational Precision, Rational Computations
294
@subsubsection Rule of Canonical Representation for Rationals
296
If any computation produces a result that is a mathematical ratio of two integers
297
such that the denominator evenly divides the numerator, then the result is converted
298
to the equivalent @i{integer}.
300
If the denominator does not evenly divide the numerator,
301
the canonical representation of a @i{rational} number is as the @i{ratio}
302
that numerator and that denominator, where the greatest common divisor of
303
the numerator and denominator is one, and where the denominator is positive
304
and greater than one.
306
When used as input (in the default syntax),
307
the notation @t{-0} always denotes the @i{integer} @t{0}.
308
A @i{conforming implementation} must not have a
309
representation of ``minus zero'' for @i{integers}
310
that is distinct from its representation of zero for @i{integers}.
311
However, such a distinction is possible for @i{floats};
312
see the @i{type} @b{float}.
314
@node Rule of Float Substitutability, , Rule of Canonical Representation for Rationals, Rational Computations
315
@subsubsection Rule of Float Substitutability
317
When the arguments to an irrational mathematical @i{function}
319
[Reviewer Note by Barmar: There should be a table of these functions.]
320
are all @i{rational} and the true mathematical result
321
is also (mathematically) rational, then unless otherwise noted
322
an implementation is free to return either an accurate
324
or a @i{single float} approximation.
325
If the arguments are all @i{rational}
326
but the result cannot be expressed
327
as a @i{rational} number, then a @i{single float}
328
approximation is always returned.
330
If the arguments to a mathematical @i{function} are all of type
331
@t{(or rational (complex rational))}
332
and the true mathematical result is
333
(mathematically) a complex number with rational real and imaginary
334
parts, then unless otherwise noted an implementation is free to return
335
either an accurate result of type @t{(or rational (complex rational))}
338
(permissible only if the imaginary part of the true mathematical
339
result is zero) or @t{(complex single-float)}. If the arguments are
340
all of type @t{(or rational (complex rational))}
341
but the result cannot be
342
expressed as a @i{rational} or @i{complex rational},
344
value will be of @i{type} @b{single-float}
345
(permissible only if the imaginary
346
part of the true mathematical result is zero) or @t{(complex single-float)}.
351
@w{ Function Sample Results }
352
@w{ @b{abs} @t{(abs #c(3 4)) @result{} 5 @i{or} 5.0} }
353
@w{ @b{acos} @t{(acos 1) @result{} 0 @i{or} 0.0} }
354
@w{ @b{acosh} @t{(acosh 1) @result{} 0 @i{or} 0.0} }
355
@w{ @b{asin} @t{(asin 0) @result{} 0 @i{or} 0.0} }
356
@w{ @b{asinh} @t{(asinh 0) @result{} 0 @i{or} 0.0} }
357
@w{ @b{atan} @t{(atan 0) @result{} 0 @i{or} 0.0} }
358
@w{ @b{atanh} @t{(atanh 0) @result{} 0 @i{or} 0.0} }
359
@w{ @b{cis} @t{(cis 0) @result{} #c(1 0) @i{or} #c(1.0 0.0)} }
360
@w{ @b{cos} @t{(cos 0) @result{} 1 @i{or} 1.0} }
361
@w{ @b{cosh} @t{(cosh 0) @result{} 1 @i{or} 1.0} }
362
@w{ @b{exp} @t{(exp 0) @result{} 1 @i{or} 1.0} }
363
@w{ @b{expt} @t{(expt 8 1/3) @result{} 2 @i{or} 2.0} }
364
@w{ @b{log} @t{(log 1) @result{} 0 @i{or} 0.0} }
365
@w{ @t{(log 8 2) @result{} 3 @i{or} 3.0} }
366
@w{ @b{phase} @t{(phase 7) @result{} 0 @i{or} 0.0} }
367
@w{ @b{signum} @t{(signum #c(3 4)) @result{} #c(3/5 4/5) @i{or} #c(0.6 0.8)} }
368
@w{ @b{sin} @t{(sin 0) @result{} 0 @i{or} 0.0} }
369
@w{ @b{sinh} @t{(sinh 0) @result{} 0 @i{or} 0.0} }
370
@w{ @b{sqrt} @t{(sqrt 4) @result{} 2 @i{or} 2.0} }
371
@w{ @t{(sqrt 9/16) @result{} 3/4 @i{or} 0.75} }
372
@w{ @b{tan} @t{(tan 0) @result{} 0 @i{or} 0.0} }
373
@w{ @b{tanh} @t{(tanh 0) @result{} 0 @i{or} 0.0} }
376
@w{ Figure 12--8: Functions Affected by Rule of Float Substitutability}
381
@node Floating-point Computations, Complex Computations, Rational Computations, Number Concepts
382
@subsection Floating-point Computations
384
The following rules apply to floating point computations.
387
* Rule of Float and Rational Contagion::
388
* Examples of Rule of Float and Rational Contagion::
389
* Rule of Float Approximation::
390
* Rule of Float Underflow and Overflow::
391
* Rule of Float Precision Contagion::
394
@node Rule of Float and Rational Contagion, Examples of Rule of Float and Rational Contagion, Floating-point Computations, Floating-point Computations
395
@subsubsection Rule of Float and Rational Contagion
397
When @i{rationals} and @i{floats} are combined by a numerical function,
398
the @i{rational} is first converted to a @i{float} of the same format.
399
For @i{functions} such as @b{+} that take more than two arguments,
400
it is permitted that part of the operation be carried out exactly using
401
@i{rationals} and the rest be done using floating-point arithmetic.
403
When @i{rationals} and @i{floats} are compared by a numerical function,
404
the @i{function} @b{rational} is effectively called to convert the @i{float}
405
to a @i{rational} and then an exact
406
comparison is performed. In the case of @i{complex} numbers,
407
the real and imaginary parts are effectively handled individually.
409
@node Examples of Rule of Float and Rational Contagion, Rule of Float Approximation, Rule of Float and Rational Contagion, Floating-point Computations
410
@subsubsection Examples of Rule of Float and Rational Contagion
413
;;;; Combining rationals with floats.
414
;;; This example assumes an implementation in which
415
;;; (float-radix 0.5) is 2 (as in IEEE) or 16 (as in IBM/360),
416
;;; or else some other implementation in which 1/2 has an exact
417
;;; representation in floating point.
418
(+ 1/2 0.5) @result{} 1.0
419
(- 1/2 0.5d0) @result{} 0.0d0
420
(+ 0.5 -0.5 1/2) @result{} 0.5
422
;;;; Comparing rationals with floats.
423
;;; This example assumes an implementation in which the default float
424
;;; format is IEEE single-float, IEEE double-float, or some other format
425
;;; in which 5/7 is rounded upwards by FLOAT.
426
(< 5/7 (float 5/7)) @result{} @i{true}
427
(< 5/7 (rational (float 5/7))) @result{} @i{true}
428
(< (float 5/7) (float 5/7)) @result{} @i{false}
431
@node Rule of Float Approximation, Rule of Float Underflow and Overflow, Examples of Rule of Float and Rational Contagion, Floating-point Computations
432
@subsubsection Rule of Float Approximation
434
Computations with @i{floats} are only approximate,
435
although they are described as if the results
436
were mathematically accurate.
437
Two mathematically identical
438
expressions may be computationally different because of errors
439
inherent in the floating-point approximation process.
440
The precision of a @i{float} is not necessarily
441
correlated with the accuracy of that number.
442
For instance, 3.142857142857142857 is a more precise approximation
443
to \pi than 3.14159, but the latter is more accurate.
444
The precision refers to the number of bits retained in the representation.
445
When an operation combines a @i{short float} with a
447
the result will be a @i{long float}.
448
@r{Common Lisp} functions assume that the accuracy of
449
arguments to them does not exceed their precision. Therefore
450
when two @i{small floats}
451
are combined, the result is a @i{small float}.
452
@r{Common Lisp} functions
453
never convert automatically from a larger size to a smaller one.
455
@node Rule of Float Underflow and Overflow, Rule of Float Precision Contagion, Rule of Float Approximation, Floating-point Computations
456
@subsubsection Rule of Float Underflow and Overflow
458
An error of @i{type} @b{floating-point-overflow}
459
or @b{floating-point-underflow} should be signaled if a
460
floating-point computation causes exponent overflow or underflow, respectively.
462
@node Rule of Float Precision Contagion, , Rule of Float Underflow and Overflow, Floating-point Computations
463
@subsubsection Rule of Float Precision Contagion
465
The result of a numerical function is a @i{float} of the
466
largest format among all the floating-point arguments to the @i{function}.
468
@node Complex Computations, Interval Designators, Floating-point Computations, Number Concepts
469
@subsection Complex Computations
471
The following rules apply to @i{complex} computations:
474
* Rule of Complex Substitutability::
475
* Rule of Complex Contagion::
476
* Rule of Canonical Representation for Complex Rationals::
477
* Examples of Rule of Canonical Representation for Complex Rationals::
478
* Principal Values and Branch Cuts::
481
@node Rule of Complex Substitutability, Rule of Complex Contagion, Complex Computations, Complex Computations
482
@subsubsection Rule of Complex Substitutability
484
Except during the execution of irrational and transcendental @i{functions},
485
no numerical @i{function} ever @i{yields} a @i{complex} unless
486
one or more of its @i{arguments} is a @i{complex}.
488
@node Rule of Complex Contagion, Rule of Canonical Representation for Complex Rationals, Rule of Complex Substitutability, Complex Computations
489
@subsubsection Rule of Complex Contagion
496
a @i{complex} are both part of a computation,
501
is first converted to a @i{complex} by providing an imaginary part of @t{0}.
503
@node Rule of Canonical Representation for Complex Rationals, Examples of Rule of Canonical Representation for Complex Rationals, Rule of Complex Contagion, Complex Computations
504
@subsubsection Rule of Canonical Representation for Complex Rationals
506
If the result of any computation would be a @i{complex}
507
number whose real part is of @i{type} @b{rational} and whose imaginary
508
part is zero, the result is converted to the @i{rational}
509
which is the real part.
510
This rule does not apply to @i{complex} numbers whose parts
512
For example, @t{#C(5 0)} and @t{5} are not @i{different} @i{objects} in @r{Common Lisp}
513
(they are always the @i{same} under @b{eql});
514
@t{#C(5.0 0.0)} and @t{5.0} are always @i{different} @i{objects} in @r{Common Lisp}
515
(they are never the @i{same} under @b{eql},
516
although they are the @i{same} under @b{equalp} and @b{=}).
518
@node Examples of Rule of Canonical Representation for Complex Rationals, Principal Values and Branch Cuts, Rule of Canonical Representation for Complex Rationals, Complex Computations
519
@subsubsection Examples of Rule of Canonical Representation for Complex Rationals
522
#c(1.0 1.0) @result{} #C(1.0 1.0)
523
#c(0.0 0.0) @result{} #C(0.0 0.0)
524
#c(1.0 1) @result{} #C(1.0 1.0)
525
#c(0.0 0) @result{} #C(0.0 0.0)
526
#c(1 1) @result{} #C(1 1)
528
(typep #c(1 1) '(complex (eql 1))) @result{} @i{true}
529
(typep #c(0 0) '(complex (eql 0))) @result{} @i{false}
532
@node Principal Values and Branch Cuts, , Examples of Rule of Canonical Representation for Complex Rationals, Complex Computations
533
@subsubsection Principal Values and Branch Cuts
535
Many of the irrational and transcendental functions are multiply defined
536
in the complex domain; for example, there are in general an infinite
537
number of complex values for the logarithm function. In each such
538
case, a @i{principal} @i{value} must be chosen for the function to return.
539
In general, such values cannot be chosen so as to make the range
540
continuous; lines in the domain
541
called branch cuts must be defined, which in turn
542
define the discontinuities in the range.
543
@r{Common Lisp} defines the branch cuts, @i{principal} @i{values}, and boundary
544
conditions for the complex functions following ``Principal Values and Branch Cuts in Complex APL.'' The branch
545
cut rules that apply to each function are located with the description of
549
the identities that are obeyed
550
throughout the applicable portion of the complex domain, even on
556
@w{ sin i z = i sinh z sinh i z = i sin z arctan i z = i arctanh z }
557
@w{ cos i z = cosh z cosh i z = cos z arcsinh i z = i arcsin z }
558
@w{ tan i z = i tanh z arcsin i z = i arcsinh z arctanh i z = i arctan z }
561
@w{ Figure 12--9: Trigonometric Identities for Complex Domain }
566
The quadrant numbers referred to in the discussions of branch cuts are as illustrated
577
______________________________________ Real Axis
589
@w{ Figure 12--9: Quadrant Numbering for Branch Cuts}
591
@node Interval Designators, Random-State Operations, Complex Computations, Number Concepts
592
@subsection Interval Designators
594
The @i{compound type specifier} form of the numeric @i{type specifiers}
595
in Figure 12--10 permit the user to specify an interval on the real number line
596
which describe a @i{subtype} of the @i{type} which would be described by the
597
corresponding @i{atomic type specifier}. A @i{subtype} of some @i{type}
598
@i{T} is specified using an ordered pair of @i{objects} called
599
@i{interval designators} for @i{type} @i{T}.
601
The first of the two @i{interval designators} for @i{type} @i{T} can be
602
any of the following:
606
@item a number @i{N} of @i{type} @i{T}
607
This denotes a lower inclusive bound of @i{N}. That is, @i{elements}
608
of the @i{subtype} of @i{T} will be greater than or equal to @i{N}.
610
@item a @i{singleton} @i{list} whose @i{element} is
611
a number @i{M} of @i{type} @i{T}
612
This denotes a lower exclusive bound of @i{M}. That is, @i{elements}
613
of the @i{subtype} of @i{T} will be greater than @i{M}.
615
@item the symbol @b{*}
616
This denotes the absence of a lower bound on the interval.
620
The second of the two @i{interval designators} for @i{type} @i{T} can be
621
any of the following:
625
@item a number @i{N} of @i{type} @i{T}
626
This denotes an upper inclusive bound of @i{N}. That is, @i{elements}
627
of the @i{subtype} of @i{T} will be less than or equal to @i{N}.
629
@item a @i{singleton} @i{list} whose @i{element} is
630
a number @i{M} of @i{type} @i{T}
631
This denotes an upper exclusive bound of @i{M}. That is, @i{elements}
632
of the @i{subtype} of @i{T} will be less than @i{M}.
634
@item the symbol @b{*}
635
This denotes the absence of an upper bound on the interval.
639
@node Random-State Operations, , Interval Designators, Number Concepts
640
@subsection Random-State Operations
642
Figure 12--10 lists some @i{defined names} that are applicable to @i{random states}.
647
@w{ *random-state* random }
648
@w{ make-random-state random-state-p }
651
@w{ Figure 12--10: Random-state defined names}
656
@c end of including concept-numbers
658
@node Numbers Dictionary, , Number Concepts, Numbers (Numbers)
659
@section Numbers Dictionary
661
@c including dict-numbers
665
* complex (System Class)::
667
* float (System Class)::
669
* rational (System Class)::
674
* mod (System Class)::
675
* bit (System Class)::
703
* make-random-state::
714
* upgraded-complex-part-type::
717
* rational (Function)::
735
* most-positive-fixnum::
739
* most-positive-short-float::
740
* short-float-epsilon::
742
* arithmetic-error-operands::
744
* floating-point-invalid-operation::
745
* floating-point-inexact::
746
* floating-point-overflow::
747
* floating-point-underflow::
750
@node number, complex (System Class), Numbers Dictionary, Numbers Dictionary
751
@subsection number [System Class]
753
@subsubheading Class Precedence List::
757
@subsubheading Description::
759
The @i{type} @b{number} contains @i{objects} which represent
760
mathematical numbers.
762
The @i{types} @b{real} and @b{complex} are @i{disjoint}
763
@i{subtypes} of @b{number}.
765
The @i{function} @b{=} tests for numerical equality.
766
The @i{function} @b{eql}, when its arguments are both @i{numbers},
767
tests that they have both the same @i{type} and numerical value.
768
Two @i{numbers} that are the @i{same} under @b{eql} or @b{=}
769
are not necessarily the @i{same} under @b{eq}.
771
@subsubheading Notes::
773
@r{Common Lisp} differs from mathematics on some naming issues. In mathematics,
774
the set of real numbers is traditionally described as a subset of the
775
complex numbers, but in @r{Common Lisp}, the @i{type} @b{real} and the @i{type} @b{complex} are
776
disjoint. The @r{Common Lisp} type which includes all mathematical complex
777
numbers is called @b{number}. The reasons for these differences
778
include historical precedent, compatibility with most other popular
779
computer languages, and various issues of time and space efficiency.
781
@node complex (System Class), real, number, Numbers Dictionary
782
@subsection complex [System Class]
784
@subsubheading Class Precedence List::
789
@subsubheading Description::
791
The @i{type} @b{complex} includes all mathematical complex numbers
792
other than those included in the @i{type} @b{rational}.
795
in Cartesian form with a
796
real part and an imaginary part, each of which is a @i{real}.
797
The real part and imaginary part are either both
798
@i{rational} or both of the same @i{float} @i{type}.
799
The imaginary part can be a @i{float} zero, but can never
800
be a @i{rational} zero, for such a number is always represented
801
by @r{Common Lisp} as a @i{rational} rather than a @i{complex}.
803
@subsubheading Compound Type Specifier Kind::
807
@subsubheading Compound Type Specifier Syntax::
809
(@code{complex}@{@i{@t{[}typespec | @b{*}@t{]}}@})
811
@subsubheading Compound Type Specifier Arguments::
813
@i{typespec}---a @i{type specifier} that denotes a @i{subtype} of @i{type} @b{real}.
815
@subsubheading Compound Type Specifier Description::
817
[Editorial Note by KMP: If you ask me, this definition is a complete mess. Looking at
818
issue ARRAY-TYPE-ELEMENT-TYPE-SEMANTICS:UNIFY-UPGRADING does not help me figure
819
it out, either. Anyone got any suggestions?]
821
Every element of this @i{type} is a @i{complex} whose
822
real part and imaginary part are each of type
824
@t{(upgraded-complex-part-type @i{typespec})}.
826
This @i{type} encompasses those @i{complexes}
827
that can result by giving numbers of @i{type} @i{typespec}
830
@t{(complex @i{type-specifier})}
831
refers to all @i{complexes} that can result from giving
832
@i{numbers} of @i{type} @i{type-specifier} to the @i{function} @b{complex},
833
plus all other @i{complexes} of the same specialized representation.
835
@subsubheading See Also::
837
@ref{Rule of Canonical Representation for Complex Rationals},
838
@ref{Constructing Numbers from Tokens},
839
@ref{Printing Complexes}
841
@subsubheading Notes::
843
The input syntax for a @i{complex} with real part r and
844
imaginary part i is @t{#C(r i)}.
845
For further details, see @ref{Standard Macro Characters}.
847
For every @i{float}, n, there is a @i{complex}
848
which represents the same mathematical number
849
and which can be obtained by @t{(COERCE n 'COMPLEX)}.
851
@node real, float (System Class), complex (System Class), Numbers Dictionary
852
@subsection real [System Class]
854
@subsubheading Class Precedence List::
859
@subsubheading Description::
861
The @i{type} @b{real} includes all @i{numbers} that
862
represent mathematical real numbers, though there are mathematical real
863
numbers (@i{e.g.}, irrational numbers) that do not have an exact representation
864
in @r{Common Lisp}. Only @i{reals} can be ordered using the
865
@b{<}, @b{>}, @b{<=}, and @b{>=} functions.
867
The @i{types} @b{rational} and @b{float} are @i{disjoint}
868
@i{subtypes} of @i{type} @b{real}.
870
@subsubheading Compound Type Specifier Kind::
874
@subsubheading Compound Type Specifier Syntax::
876
(@code{real}@{@i{@t{[}lower-limit @r{[}upper-limit@r{]}@t{]}}@})
878
@subsubheading Compound Type Specifier Arguments::
880
@i{lower-limit}, @i{upper-limit}---@i{interval designators}
881
for @i{type} @b{real}.
882
The defaults for each of @i{lower-limit} and @i{upper-limit} is the @i{symbol} @b{*}.
884
@subsubheading Compound Type Specifier Description::
886
This denotes the @i{reals} on the interval described by
887
@i{lower-limit} and @i{upper-limit}.
889
@node float (System Class), short-float, real, Numbers Dictionary
890
@subsection float [System Class]
892
@subsubheading Class Precedence List::
900
@subsubheading Description::
903
is a mathematical rational (but @i{not} a @r{Common Lisp} @i{rational})
905
s\cdot f\cdot b^@r{e-p},
906
where s is +1 or -1, the @i{sign};
908
greater than~1, the @i{base} or @i{radix} of the representation;
909
p is a positive @i{integer},
910
the @i{precision} (in base-b digits) of the @i{float};
911
f is a positive @i{integer}
912
between b^@r{p-1} and
913
b^p-1 (inclusive), the significand;
914
and e is an @i{integer}, the exponent.
915
The value of p and the range of~e
916
depends on the implementation and on the type of @i{float}
917
within that implementation. In addition, there is a floating-point zero;
918
depending on the implementation, there can also be a ``minus zero''. If there
919
is no minus zero, then 0.0 and~-0.0 are both interpreted as simply a
921
@t{(= 0.0 -0.0)} is always true.
922
If there is a minus zero, @t{(eql -0.0 0.0)} is @i{false},
923
otherwise it is @i{true}.
925
[Reviewer Note by Barmar: What about IEEE NaNs and infinities?]
927
[Reviewer Note by RWK: In the following, what is the ``ordering''? precision? range?
928
Can there be additional subtypes of float or does ``others'' in the
931
The @i{types} @b{short-float}, @b{single-float}, @b{double-float},
932
and @b{long-float} are @i{subtypes} of @i{type} @b{float}. Any two of them must be
933
either @i{disjoint} @i{types} or the @i{same} @i{type};
934
if the @i{same} @i{type}, then any other @i{types} between them in the
935
above ordering must also be the @i{same} @i{type}. For example,
936
if the @i{type} @b{single-float} and the @i{type} @b{long-float} are the @i{same} @i{type},
937
then the @i{type} @b{double-float} must be the @i{same} @i{type} also.
939
@subsubheading Compound Type Specifier Kind::
943
@subsubheading Compound Type Specifier Syntax::
945
(@code{float}@{@i{@t{[}lower-limit @r{[}upper-limit@r{]}@t{]}}@})
947
@subsubheading Compound Type Specifier Arguments::
949
@i{lower-limit}, @i{upper-limit}---@i{interval designators}
950
for @i{type} @b{float}.
951
The defaults for each of @i{lower-limit} and @i{upper-limit} is the @i{symbol} @b{*}.
953
@subsubheading Compound Type Specifier Description::
955
This denotes the @i{floats} on the interval described by
956
@i{lower-limit} and @i{upper-limit}.
958
@subsubheading See Also::
961
@ref{Constructing Numbers from Tokens},
962
@ref{Printing Floats}
964
@subsubheading Notes::
966
Note that all mathematical integers are representable not only as
967
@r{Common Lisp} @i{reals}, but also as @i{complex floats}. For example,
968
possible representations of the mathematical number 1
969
include the @i{integer} @t{1},
970
the @i{float} @t{1.0},
971
or the @i{complex} @t{#C(1.0 0.0)}.
973
@node short-float, rational (System Class), float (System Class), Numbers Dictionary
974
@subsection short-float, single-float, double-float, long-float [Type]
976
@subsubheading Supertypes::
1014
@subsubheading Description::
1016
For the four defined @i{subtypes} of @i{type} @b{float}, it is true that
1017
intermediate between the @i{type} @b{short-float} and the @i{type} @b{long-float} are
1018
the @i{type} @b{single-float} and the @i{type} @b{double-float}.
1019
The precise definition of these categories is
1020
@i{implementation-defined}.
1021
The precision (measured in ``bits'', computed as p\log_2b)
1022
and the exponent size (also measured in ``bits,'' computed as
1023
\log_2(n+1), where n is the maximum exponent value) is recommended
1024
to be at least as great
1025
as the values in Figure 12--11.
1026
Each of the defined @i{subtypes} of @i{type} @b{float} might or might not have a minus zero.
1031
@w{ @b{Format} @b{Minimum Precision} @b{Minimum Exponent Size} }
1032
@w{ __________________________________________________}
1033
@w{ Short 13 bits 5 bits }
1034
@w{ Single 24 bits 8 bits }
1035
@w{ Double 50 bits 8 bits }
1036
@w{ Long 50 bits 8 bits }
1039
@w{ Figure 12--11: Recommended Minimum Floating-Point Precision and Exponent Size}
1044
There can be fewer than four internal
1045
representations for @i{floats}.
1046
If there are fewer distinct representations, the following rules apply:
1050
If there is only one, it is
1051
the @i{type} @b{single-float}.
1052
In this representation, an @i{object} is simultaneously of @i{types}
1053
@b{single-float}, @b{double-float}, @b{short-float},
1056
Two internal representations can be arranged in either of the
1061
Two @i{types} are provided: @b{single-float} and
1062
@b{short-float}. An @i{object} is simultaneously
1063
of @i{types} @b{single-float}, @b{double-float}, and @b{long-float}.
1065
Two @i{types} are provided: @b{single-float} and
1066
@b{double-float}. An @i{object} is simultaneously of @i{types}
1067
@b{single-float} and @b{short-float}, or
1068
@b{double-float} and @b{long-float}.
1072
Three internal representations can be arranged in either
1073
of the following ways:
1077
Three @i{types} are provided: @b{short-float},
1078
@b{single-float}, and @b{double-float}.
1079
An @i{object} can simultaneously be of @i{type} @b{double-float}
1082
Three @i{types} are provided:
1083
@b{single-float}, @b{double-float},
1084
and @b{long-float}. An @i{object} can simultaneously
1085
be of @i{types} @b{single-float} and @b{short-float}.
1090
@subsubheading Compound Type Specifier Kind::
1094
@subsubheading Compound Type Specifier Syntax::
1096
(@code{short-float}@{@i{@t{[}short-lower-limit @r{[}short-upper-limit@r{]}@t{]}}@})
1097
(@code{single-float}@{@i{@t{[}single-lower-limit @r{[}single-upper-limit@r{]}@t{]}}@})
1098
(@code{double-float}@{@i{@t{[}double-lower-limit @r{[}double-upper-limit@r{]}@t{]}}@})
1099
(@code{long-float}@{@i{@t{[}long-lower-limit @r{[}long-upper-limit@r{]}@t{]}}@})
1101
@subsubheading Compound Type Specifier Arguments::
1103
@i{short-lower-limit}, @i{short-upper-limit}---@i{interval designators}
1104
for @i{type} @b{short-float}.
1105
The defaults for each of @i{lower-limit} and @i{upper-limit} is the @i{symbol} @b{*}.
1107
@i{single-lower-limit}, @i{single-upper-limit}---@i{interval designators}
1108
for @i{type} @b{single-float}.
1109
The defaults for each of @i{lower-limit} and @i{upper-limit} is the @i{symbol} @b{*}.
1111
@i{double-lower-limit}, @i{double-upper-limit}---@i{interval designators}
1112
for @i{type} @b{double-float}.
1113
The defaults for each of @i{lower-limit} and @i{upper-limit} is the @i{symbol} @b{*}.
1115
@i{long-lower-limit}, @i{long-upper-limit}---@i{interval designators}
1116
for @i{type} @b{long-float}.
1117
The defaults for each of @i{lower-limit} and @i{upper-limit} is the @i{symbol} @b{*}.
1119
@subsubheading Compound Type Specifier Description::
1121
Each of these denotes the set of @i{floats} of the indicated @i{type}
1122
that are on the interval specified by the @i{interval designators}.
1124
@node rational (System Class), ratio, short-float, Numbers Dictionary
1125
@subsection rational [System Class]
1127
@subsubheading Class Precedence List::
1135
@subsubheading Description::
1137
The canonical representation of a @i{rational}
1138
is as an @i{integer} if its value is integral,
1139
and otherwise as a @i{ratio}.
1141
The @i{types} @b{integer} and @b{ratio}
1142
are @i{disjoint} @i{subtypes} of @i{type} @b{rational}.
1144
@subsubheading Compound Type Specifier Kind::
1148
@subsubheading Compound Type Specifier Syntax::
1150
(@code{rational}@{@i{@t{[}lower-limit @r{[}upper-limit@r{]}@t{]}}@})
1152
@subsubheading Compound Type Specifier Arguments::
1154
@i{lower-limit}, @i{upper-limit}---@i{interval designators}
1155
for @i{type} @b{rational}.
1156
The defaults for each of @i{lower-limit} and @i{upper-limit} is the @i{symbol} @b{*}.
1158
@subsubheading Compound Type Specifier Description::
1160
This denotes the @i{rationals} on the interval described by
1161
@i{lower-limit} and @i{upper-limit}.
1163
@node ratio, integer, rational (System Class), Numbers Dictionary
1164
@subsection ratio [System Class]
1166
@subsubheading Class Precedence List::
1175
@subsubheading Description::
1177
A @i{ratio} is a @i{number}
1178
representing the mathematical ratio of two non-zero integers,
1179
the numerator and denominator,
1180
whose greatest common divisor is one,
1181
and of which the denominator is positive and greater than one.
1183
@subsubheading See Also::
1186
@ref{Constructing Numbers from Tokens},
1187
@ref{Printing Ratios}
1189
@node integer, signed-byte, ratio, Numbers Dictionary
1190
@subsection integer [System Class]
1192
@subsubheading Class Precedence List::
1201
@subsubheading Description::
1203
An @i{integer} is a mathematical integer. There is no limit on the
1204
magnitude of an @i{integer}.
1206
The @i{types} @b{fixnum} and @b{bignum}
1207
form an @i{exhaustive partition} of @i{type} @b{integer}.
1209
@subsubheading Compound Type Specifier Kind::
1213
@subsubheading Compound Type Specifier Syntax::
1215
(@code{integer}@{@i{@t{[}lower-limit @r{[}upper-limit@r{]}@t{]}}@})
1217
@subsubheading Compound Type Specifier Arguments::
1219
@i{lower-limit}, @i{upper-limit}---@i{interval designators}
1220
for @i{type} @b{integer}.
1221
The defaults for each of @i{lower-limit} and @i{upper-limit} is the @i{symbol} @b{*}.
1223
@subsubheading Compound Type Specifier Description::
1225
This denotes the @i{integers} on the interval described by
1226
@i{lower-limit} and @i{upper-limit}.
1228
@subsubheading See Also::
1231
@ref{Constructing Numbers from Tokens},
1232
@ref{Printing Integers}
1234
@subsubheading Notes::
1236
The @i{type} @t{(integer @i{lower} @i{upper})},
1237
where @i{lower} and @i{upper}
1238
are @b{most-negative-fixnum} and @b{most-positive-fixnum}, respectively,
1239
is also called @b{fixnum}.
1241
The @i{type} @t{(integer 0 1)} is also called @b{bit}.
1242
The @i{type} @t{(integer 0 *)} is also called @b{unsigned-byte}.
1244
@node signed-byte, unsigned-byte, integer, Numbers Dictionary
1245
@subsection signed-byte [Type]
1247
@subsubheading Supertypes::
1258
@subsubheading Description::
1260
The atomic @i{type specifier} @b{signed-byte} denotes the same
1261
type as is denoted by the @i{type specifier} @b{integer};
1262
however, the list forms of these two @i{type specifiers} have different semantics.
1264
@subsubheading Compound Type Specifier Kind::
1268
@subsubheading Compound Type Specifier Syntax::
1270
(@code{signed-byte}@{@i{@t{[}s | @b{*}@t{]}}@})
1272
@subsubheading Compound Type Specifier Arguments::
1274
@i{s}---a positive @i{integer}.
1276
@subsubheading Compound Type Specifier Description::
1278
This denotes the set of @i{integers} that can be represented
1279
in two's-complement form in a @i{byte} of @i{s} bits. This is
1280
equivalent to @t{(integer -2^@r{s-1} 2^@r{s-1}-1)}. The type
1281
@b{signed-byte} or the type @t{(signed-byte *)} is the same
1282
as the @i{type} @b{integer}.
1284
@node unsigned-byte, mod (System Class), signed-byte, Numbers Dictionary
1285
@subsection unsigned-byte [Type]
1287
@subsubheading Supertypes::
1299
@subsubheading Description::
1301
The atomic @i{type specifier} @b{unsigned-byte} denotes the same
1302
type as is denoted by the @i{type specifier} @t{(integer 0 *)}.
1304
@subsubheading Compound Type Specifier Kind::
1308
@subsubheading Compound Type Specifier Syntax::
1310
(@code{unsigned-byte}@{@i{@t{[}@i{s} | @b{*}@t{]}}@})
1312
@subsubheading Compound Type Specifier Arguments::
1314
@i{s}---a positive @i{integer}.
1316
@subsubheading Compound Type Specifier Description::
1318
This denotes the set of non-negative @i{integers} that can be
1319
represented in a byte of size @i{s} (bits).
1321
to @t{(mod @i{m})} for @i{m}=2^s, or
1322
to @t{(integer 0 @i{n})} for @i{n}=2^s-1.
1323
The @i{type} @b{unsigned-byte} or
1324
the type @t{(unsigned-byte *)} is the same as
1325
the type @t{(integer 0 *)}, the set of non-negative @i{integers}.
1327
@subsubheading Notes::
1329
The @i{type} @t{(unsigned-byte 1)} is also called @b{bit}.
1331
@node mod (System Class), bit (System Class), unsigned-byte, Numbers Dictionary
1332
@subsection mod [Type Specifier]
1334
@subsubheading Compound Type Specifier Kind::
1338
@subsubheading Compound Type Specifier Syntax::
1340
(@code{mod}@{@i{n}@})
1342
@subsubheading Compound Type Specifier Arguments::
1344
@i{n}---a positive @i{integer}.
1346
@subsubheading Compound Type Specifier Description::
1348
This denotes the set of non-negative @i{integers} less than @i{n}.
1349
This is equivalent to
1350
@t{(integer 0 (@i{n}))}
1352
@t{(integer 0 @i{m})},
1353
where @i{m}=@i{n}-1.
1355
The argument is required, and cannot be @b{*}.
1357
The symbol @b{mod} is not valid as a @i{type specifier}.
1359
@node bit (System Class), fixnum, mod (System Class), Numbers Dictionary
1360
@subsection bit [Type]
1362
@subsubheading Supertypes::
1375
@subsubheading Description::
1377
The @i{type} @b{bit} is equivalent to the @i{type} @t{(integer 0 1)}
1378
and @t{(unsigned-byte 1)}.
1380
@node fixnum, bignum, bit (System Class), Numbers Dictionary
1381
@subsection fixnum [Type]
1383
@subsubheading Supertypes::
1394
@subsubheading Description::
1396
A @i{fixnum} is an @i{integer} whose value is between
1397
@b{most-negative-fixnum} and @b{most-positive-fixnum} inclusive.
1398
Exactly which @i{integers} are @i{fixnums} is
1399
@i{implementation-defined}.
1401
The @i{type} @b{fixnum} is required to be a supertype of
1402
@t{(signed-byte 16)}.
1404
@node bignum, =, fixnum, Numbers Dictionary
1405
@subsection bignum [Type]
1407
@subsubheading Supertypes::
1418
@subsubheading Description::
1420
The @i{type} @b{bignum} is defined to be exactly @t{(and integer (not fixnum))}.
1422
@node =, max, bignum, Numbers Dictionary
1423
@subsection =, /=, <, >, <=, >= [Function]
1425
@code{=} @i{@r{&rest} numbers^+} @result{} @i{generalized-boolean}
1427
@code{/=} @i{@r{&rest} numbers^+} @result{} @i{generalized-boolean}
1429
@code{<} @i{@r{&rest} numbers^+} @result{} @i{generalized-boolean}
1431
@code{>} @i{@r{&rest} numbers^+} @result{} @i{generalized-boolean}
1433
@code{<=} @i{@r{&rest} numbers^+} @result{} @i{generalized-boolean}
1435
@code{>=} @i{@r{&rest} numbers^+} @result{} @i{generalized-boolean}
1437
@subsubheading Arguments and Values::
1439
@i{number}---for @b{<}, @b{>}, @b{<=}, @b{>=}: a @i{real};
1440
for @b{=}, @b{/=}: a @i{number}.
1442
@i{generalized-boolean}---a @i{generalized boolean}.
1444
@subsubheading Description::
1446
@b{=}, @b{/=}, @b{<}, @b{>}, @b{<=}, and @b{>=}
1447
perform arithmetic comparisons on their arguments as follows:
1452
The value of @b{=} is @i{true} if all @i{numbers} are the same in value;
1453
otherwise it is @i{false}.
1454
Two @i{complexes} are considered equal by @b{=}
1455
if their real and imaginary parts are equal according to @b{=}.
1458
The value of @b{/=} is @i{true} if no two @i{numbers} are the same in value;
1459
otherwise it is @i{false}.
1462
The value of @b{<} is @i{true} if the @i{numbers} are in monotonically increasing order;
1463
otherwise it is @i{false}.
1466
The value of @b{>} is @i{true} if the @i{numbers} are in monotonically decreasing order;
1467
otherwise it is @i{false}.
1470
The value of @b{<=} is @i{true} if the @i{numbers} are in monotonically
1471
nondecreasing order;
1472
otherwise it is @i{false}.
1475
The value of @b{>=} is @i{true} if the @i{numbers} are in monotonically
1476
nonincreasing order;
1477
otherwise it is @i{false}.
1480
@b{=}, @b{/=}, @b{<}, @b{>}, @b{<=}, and @b{>=}
1481
perform necessary type conversions.
1483
@subsubheading Examples::
1485
The uses of these functions are illustrated in Figure 12--12.
1490
@w{ @t{(= 3 3)} is @i{true}. @t{(/= 3 3)} is @i{false}. }
1491
@w{ @t{(= 3 5)} is @i{false}. @t{(/= 3 5)} is @i{true}. }
1492
@w{ @t{(= 3 3 3 3)} is @i{true}. @t{(/= 3 3 3 3)} is @i{false}. }
1493
@w{ @t{(= 3 3 5 3)} is @i{false}. @t{(/= 3 3 5 3)} is @i{false}. }
1494
@w{ @t{(= 3 6 5 2)} is @i{false}. @t{(/= 3 6 5 2)} is @i{true}. }
1495
@w{ @t{(= 3 2 3)} is @i{false}. @t{(/= 3 2 3)} is @i{false}. }
1496
@w{ @t{(< 3 5)} is @i{true}. @t{(<= 3 5)} is @i{true}. }
1497
@w{ @t{(< 3 -5)} is @i{false}. @t{(<= 3 -5)} is @i{false}. }
1498
@w{ @t{(< 3 3)} is @i{false}. @t{(<= 3 3)} is @i{true}. }
1499
@w{ @t{(< 0 3 4 6 7)} is @i{true}. @t{(<= 0 3 4 6 7)} is @i{true}. }
1500
@w{ @t{(< 0 3 4 4 6)} is @i{false}. @t{(<= 0 3 4 4 6)} is @i{true}. }
1501
@w{ @t{(> 4 3)} is @i{true}. @t{(>= 4 3)} is @i{true}. }
1502
@w{ @t{(> 4 3 2 1 0)} is @i{true}. @t{(>= 4 3 2 1 0)} is @i{true}. }
1503
@w{ @t{(> 4 3 3 2 0)} is @i{false}. @t{(>= 4 3 3 2 0)} is @i{true}. }
1504
@w{ @t{(> 4 3 1 2 0)} is @i{false}. @t{(>= 4 3 1 2 0)} is @i{false}. }
1505
@w{ @t{(= 3)} is @i{true}. @t{(/= 3)} is @i{true}. }
1506
@w{ @t{(< 3)} is @i{true}. @t{(<= 3)} is @i{true}. }
1507
@w{ @t{(= 3.0 #c(3.0 0.0))} is @i{true}. @t{(/= 3.0 #c(3.0 1.0))} is @i{true}. }
1508
@w{ @t{(= 3 3.0)} is @i{true}. @t{(= 3.0s0 3.0d0)} is @i{true}. }
1509
@w{ @t{(= 0.0 -0.0)} is @i{true}. @t{(= 5/2 2.5)} is @i{true}. }
1510
@w{ @t{(> 0.0 -0.0)} is @i{false}. @t{(= 0 -0.0)} is @i{true}. }
1511
@w{ @t{(<= 0 x 9)} is @i{true} if @t{x} is between @t{0} and @t{9}, inclusive}
1512
@w{ @t{(< 0.0 x 1.0)} is @i{true} if @t{x} is between @t{0.0} and @t{1.0}, exclusive}
1513
@w{ @t{(< -1 j (length v))} is @i{true} if @t{j} is a @i{valid array index} for a @i{vector} @t{v}}
1516
@w{ Figure 12--12: Uses of /=, =, <, >, <=, and >= }
1521
@subsubheading Exceptional Situations::
1523
Might signal @b{type-error} if some @i{argument} is not a @i{real}.
1524
Might signal @b{arithmetic-error} if otherwise unable to fulfill its contract.
1526
@subsubheading Notes::
1528
@b{=} differs from @b{eql} in that
1529
@t{(= 0.0 -0.0)} is always true,
1530
because @b{=} compares the mathematical values of its operands,
1531
whereas @b{eql} compares the representational values, so to speak.
1533
@node max, minusp, =, Numbers Dictionary
1534
@subsection max, min [Function]
1536
@code{max} @i{@r{&rest} reals^+} @result{} @i{max-real}
1538
@code{min} @i{@r{&rest} reals^+} @result{} @i{min-real}
1540
@subsubheading Arguments and Values::
1542
@i{real}---a @i{real}.
1544
@i{max-real}, @i{min-real}---a @i{real}.
1546
@subsubheading Description::
1548
@b{max} returns the @i{real} that is greatest (closest to positive infinity).
1549
@b{min} returns the @i{real} that is least (closest to negative infinity).
1552
the implementation has the choice of returning the largest
1553
argument as is or applying the rules of floating-point @i{contagion},
1554
taking all the arguments into consideration for @i{contagion} purposes.
1555
Also, if one or more of the arguments are @b{=}, then any one
1556
of them may be chosen as the value to return.
1557
For example, if the @i{reals} are a mixture of @i{rationals} and @i{floats},
1558
and the largest argument is a @i{rational},
1559
then the implementation is free to
1560
produce either that @i{rational}
1561
or its @i{float} approximation;
1562
if the largest argument is a
1563
@i{float} of a smaller format
1564
than the largest format of any @i{float} argument,
1565
then the implementation is free to
1566
return the argument in its given format or expanded to the larger format.
1567
Similar remarks apply to @b{min}
1568
(replacing ``largest argument'' by ``smallest argument'').
1570
@subsubheading Examples::
1575
(max 6 12) @result{} 12
1576
(min 6 12) @result{} 6
1577
(max -6 -12) @result{} -6
1578
(min -6 -12) @result{} -12
1579
(max 1 3 2 -7) @result{} 3
1580
(min 1 3 2 -7) @result{} -7
1581
(max -2 3 0 7) @result{} 7
1582
(min -2 3 0 7) @result{} -2
1583
(max 5.0 2) @result{} 5.0
1593
(max 1.0s0 7.0d0) @result{} 7.0d0
1596
@i{OR}@result{} 1.0d0
1597
(max 3 1 1.0s0 1.0d0)
1599
@i{OR}@result{} 3.0d0
1600
(min 3 1 1.0s0 1.0d0)
1602
@i{OR}@result{} 1.0s0
1603
@i{OR}@result{} 1.0d0
1606
@subsubheading Exceptional Situations::
1608
Should signal an error of @i{type} @b{type-error}
1609
if any @i{number} is not a @i{real}.
1611
@node minusp, zerop, max, Numbers Dictionary
1612
@subsection minusp, plusp [Function]
1614
@code{minusp} @i{real} @result{} @i{generalized-boolean}
1616
@code{plusp} @i{real} @result{} @i{generalized-boolean}
1618
@subsubheading Arguments and Values::
1620
@i{real}---a @i{real}.
1622
@i{generalized-boolean}---a @i{generalized boolean}.
1624
@subsubheading Description::
1626
@b{minusp} returns @i{true} if @i{real} is less than zero;
1627
otherwise, returns @i{false}.
1629
@b{plusp} returns @i{true} if @i{real} is greater than zero;
1630
otherwise, returns @i{false}.
1632
Regardless of whether an @i{implementation} provides distinct
1633
representations for positive and negative @i{float} zeros,
1634
@t{(minusp -0.0)} always returns @i{false}.
1636
@subsubheading Examples::
1638
(minusp -1) @result{} @i{true}
1639
(plusp 0) @result{} @i{false}
1640
(plusp least-positive-single-float) @result{} @i{true}
1643
@subsubheading Exceptional Situations::
1645
Should signal an error of @i{type} @b{type-error}
1646
if @i{real} is not a @i{real}.
1648
@node zerop, floor, minusp, Numbers Dictionary
1649
@subsection zerop [Function]
1651
@code{zerop} @i{number} @result{} @i{generalized-boolean}
1653
@subsubheading Pronunciation::
1655
pronounced 'z\=e (, )r\=o@r{}(, )p\=e
1657
@subsubheading Arguments and Values::
1659
@i{number}---a @i{number}.
1661
@i{generalized-boolean}---a @i{generalized boolean}.
1663
@subsubheading Description::
1665
Returns @i{true} if @i{number} is zero (@i{integer}, @i{float}, or @i{complex});
1666
otherwise, returns @i{false}.
1668
Regardless of whether an @i{implementation} provides distinct representations
1669
for positive and negative floating-point zeros, @t{(zerop -0.0)}
1670
always returns @i{true}.
1672
@subsubheading Examples::
1675
(zerop 0) @result{} @i{true}
1676
(zerop 1) @result{} @i{false}
1677
(zerop -0.0) @result{} @i{true}
1678
(zerop 0/100) @result{} @i{true}
1679
(zerop #c(0 0.0)) @result{} @i{true}
1682
@subsubheading Exceptional Situations::
1684
Should signal an error of @i{type} @b{type-error}
1685
if @i{number} is not a @i{number}.
1687
@subsubheading Notes::
1690
(zerop @i{number}) @equiv{} (= @i{number} 0)
1693
@node floor, sin, zerop, Numbers Dictionary
1694
@subsection floor, ffloor, ceiling, fceiling,
1695
@subheading truncate, ftruncate, round, fround
1700
@code{floor} @i{number @r{&optional} divisor} @result{} @i{quotient, remainder}
1702
@code{ffloor} @i{number @r{&optional} divisor} @result{} @i{quotient, remainder}
1704
@code{ceiling} @i{number @r{&optional} divisor} @result{} @i{quotient, remainder}
1706
@code{fceiling} @i{number @r{&optional} divisor} @result{} @i{quotient, remainder}
1708
@code{truncate} @i{number @r{&optional} divisor} @result{} @i{quotient, remainder}
1710
@code{ftruncate} @i{number @r{&optional} divisor} @result{} @i{quotient, remainder}
1712
@code{round} @i{number @r{&optional} divisor} @result{} @i{quotient, remainder}
1714
@code{fround} @i{number @r{&optional} divisor} @result{} @i{quotient, remainder}
1716
@subsubheading Arguments and Values::
1718
@i{number}---a @i{real}.
1720
@i{divisor}---a non-zero @i{real}.
1721
The default is the @i{integer} @t{1}.
1723
@i{quotient}---for @b{floor}, @b{ceiling},
1724
@b{truncate}, and @b{round}: an @i{integer};
1725
for @b{ffloor}, @b{fceiling},
1726
@b{ftruncate}, and @b{fround}: a @i{float}.
1728
@i{remainder}---a @i{real}.
1730
@subsubheading Description::
1732
These functions divide @i{number} by @i{divisor},
1733
returning a @i{quotient} and @i{remainder}, such that
1735
@i{quotient}@r{\cdot} @i{divisor}+@i{remainder}=@i{number}
1737
The @i{quotient} always represents a mathematical integer.
1738
When more than one mathematical integer might be possible
1739
(@i{i.e.}, when the remainder is not zero),
1740
the kind of rounding or truncation depends on the @i{operator}:
1744
@item @b{floor}, @b{ffloor}
1745
@b{floor} and @b{ffloor} produce a @i{quotient}
1746
that has been truncated toward negative infinity;
1747
that is, the @i{quotient} represents the largest mathematical integer
1748
that is not larger than the mathematical quotient.
1750
@item @b{ceiling}, @b{fceiling}
1751
@b{ceiling} and @b{fceiling} produce a @i{quotient}
1752
that has been truncated toward positive infinity;
1753
that is, the @i{quotient} represents the smallest mathematical integer
1754
that is not smaller than the mathematical result.
1756
@item @b{truncate}, @b{ftruncate}
1757
@b{truncate} and @b{ftruncate} produce a @i{quotient}
1758
that has been truncated towards zero;
1759
that is, the @i{quotient} represents the mathematical integer
1760
of the same sign as the mathematical quotient, and
1761
that has the greatest integral magnitude not greater than that of the mathematical quotient.
1763
@item @b{round}, @b{fround}
1764
@b{round} and @b{fround} produce a @i{quotient}
1765
that has been rounded to the nearest mathematical integer;
1766
if the mathematical quotient is exactly halfway between two integers,
1767
(that is, it has the form @i{integer}+1\over2),
1768
then the @i{quotient} has been rounded to the even (divisible by two) integer.
1772
All of these functions perform type conversion operations on @i{numbers}.
1775
is an @i{integer} if both @t{x} and @t{y} are @i{integers},
1776
is a @i{rational} if both @t{x} and @t{y} are @i{rationals}, and
1777
is a @i{float} if either @t{x} or @t{y} is a @i{float}.
1779
@b{ffloor}, @b{fceiling}, @b{ftruncate}, and @b{fround}
1780
handle arguments of different @i{types} in the following way:
1781
If @i{number} is a @i{float},
1782
and @i{divisor} is not a @i{float} of longer format,
1783
then the first result is a @i{float} of the same @i{type} as @i{number}.
1784
Otherwise, the first result is of the @i{type} determined by @i{contagion} rules;
1785
see @ref{Contagion in Numeric Operations}.
1787
@subsubheading Examples::
1790
(floor 3/2) @result{} 1, 1/2
1791
(ceiling 3 2) @result{} 2, -1
1792
(ffloor 3 2) @result{} 1.0, 1
1793
(ffloor -4.7) @result{} -5.0, 0.3
1794
(ffloor 3.5d0) @result{} 3.0d0, 0.5d0
1795
(fceiling 3/2) @result{} 2.0, -1/2
1796
(truncate 1) @result{} 1, 0
1797
(truncate .5) @result{} 0, 0.5
1798
(round .5) @result{} 0, 0.5
1799
(ftruncate -7 2) @result{} -3.0, -1
1800
(fround -7 2) @result{} -4.0, 1
1801
(dolist (n '(2.6 2.5 2.4 0.7 0.3 -0.3 -0.7 -2.4 -2.5 -2.6))
1802
(format t "~&~4,1@@F ~2,' D ~2,' D ~2,' D ~2,' D"
1803
n (floor n) (ceiling n) (truncate n) (round n)))
1804
@t{ |> } +2.6 2 3 2 3
1805
@t{ |> } +2.5 2 3 2 2
1806
@t{ |> } +2.4 2 3 2 2
1807
@t{ |> } +0.7 0 1 0 1
1808
@t{ |> } +0.3 0 1 0 0
1809
@t{ |> } -0.3 -1 0 0 0
1810
@t{ |> } -0.7 -1 0 0 -1
1811
@t{ |> } -2.4 -3 -2 -2 -2
1812
@t{ |> } -2.5 -3 -2 -2 -2
1813
@t{ |> } -2.6 -3 -2 -2 -3
1817
@subsubheading Notes::
1819
When only @i{number} is given, the two results are exact;
1820
the mathematical sum of the two results is always equal to the
1821
mathematical value of @i{number}.
1823
@t{(@i{function} @i{number} @i{divisor})}
1824
and @t{(@i{function} (/ @i{number} @i{divisor}))}
1825
(where @i{function} is any of one
1826
of @b{floor}, @b{ceiling}, @b{ffloor},
1827
@b{fceiling}, @b{truncate},
1828
@b{round}, @b{ftruncate}, and @b{fround})
1829
return the same first value, but
1830
they return different remainders as the second value. For example:
1833
(floor 5 2) @result{} 2, 1
1834
(floor (/ 5 2)) @result{} 2, 1/2
1837
If an effect is desired that is similar to @b{round},
1838
but that always rounds up or down (rather than toward the nearest even integer)
1839
if the mathematical quotient is exactly halfway between two integers,
1840
the programmer should consider a construction such as
1841
@t{(floor (+ x 1/2))}
1842
or @t{(ceiling (- x 1/2))}.
1844
@node sin, asin, floor, Numbers Dictionary
1845
@subsection sin, cos, tan [Function]
1847
@code{sin} @i{radians} @result{} @i{number}
1849
@code{cos} @i{radians} @result{} @i{number}
1851
@code{tan} @i{radians} @result{} @i{number}
1853
@subsubheading Arguments and Values::
1855
@i{radians}---a @i{number} given in radians.
1857
@i{number}---a @i{number}.
1859
@subsubheading Description::
1861
@b{sin}, @b{cos}, and @b{tan}
1862
return the sine, cosine, and tangent, respectively, of @i{radians}.
1864
@subsubheading Examples::
1867
(sin 0) @result{} 0.0
1868
(cos 0.7853982) @result{} 0.707107
1869
(tan #c(0 1)) @result{} #C(0.0 0.761594)
1872
@subsubheading Exceptional Situations::
1874
Should signal an error of @i{type} @b{type-error}
1875
if @i{radians} is not a @i{number}.
1876
Might signal @b{arithmetic-error}.
1878
@subsubheading See Also::
1884
@ref{Rule of Float Substitutability}
1886
@node asin, pi, sin, Numbers Dictionary
1887
@subsection asin, acos, atan [Function]
1889
@code{asin} @i{number} @result{} @i{radians}
1891
@code{acos} @i{number} @result{} @i{radians}
1893
@code{atan} @i{number1 @r{&optional} number2} @result{} @i{radians}
1895
@subsubheading Arguments and Values::
1897
@i{number}---a @i{number}.
1899
@i{number1}---a @i{number} if @i{number2} is not supplied,
1900
or a @i{real} if @i{number2} is supplied.
1902
@i{number2}---a @i{real}.
1904
@i{radians}---a @i{number} (of radians).
1906
@subsubheading Description::
1908
@b{asin}, @b{acos}, and @b{atan}
1909
compute the arc sine, arc cosine, and arc tangent respectively.
1911
The arc sine, arc cosine, and arc tangent (with only @i{number1} supplied)
1912
functions can be defined mathematically for
1913
@i{number} or @i{number1} specified as @i{x} as in Figure 12--13.
1918
@w{ Function Definition }
1919
@w{ Arc sine -i @t{log} (ix+ \sqrt@r{1-x^2} ) }
1920
@w{ Arc cosine (\pi/2) - @t{arcsin} x }
1921
@w{ Arc tangent -i @t{log} ((1+ix) \sqrt@r{1/(1+x^2)} ) }
1924
@w{ Figure 12--13: Mathematical definition of arc sine, arc cosine, and arc tangent}
1929
These formulae are mathematically correct, assuming
1930
completely accurate computation. They are not necessarily
1931
the simplest ones for real-valued computations.
1933
If both @i{number1} and @i{number2} are supplied
1934
for @b{atan}, the result is the arc tangent
1935
of @i{number1}/@i{number2}.
1936
The value of @b{atan} is always between
1937
-\pi (exclusive) and~\pi (inclusive)
1939
when minus zero is not supported.
1940
The range of the two-argument arc tangent when minus zero is supported
1953
-\pi/2 and~\pi/2 (both exclusive).
1954
@i{number1} can be a @i{complex} if @i{number2}
1955
is not supplied. If both are supplied, @i{number2} can be zero provided
1956
@i{number1} is not zero.
1958
[Reviewer Note by Barmar: Should add ``However, if the implementation distinguishes
1959
positive and negative zero, both may be signed zeros,
1960
and limits are used to define the result.'']
1962
The following definition for arc sine determines the range and
1965
@center @t{arcsin} z = -i @t{log} (iz+\sqrt@r{1-z^2}\Bigr)
1967
The branch cut for the arc sine function is in two pieces:
1968
one along the negative real axis to the left of~-1
1969
(inclusive), continuous with quadrant II, and one along the positive real
1970
axis to the right of~1 (inclusive), continuous with quadrant IV. The
1971
range is that strip of the complex plane containing numbers whose real
1972
part is between -\pi/2 and~\pi/2. A number with real
1973
part equal to -\pi/2 is in the range if and only if its imaginary
1974
part is non-negative; a number with real part equal to \pi/2 is in
1975
the range if and only if its imaginary part is non-positive.
1977
The following definition for arc cosine determines the range and
1980
@center @t{arccos} z = \pi\over2 - @t{arcsin} z
1982
or, which are equivalent,
1984
@center @t{arccos} z = -i @t{log} (z+i \sqrt@r{1-z^2}\Bigr)
1986
@center @t{arccos} z = @t{2 @t{log} (\sqrt@r{(1+z)/2} + i \sqrt@r{(1-z)/2})}\over@r{i}
1988
The branch cut for the arc cosine function is in two pieces:
1989
one along the negative real axis to the left of~-1
1990
(inclusive), continuous with quadrant II, and one along the positive real
1991
axis to the right of~1 (inclusive), continuous with quadrant IV.
1992
This is the same branch cut as for arc sine.
1993
The range is that strip of the complex plane containing numbers whose real
1994
part is between 0 and~\pi. A number with real
1995
part equal to 0 is in the range if and only if its imaginary
1996
part is non-negative; a number with real part equal to \pi is in
1997
the range if and only if its imaginary part is non-positive.
1999
The following definition for (one-argument) arc tangent determines the
2000
range and branch cuts:
2002
@center @t{arctan} z = @i{@i{@t{log} (1+iz) - @t{log} (1-iz)}\over@i{2i}}
2004
Beware of simplifying this formula; ``obvious'' simplifications are likely
2005
to alter the branch cuts or the values on the branch cuts incorrectly.
2006
The branch cut for the arc tangent function is in two pieces:
2007
one along the positive imaginary axis above i
2008
(exclusive), continuous with quadrant II, and one along the negative imaginary
2009
axis below -i (exclusive), continuous with quadrant IV.
2010
The points i and~-i are excluded from the domain.
2011
The range is that strip of the complex plane containing numbers whose real
2012
part is between -\pi/2 and~\pi/2. A number with real
2013
part equal to -\pi/2 is in the range if and only if its imaginary
2014
part is strictly positive; a number with real part equal to \pi/2 is in
2015
the range if and only if its imaginary part is strictly negative. Thus the range of
2016
arc tangent is identical to that of arc sine with the points
2017
-\pi/2 and~\pi/2 excluded.
2020
the signs of @i{number1} (indicated as @i{x})
2021
and @i{number2} (indicated as @i{y}) are used to derive quadrant
2022
information. Figure 12--14 details various special cases.
2024
The asterisk (*) indicates that the entry in the figure applies to
2025
implementations that support minus zero.
2030
@w{ to 1pc@r{}@i{y} Condition @i{x} Condition Cartesian locus Range of result }
2031
@w{ to 1pc@r{} y = 0 x > 0 Positive x-axis 0 }
2032
@w{ to 1pc* y = +0 x > 0 Positive x-axis +0 }
2033
@w{ to 1pc* y = -0 x > 0 Positive x-axis -0 }
2034
@w{ to 1pc@r{} y > 0 x > 0 Quadrant I 0 < result < \pi/2 }
2035
@w{ to 1pc@r{} y > 0 x = 0 Positive y-axis \pi/2 }
2036
@w{ to 1pc@r{} y > 0 x < 0 Quadrant II \pi/2 < result < \pi }
2037
@w{ to 1pc@r{} y = 0 x < 0 Negative x-axis \pi }
2038
@w{ to 1pc* y = +0 x < 0 Negative x-axis +\pi }
2039
@w{ to 1pc* y = -0 x < 0 Negative x-axis -\pi }
2040
@w{ to 1pc@r{} y < 0 x < 0 Quadrant III -\pi < result < -\pi/2 }
2041
@w{ to 1pc@r{} y < 0 x = 0 Negative y-axis -\pi/2 }
2042
@w{ to 1pc@r{} y < 0 x > 0 Quadrant IV -\pi/2 < result < 0 }
2043
@w{ to 1pc@r{} y = 0 x = 0 Origin undefined consequences }
2044
@w{ to 1pc* y = +0 x = +0 Origin +0 }
2045
@w{ to 1pc* y = -0 x = +0 Origin -0 }
2046
@w{ to 1pc* y = +0 x = -0 Origin +\pi }
2047
@w{ to 1pc* y = -0 x = -0 Origin -\pi }
2050
@w{ Figure 12--14: Quadrant information for arc tangent }
2055
@subsubheading Examples::
2058
(asin 0) @result{} 0.0
2059
(acos #c(0 1)) @result{} #C(1.5707963267948966 -0.8813735870195432)
2060
(/ (atan 1 (sqrt 3)) 6) @result{} 0.087266
2061
(atan #c(0 2)) @result{} #C(-1.5707964 0.54930615)
2064
@subsubheading Exceptional Situations::
2066
@b{acos} and @b{asin} should signal an error of @i{type} @b{type-error}
2067
if @i{number} is not a @i{number}.
2068
@b{atan} should signal @b{type-error} if
2069
one argument is supplied and that argument is not a @i{number},
2070
or if two arguments are supplied and both of those arguments are not @i{reals}.
2072
@b{acos}, @b{asin}, and @b{atan} might signal @b{arithmetic-error}.
2074
@subsubheading See Also::
2080
@ref{Rule of Float Substitutability}
2082
@subsubheading Notes::
2084
The result of either @b{asin} or @b{acos} can be a @i{complex}
2085
even if @i{number} is not a @i{complex}; this occurs when the
2086
absolute value of @i{number} is greater than one.
2088
@node pi, sinh, asin, Numbers Dictionary
2089
@subsection pi [Constant Variable]
2091
@subsubheading Value::
2093
an @i{implementation-dependent} @i{long float}.
2095
@subsubheading Description::
2097
The best @i{long float} approximation to the mathematical constant \pi.
2099
@subsubheading Examples::
2102
;; In each of the following computations, the precision depends
2103
;; on the implementation. Also, if `long float' is treated by
2104
;; the implementation as equivalent to some other float format
2105
;; (e.g., `double float') the exponent marker might be the marker
2106
;; for that equivalent (e.g., `D' instead of `L').
2107
pi @result{} 3.141592653589793L0
2108
(cos pi) @result{} -1.0L0
2110
(defun sin-of-degrees (degrees)
2111
(let ((x (if (floatp degrees) degrees (float degrees pi))))
2112
(sin (* x (/ (float pi x) 180)))))
2115
@subsubheading Notes::
2117
An approximation to \pi in some other precision can be obtained
2118
by writing @t{(float pi x)}, where @t{x} is a @i{float} of the
2119
desired precision, or by writing @t{(coerce pi @i{type})},
2120
where @i{type} is the desired type, such as @b{short-float}.
2122
@node sinh, *, pi, Numbers Dictionary
2123
@subsection sinh, cosh, tanh, asinh, acosh, atanh [Function]
2125
@code{sinh} @i{number} @result{} @i{result}
2127
@code{cosh} @i{number} @result{} @i{result}
2129
@code{tanh} @i{number} @result{} @i{result}
2131
@code{asinh} @i{number} @result{} @i{result}
2133
@code{acosh} @i{number} @result{} @i{result}
2135
@code{atanh} @i{number} @result{} @i{result}
2137
@subsubheading Arguments and Values::
2139
@i{number}---a @i{number}.
2141
@i{result}---a @i{number}.
2143
@subsubheading Description::
2145
These functions compute the hyperbolic sine, cosine, tangent,
2146
arc sine, arc cosine, and arc tangent functions,
2147
which are mathematically defined for an argument @i{x}
2148
as given in Figure 12--15.
2153
@w{ Function Definition }
2154
@w{ Hyperbolic sine (e^x-e^@i{-x})/2 }
2155
@w{ Hyperbolic cosine (e^x+e^@i{-x})/2 }
2156
@w{ Hyperbolic tangent (e^x-e^@i{-x})/(e^x+e^@i{-x}) }
2157
@w{ Hyperbolic arc sine @t{log} (x+\sqrt@i{1+x^2}) }
2158
@w{ Hyperbolic arc cosine 2 @t{log} (\sqrt@i{(x+1)/2} + \sqrt@i{(x-1)/2}) }
2159
@w{ Hyperbolic arc tangent (@t{log} (1+x) - @t{log} (1-x))/2 }
2162
@w{ Figure 12--15: Mathematical definitions for hyperbolic functions }
2167
The following definition for the inverse hyperbolic cosine
2168
determines the range and branch cuts:
2170
@center @t{arccosh} z = 2 @t{log} (\sqrt@i{(z+1)/2} + \sqrt@i{(z-1)/2}\Bigr).
2172
The branch cut for the inverse hyperbolic cosine function
2173
lies along the real axis to the left of~1 (inclusive), extending
2174
indefinitely along the negative real axis, continuous with quadrant II
2175
and (between 0 and~1) with quadrant I.
2176
The range is that half-strip of the complex plane containing numbers whose
2177
real part is non-negative and whose imaginary
2178
part is between -\pi (exclusive) and~\pi (inclusive).
2179
A number with real part zero is in the range
2180
if its imaginary part is between zero (inclusive) and~\pi (inclusive).
2182
The following definition for the inverse hyperbolic sine determines
2183
the range and branch cuts:
2185
@center @t{arcsinh} z = @t{log} (z+\sqrt@i{1+z^2}\Bigr).
2187
The branch cut for the inverse hyperbolic sine function is in two pieces:
2188
one along the positive imaginary axis above i
2189
(inclusive), continuous with quadrant I, and one along the negative imaginary
2190
axis below -i (inclusive), continuous with quadrant III.
2191
The range is that strip of the complex plane containing numbers whose imaginary
2192
part is between -\pi/2 and~\pi/2. A number with imaginary
2193
part equal to -\pi/2 is in the range if and only if its real
2194
part is non-positive; a number with imaginary part equal to \pi/2 is in
2195
the range if and only if its imaginary part is non-negative.
2197
The following definition for the inverse hyperbolic tangent
2198
determines the range and branch cuts:
2200
@center @t{arctanh} z = @i{@i{@t{log} (1+z) - @t{log} (1-z)}\over@r{2}}.
2204
@center i @t{arctan} z = @t{arctanh} iz.
2206
The branch cut for the inverse hyperbolic tangent function
2207
is in two pieces: one along the negative real axis to the left of
2208
-1 (inclusive), continuous with quadrant III, and one along
2209
the positive real axis to the right of~1 (inclusive), continuous with
2210
quadrant I. The points -1 and~1 are excluded from the
2212
The range is that strip of the complex plane containing
2213
numbers whose imaginary part is between -\pi/2 and
2214
\pi/2. A number with imaginary part equal to -\pi/2
2215
is in the range if and only if its real part is strictly negative; a number with
2216
imaginary part equal to \pi/2 is in the range if and only if its imaginary
2217
part is strictly positive.
2218
Thus the range of the inverse hyperbolic tangent function is identical to
2219
that of the inverse hyperbolic sine function with the points
2220
-\pi i/2 and~\pi i/2 excluded.
2222
@subsubheading Examples::
2225
(sinh 0) @result{} 0.0
2226
(cosh (complex 0 -1)) @result{} #C(0.540302 -0.0)
2229
@subsubheading Exceptional Situations::
2231
Should signal an error of @i{type} @b{type-error}
2232
if @i{number} is not a @i{number}.
2233
Might signal @b{arithmetic-error}.
2235
@subsubheading See Also::
2241
@ref{Rule of Float Substitutability}
2243
@subsubheading Notes::
2245
The result of @b{acosh} may be a @i{complex} even if @i{number}
2246
is not a @i{complex}; this occurs when @i{number} is less than one.
2247
Also, the result of @b{atanh} may be a @i{complex} even if @i{number}
2248
is not a @i{complex}; this occurs when the absolute value of @i{number}
2249
is greater than one.
2251
The branch cut formulae are mathematically correct, assuming
2252
completely accurate computation.
2253
Implementors should consult a good text on
2254
numerical analysis. The formulae given above are not necessarily
2255
the simplest ones for real-valued computations; they are chosen
2256
to define the branch cuts in desirable ways for the complex case.
2258
@node *, +, sinh, Numbers Dictionary
2259
@subsection * [Function]
2261
@code{*} @i{@r{&rest} numbers} @result{} @i{product}
2263
@subsubheading Arguments and Values::
2265
@i{number}---a @i{number}.
2267
@i{product}---a @i{number}.
2269
@subsubheading Description::
2271
Returns the product of @i{numbers},
2272
performing any necessary type conversions in the process.
2273
If no @i{numbers} are supplied, @t{1} is returned.
2275
@subsubheading Examples::
2279
(* 3 5) @result{} 15
2280
(* 1.0 #c(22 33) 55/98) @result{} #C(12.346938775510203 18.520408163265305)
2283
@subsubheading Exceptional Situations::
2285
Might signal @b{type-error} if some @i{argument} is not a @i{number}.
2286
Might signal @b{arithmetic-error}.
2288
@subsubheading See Also::
2290
@ref{Numeric Operations},
2291
@ref{Rational Computations},
2292
@ref{Floating-point Computations},
2293
@ref{Complex Computations}
2295
@node +, -, *, Numbers Dictionary
2296
@subsection + [Function]
2298
@code{+} @i{@r{&rest} numbers} @result{} @i{sum}
2300
@subsubheading Arguments and Values::
2302
@i{number}---a @i{number}.
2304
@i{sum}---a @i{number}.
2306
@subsubheading Description::
2308
Returns the sum of @i{numbers},
2309
performing any necessary type conversions in the process.
2310
If no @i{numbers} are supplied, @t{0} is returned.
2312
@subsubheading Examples::
2316
(+ 31/100 69/100) @result{} 1
2317
(+ 1/5 0.8) @result{} 1.0
2320
@subsubheading Exceptional Situations::
2322
Might signal @b{type-error} if some @i{argument} is not a @i{number}.
2323
Might signal @b{arithmetic-error}.
2325
@subsubheading See Also::
2327
@ref{Numeric Operations},
2328
@ref{Rational Computations},
2329
@ref{Floating-point Computations},
2330
@ref{Complex Computations}
2332
@node -, /, +, Numbers Dictionary
2333
@subsection - [Function]
2335
@code{-} @i{number} @result{} @i{negation}
2337
@code{-} @i{minuend @r{&rest} subtrahends^+} @result{} @i{difference}
2339
@subsubheading Arguments and Values::
2341
@i{number}, @i{minuend}, @i{subtrahend}---a @i{number}.
2343
@i{negation}, @i{difference}---a @i{number}.
2345
@subsubheading Description::
2347
The @i{function} @b{-} performs arithmetic subtraction and negation.
2349
If only one @i{number} is supplied,
2350
the negation of that @i{number} is returned.
2352
If more than one @i{argument} is given,
2353
it subtracts all of the @i{subtrahends} from the @i{minuend}
2354
and returns the result.
2356
The @i{function} @b{-} performs necessary type conversions.
2358
@subsubheading Examples::
2361
(- 55.55) @result{} -55.55
2362
(- #c(3 -5)) @result{} #C(-3 5)
2364
(eql (- 0.0) -0.0) @result{} @i{true}
2365
(- #c(100 45) #c(0 45)) @result{} 100
2366
(- 10 1 2 3 4) @result{} 0
2369
@subsubheading Exceptional Situations::
2371
Might signal @b{type-error} if some @i{argument} is not a @i{number}.
2372
Might signal @b{arithmetic-error}.
2374
@subsubheading See Also::
2376
@ref{Numeric Operations},
2377
@ref{Rational Computations},
2378
@ref{Floating-point Computations},
2379
@ref{Complex Computations}
2381
@node /, 1+, -, Numbers Dictionary
2382
@subsection / [Function]
2384
@code{/} @i{number} @result{} @i{reciprocal}
2386
@code{/} @i{numerator @r{&rest} denominators^+} @result{} @i{quotient}
2388
@subsubheading Arguments and Values::
2390
@i{number}, @i{denominator}---a non-zero @i{number}.
2392
@i{numerator}, @i{quotient}, @i{reciprocal}---a @i{number}.
2394
@subsubheading Description::
2396
The @i{function} @b{/} performs division or reciprocation.
2398
If no @i{denominators} are supplied,
2399
the @i{function} @b{/} returns the reciprocal of @i{number}.
2401
If at least one @i{denominator} is supplied,
2402
the @i{function} @b{/} divides the @i{numerator} by all of the @i{denominators}
2403
and returns the resulting @i{quotient}.
2405
If each @i{argument} is either an @i{integer} or a @i{ratio},
2406
and the result is not an @i{integer}, then it is a @i{ratio}.
2408
The @i{function} @b{/} performs necessary type conversions.
2410
If any @i{argument} is a @i{float} then
2411
the rules of floating-point contagion apply;
2412
see @ref{Floating-point Computations}.
2414
@subsubheading Examples::
2417
(/ 12 4) @result{} 3
2418
(/ 13 4) @result{} 13/4
2419
(/ -8) @result{} -1/8
2420
(/ 3 4 5) @result{} 3/20
2421
(/ 0.5) @result{} 2.0
2422
(/ 20 5) @result{} 4
2423
(/ 5 20) @result{} 1/4
2424
(/ 60 -2 3 5.0) @result{} -2.0
2425
(/ 2 #c(2 2)) @result{} #C(1/2 -1/2)
2428
@subsubheading Exceptional Situations::
2430
The consequences are unspecified if any @i{argument} other than the first is zero.
2431
If there is only one @i{argument}, the consequences are unspecified if it is zero.
2433
Might signal @b{type-error} if some @i{argument} is not a @i{number}.
2434
Might signal @b{division-by-zero} if division by zero is attempted.
2435
Might signal @b{arithmetic-error}.
2437
@subsubheading See Also::
2440
, @b{ceiling}, @b{truncate}, @b{round}
2442
@node 1+, abs, /, Numbers Dictionary
2443
@subsection 1+, 1- [Function]
2445
@code{1} @i{+} @result{} @i{number}
2447
@code{1} @i{-} @result{} @i{number}
2450
@subsubheading Arguments and Values::
2452
@i{number}---a @i{number}.
2454
@i{successor}, @i{predecessor}---a @i{number}.
2456
@subsubheading Description::
2458
@b{1+} returns a @i{number} that is one more than its argument @i{number}.
2459
@b{1-} returns a @i{number} that is one less than its argument @i{number}.
2461
@subsubheading Examples::
2464
(1+ 99) @result{} 100
2465
(1- 100) @result{} 99
2466
(1+ (complex 0.0)) @result{} #C(1.0 0.0)
2467
(1- 5/3) @result{} 2/3
2470
@subsubheading Exceptional Situations::
2472
Might signal @b{type-error} if its @i{argument} is not a @i{number}.
2473
Might signal @b{arithmetic-error}.
2475
@subsubheading See Also::
2480
@subsubheading Notes::
2483
(1+ @i{number}) @equiv{} (+ @i{number} 1)
2484
(1- @i{number}) @equiv{} (- @i{number} 1)
2487
Implementors are encouraged to make the performance of both the previous
2488
expressions be the same.
2490
@node abs, evenp, 1+, Numbers Dictionary
2491
@subsection abs [Function]
2493
@code{abs} @i{number} @result{} @i{absolute-value}
2495
@subsubheading Arguments and Values::
2497
@i{number}---a @i{number}.
2499
@i{absolute-value}---a non-negative @i{real}.
2501
@subsubheading Description::
2503
@b{abs} returns the absolute value of @i{number}.
2509
the result is of the same @i{type} as @i{number}.
2511
If @i{number} is a @i{complex},
2512
the result is a positive
2517
the same magnitude as @i{number}.
2518
The result can be a @i{float}
2520
[Reviewer Note by Barmar: Single-float.]
2521
even if @i{number}'s components are @i{rationals}
2522
and an exact rational result
2523
would have been possible.
2524
Thus the result of @t{(abs #c(3 4))} can be either @t{5} or @t{5.0},
2525
depending on the implementation.
2527
@subsubheading Examples::
2531
(abs 12/13) @result{} 12/13
2532
(abs -1.09) @result{} 1.09
2533
(abs #c(5.0 -5.0)) @result{} 7.071068
2534
(abs #c(5 5)) @result{} 7.071068
2535
(abs #c(3/5 4/5)) @result{} 1 or approximately 1.0
2536
(eql (abs -0.0) -0.0) @result{} @i{true}
2539
@subsubheading See Also::
2541
@ref{Rule of Float Substitutability}
2543
@subsubheading Notes::
2545
If @i{number} is a @i{complex},
2546
the result is equivalent to the following:
2548
@t{(sqrt (+ (expt (realpart @i{number}) 2) (expt (imagpart @i{number}) 2)))}
2550
An implementation should not use this formula directly
2551
for all @i{complexes}
2552
but should handle very large or very small components specially
2553
to avoid intermediate overflow or underflow.
2555
@node evenp, exp, abs, Numbers Dictionary
2556
@subsection evenp, oddp [Function]
2558
@code{evenp} @i{integer} @result{} @i{generalized-boolean}
2560
@code{oddp} @i{integer} @result{} @i{generalized-boolean}
2562
@subsubheading Arguments and Values::
2564
@i{integer}---an @i{integer}.
2566
@i{generalized-boolean}---a @i{generalized boolean}.
2568
@subsubheading Description::
2570
@b{evenp} returns @i{true} if @i{integer} is even (divisible by two);
2571
otherwise, returns @i{false}.
2573
@b{oddp} returns @i{true} if @i{integer} is odd (not divisible by two);
2574
otherwise, returns @i{false}.
2576
@subsubheading Examples::
2579
(evenp 0) @result{} @i{true}
2580
(oddp 10000000000000000000000) @result{} @i{false}
2581
(oddp -1) @result{} @i{true}
2584
@subsubheading Exceptional Situations::
2586
Should signal an error of @i{type} @b{type-error}
2587
if @i{integer} is not an @i{integer}.
2589
@subsubheading Notes::
2592
(evenp @i{integer}) @equiv{} (not (oddp @i{integer}))
2593
(oddp @i{integer}) @equiv{} (not (evenp @i{integer}))
2596
@node exp, gcd, evenp, Numbers Dictionary
2597
@subsection exp, expt [Function]
2599
@code{exp} @i{number} @result{} @i{result}
2601
@code{expt} @i{base-number power-number} @result{} @i{result}
2603
@subsubheading Arguments and Values::
2605
@i{number}---a @i{number}.
2607
@i{base-number}---a @i{number}.
2609
@i{power-number}---a @i{number}.
2611
@i{result}---a @i{number}.
2613
@subsubheading Description::
2615
@b{exp} and @b{expt} perform exponentiation.
2617
@b{exp} returns @i{e} raised to the power @i{number},
2618
where @i{e} is the base of the natural logarithms.
2619
@b{exp} has no branch cut.
2621
@b{expt} returns @i{base-number}
2622
raised to the power @i{power-number}.
2623
If the @i{base-number} is a @i{rational}
2624
and @i{power-number} is
2626
the calculation is exact and the result will be of @i{type} @b{rational};
2627
otherwise a floating-point approximation might result.
2629
For @b{expt} of a @i{complex rational} to an @i{integer} power,
2630
the calculation must be exact and the result is
2631
of type @t{(or rational (complex rational))}.
2633
The result of @b{expt} can be a @i{complex},
2634
even when neither argument is a @i{complex},
2635
if @i{base-number} is negative and @i{power-number}
2636
is not an @i{integer}.
2637
The result is always the @i{principal} @i{complex} @i{value}.
2638
For example, @t{(expt -8 1/3)} is not permitted to return @t{-2},
2639
even though @t{-2} is one of the cube roots of @t{-8}.
2640
The @i{principal} cube root is a @i{complex}
2641
approximately equal to @t{#C(1.0 1.73205)}, not @t{-2}.
2644
as @i{b^x = e^@i{x log b\/}}.
2645
This defines the @i{principal} @i{values} precisely. The range of
2646
@b{expt} is the entire complex plane. Regarded
2647
as a function of @i{x}, with @i{b} fixed, there is no branch cut.
2648
Regarded as a function of @i{b}, with @i{x} fixed, there is in general
2649
a branch cut along the negative real axis, continuous with quadrant II.
2650
The domain excludes the origin.
2651
By definition, 0^0=1. If @i{b}=0 and the real part of @i{x} is strictly
2653
@i{b^x}=0. For all other values of @i{x}, 0^@i{x}
2656
When @i{power-number} is an @i{integer} @t{0},
2657
then the result is always the value one in the @i{type}
2659
even if the @i{base-number} is zero (of any @i{type}). That is:
2662
(expt x 0) @equiv{} (coerce 1 (type-of x))
2665
If @i{power-number} is a zero of any other @i{type},
2666
then the result is also the value one, in the @i{type} of the arguments
2667
after the application of the contagion rules in @ref{Contagion in Numeric Operations},
2669
the consequences are undefined if @i{base-number} is zero when @i{power-number}
2670
is zero and not of @i{type} @b{integer}.
2672
@subsubheading Examples::
2675
(exp 0) @result{} 1.0
2676
(exp 1) @result{} 2.718282
2677
(exp (log 5)) @result{} 5.0
2678
(expt 2 8) @result{} 256
2679
(expt 4 .5) @result{} 2.0
2680
(expt #c(0 1) 2) @result{} -1
2681
(expt #c(2 2) 3) @result{} #C(-16 16)
2682
(expt #c(2 2) 4) @result{} -64
2685
@subsubheading See Also::
2689
@ref{Rule of Float Substitutability}
2691
@subsubheading Notes::
2693
Implementations of @b{expt} are permitted to use different algorithms
2694
for the cases of a @i{power-number} of @i{type} @b{rational}
2695
and a @i{power-number} of @i{type} @b{float}.
2697
Note that by the following logic,
2698
@t{(sqrt (expt @i{x} 3))} is not equivalent to
2699
@t{(expt @i{x} 3/2)}.
2702
(setq x (exp (/ (* 2 pi #c(0 1)) 3))) ;exp(2.pi.i/3)
2703
(expt x 3) @result{} 1 ;except for round-off error
2704
(sqrt (expt x 3)) @result{} 1 ;except for round-off error
2705
(expt x 3/2) @result{} -1 ;except for round-off error
2708
@node gcd, incf, exp, Numbers Dictionary
2709
@subsection gcd [Function]
2711
@code{gcd} @i{@r{&rest} integers} @result{} @i{greatest-common-denominator}
2713
@subsubheading Arguments and Values::
2715
@i{integer}---an @i{integer}.
2717
@i{greatest-common-denominator}---a non-negative @i{integer}.
2719
@subsubheading Description::
2721
Returns the greatest common divisor of @i{integers}.
2722
If only one @i{integer} is supplied, its absolute value is returned.
2723
If no @i{integers} are given, @b{gcd} returns @t{0},
2724
which is an identity for this operation.
2726
@subsubheading Examples::
2730
(gcd 60 42) @result{} 6
2731
(gcd 3333 -33 101) @result{} 1
2732
(gcd 3333 -33 1002001) @result{} 11
2733
(gcd 91 -49) @result{} 7
2734
(gcd 63 -42 35) @result{} 7
2736
(gcd -4) @result{} 4
2739
@subsubheading Exceptional Situations::
2741
Should signal an error of @i{type} @b{type-error}
2742
if any @i{integer} is not an @i{integer}.
2744
@subsubheading See Also::
2748
@subsubheading Notes::
2749
For three or more arguments,
2752
(gcd b c ... z) @equiv{} (gcd (gcd a b) c ... z)
2755
@node incf, lcm, gcd, Numbers Dictionary
2756
@subsection incf, decf [Macro]
2758
@code{incf} @i{place @r{[}delta-form@r{]}} @result{} @i{new-value}
2760
@code{decf} @i{place @r{[}delta-form@r{]}} @result{} @i{new-value}
2762
@subsubheading Arguments and Values::
2764
@i{place}---a @i{place}.
2766
@i{delta-form}---a @i{form}; evaluated to produce a @i{delta}.
2767
The default is @t{1}.
2769
@i{delta}---a @i{number}.
2771
@i{new-value}---a @i{number}.
2773
@subsubheading Description::
2775
@b{incf} and @b{decf} are used for incrementing and
2776
decrementing the @i{value} of @i{place}, respectively.
2779
added to (in the case of @b{incf})
2780
or subtracted from (in the case of @b{decf})
2781
the number in @i{place} and the result is stored in @i{place}.
2783
Any necessary type conversions are performed automatically.
2785
For information about the @i{evaluation} of @i{subforms} of @i{places},
2786
see @ref{Evaluation of Subforms to Places}.
2788
@subsubheading Examples::
2791
(incf n) @result{} 1
2793
(decf n 3) @result{} -2
2795
(decf n -5) @result{} 3
2796
(decf n) @result{} 2
2797
(incf n 0.5) @result{} 2.5
2798
(decf n) @result{} 1.5
2802
@subsubheading Side Effects::
2804
@i{Place} is modified.
2806
@subsubheading See Also::
2813
@node lcm, log, incf, Numbers Dictionary
2814
@subsection lcm [Function]
2816
@code{lcm} @i{@r{&rest} integers} @result{} @i{least-common-multiple}
2818
@subsubheading Arguments and Values::
2820
@i{integer}---an @i{integer}.
2822
@i{least-common-multiple}---a non-negative @i{integer}.
2824
@subsubheading Description::
2826
@b{lcm} returns the least common multiple of the @i{integers}.
2828
If no @i{integer} is supplied, the @i{integer} @t{1} is returned.
2830
If only one @i{integer} is supplied,
2831
the absolute value of that @i{integer} is returned.
2833
For two arguments that are not both zero,
2836
(lcm a b) @equiv{} (/ (abs (* a b)) (gcd a b))
2839
If one or both arguments are zero,
2842
(lcm a 0) @equiv{} (lcm 0 a) @equiv{} 0
2845
For three or more arguments,
2848
(lcm a b c ... z) @equiv{} (lcm (lcm a b) c ... z)
2851
@subsubheading Examples::
2853
(lcm 10) @result{} 10
2854
(lcm 25 30) @result{} 150
2855
(lcm -24 18 10) @result{} 360
2856
(lcm 14 35) @result{} 70
2857
(lcm 0 5) @result{} 0
2858
(lcm 1 2 3 4 5 6) @result{} 60
2861
@subsubheading Exceptional Situations::
2863
Should signal @b{type-error} if any argument is not an @i{integer}.
2865
@subsubheading See Also::
2869
@node log, mod (Function), lcm, Numbers Dictionary
2870
@subsection log [Function]
2872
@code{log} @i{number @r{&optional} base} @result{} @i{logarithm}
2874
@subsubheading Arguments and Values::
2876
@i{number}---a non-zero @i{number}.
2878
@i{base}---a @i{number}.
2880
@i{logarithm}---a @i{number}.
2882
@subsubheading Description::
2884
@b{log} returns the logarithm of @i{number} in base @i{base}.
2885
If @i{base} is not supplied its value is @i{e},
2886
the base of the natural logarithms.
2888
@b{log} may return a @i{complex} when given a
2892
negative @i{number}.
2895
(log -1.0) @equiv{} (complex 0.0 (float pi 0.0))
2898
If @i{base} is zero,
2899
@b{log} returns zero.
2901
The result of @t{(log 8 2)} may be either @t{3} or @t{3.0}, depending on the
2902
implementation. An implementation can use floating-point calculations
2903
even if an exact integer result is possible.
2905
The branch cut for the logarithm function of one argument (natural
2906
logarithm) lies along the negative real axis, continuous with quadrant II.
2907
The domain excludes the origin.
2909
The mathematical definition of a complex logarithm
2910
is as follows, whether or not minus zero is supported by the
2914
(log @i{x}) @equiv{} (complex (log (abs @i{x})) (phase @i{x}))
2917
Therefore the range of the one-argument logarithm function is that strip
2918
of the complex plane containing numbers with imaginary parts between
2920
-\pi (exclusive) and~\pi (inclusive) if minus zero is not supported,
2921
or -\pi (inclusive) and~\pi (inclusive) if minus zero is supported.
2923
The two-argument logarithm function is defined as
2926
(log @i{base} @i{number})
2927
@equiv{} (/ (log @i{number}) (log @i{base}))
2930
This defines the @i{principal} @i{values} precisely.
2931
The range of the two-argument logarithm function is the entire complex plane.
2933
@subsubheading Examples::
2939
(log 100.0 10) @result{} 2.0
2940
(log #c(0 1) #c(0 -1))
2941
@result{} #C(-1.0 0.0)
2942
@i{OR}@result{} #C(-1 0)
2943
(log 8.0 2) @result{} 3.0
2947
(log #c(-16 16) #c(2 2)) @result{} 3 or approximately #c(3.0 0.0)
2948
or approximately 3.0 (unlikely)
2951
@subsubheading Affected By::
2955
@subsubheading See Also::
2960
@ref{Rule of Float Substitutability}
2962
@node mod (Function), signum, log, Numbers Dictionary
2963
@subsection mod, rem [Function]
2965
@code{mod} @i{number divisor} @result{} @i{modulus}
2967
@code{rem} @i{number divisor} @result{} @i{remainder}
2969
@subsubheading Arguments and Values::
2971
@i{number}---a @i{real}.
2973
@i{divisor}---a @i{real}.
2975
@i{modulus}, @i{remainder}---a @i{real}.
2977
@subsubheading Description::
2979
@b{mod} and @b{rem} are generalizations of the modulus
2980
and remainder functions respectively.
2982
@b{mod} performs the operation @b{floor}
2983
on @i{number} and @i{divisor}
2984
and returns the remainder of the @b{floor} operation.
2986
@b{rem} performs the operation @b{truncate}
2987
on @i{number} and @i{divisor}
2988
and returns the remainder of the @b{truncate} operation.
2990
@b{mod} and @b{rem} are
2991
the modulus and remainder functions
2992
when @i{number} and @i{divisor} are @i{integers}.
2994
@subsubheading Examples::
2996
(rem -1 5) @result{} -1
2997
(mod -1 5) @result{} 4
2998
(mod 13 4) @result{} 1
2999
(rem 13 4) @result{} 1
3000
(mod -13 4) @result{} 3
3001
(rem -13 4) @result{} -1
3002
(mod 13 -4) @result{} -3
3003
(rem 13 -4) @result{} 1
3004
(mod -13 -4) @result{} -1
3005
(rem -13 -4) @result{} -1
3006
(mod 13.4 1) @result{} 0.4
3007
(rem 13.4 1) @result{} 0.4
3008
(mod -13.4 1) @result{} 0.6
3009
(rem -13.4 1) @result{} -0.4
3012
@subsubheading See Also::
3017
@subsubheading Notes::
3019
The result of @b{mod} is either zero or a
3023
with the same sign as @i{divisor}.
3025
@node signum, sqrt, mod (Function), Numbers Dictionary
3026
@subsection signum [Function]
3028
@code{signum} @i{number} @result{} @i{signed-prototype}
3030
@subsubheading Arguments and Values::
3032
@i{number}---a @i{number}.
3034
@i{signed-prototype}---a @i{number}.
3036
@subsubheading Description::
3038
@b{signum} determines a numerical value that indicates whether
3039
@i{number} is negative, zero, or positive.
3042
@b{signum} returns one of @t{-1}, @t{0}, or @t{1}
3043
according to whether @i{number} is negative, zero, or positive.
3045
the result is a @i{float} of the same format
3046
whose value is minus one, zero, or one.
3047
For a @i{complex} number @t{z},
3048
@t{(signum @i{z})} is a complex number of the same phase but with unit magnitude,
3049
unless @t{z} is a complex zero, in which case the result is @t{z}.
3051
For @i{rational} @i{arguments}, @b{signum} is a rational function,
3052
but it may be irrational for @i{complex} @i{arguments}.
3054
If @i{number} is a @i{float}, the result is a @i{float}.
3055
If @i{number} is a @i{rational}, the result is a @i{rational}.
3056
If @i{number} is a @i{complex float}, the result is a @i{complex float}.
3057
If @i{number} is a @i{complex rational}, the result is a @i{complex},
3058
but it is @i{implementation-dependent} whether that result is a
3059
@i{complex rational} or a @i{complex float}.
3061
@subsubheading Examples::
3064
(signum 0) @result{} 0
3065
(signum 99) @result{} 1
3066
(signum 4/5) @result{} 1
3067
(signum -99/100) @result{} -1
3068
(signum 0.0) @result{} 0.0
3069
(signum #c(0 33)) @result{} #C(0.0 1.0)
3070
(signum #c(7.5 10.0)) @result{} #C(0.6 0.8)
3071
(signum #c(0.0 -14.7)) @result{} #C(0.0 -1.0)
3072
(eql (signum -0.0) -0.0) @result{} @i{true}
3075
@subsubheading See Also::
3077
@ref{Rule of Float Substitutability}
3079
@subsubheading Notes::
3081
(signum x) @equiv{} (if (zerop x) x (/ x (abs x)))
3084
@node sqrt, random-state, signum, Numbers Dictionary
3085
@subsection sqrt, isqrt [Function]
3087
@code{sqrt} @i{number} @result{} @i{root}
3089
@code{isqrt} @i{natural} @result{} @i{natural-root}
3091
@subsubheading Arguments and Values::
3093
@i{number}, @i{root}---a @i{number}.
3095
@i{natural}, @i{natural-root}---a non-negative @i{integer}.
3097
@subsubheading Description::
3099
@b{sqrt} and @b{isqrt} compute square roots.
3101
@b{sqrt} returns the @i{principal} square root of @i{number}.
3102
If the @i{number} is not a @i{complex} but is negative,
3103
then the result is a @i{complex}.
3105
@b{isqrt} returns the greatest @i{integer}
3106
less than or equal to the exact positive square root of @i{natural}.
3108
If @i{number} is a positive @i{rational},
3109
it is @i{implementation-dependent}
3110
whether @i{root} is a @i{rational} or a @i{float}.
3111
If @i{number} is a negative @i{rational},
3112
it is @i{implementation-dependent}
3113
whether @i{root} is a @i{complex rational} or a @i{complex float}.
3115
The mathematical definition of complex square root (whether or not
3116
minus zero is supported) follows:
3118
@t{(sqrt @i{x}) = (exp (/ (log @i{x}) 2))}
3120
The branch cut for square root lies along the negative real axis,
3121
continuous with quadrant II.
3122
The range consists of the right half-plane, including the non-negative
3123
imaginary axis and excluding the negative imaginary axis.
3125
@subsubheading Examples::
3128
(sqrt 9.0) @result{} 3.0
3129
(sqrt -9.0) @result{} #C(0.0 3.0)
3130
(isqrt 9) @result{} 3
3131
(sqrt 12) @result{} 3.4641016
3132
(isqrt 12) @result{} 3
3133
(isqrt 300) @result{} 17
3134
(isqrt 325) @result{} 18
3138
(isqrt 25) @result{} 5
3139
(sqrt -1) @result{} #C(0.0 1.0)
3140
(sqrt #c(0 2)) @result{} #C(1.0 1.0)
3143
@subsubheading Exceptional Situations::
3145
The @i{function} @b{sqrt} should signal @b{type-error} if its argument
3146
is not a @i{number}.
3148
The @i{function} @b{isqrt} should signal @b{type-error} if its argument
3149
is not a non-negative @i{integer}.
3151
The functions @b{sqrt} and @b{isqrt} might signal @b{arithmetic-error}.
3153
@subsubheading See Also::
3159
@ref{Rule of Float Substitutability}
3161
@subsubheading Notes::
3164
(isqrt x) @equiv{} (values (floor (sqrt x)))
3167
but it is potentially more efficient.
3169
@node random-state, make-random-state, sqrt, Numbers Dictionary
3170
@subsection random-state [System Class]
3172
@subsubheading Class Precedence List::
3176
@subsubheading Description::
3178
A @i{random state} @i{object} contains state
3179
information used by the pseudo-random number generator.
3180
The nature of a @i{random state} @i{object} is @i{implementation-dependent}.
3181
It can be printed out and successfully read back in by the same @i{implementation},
3182
but might not function correctly as a @i{random state} in another @i{implementation}.
3184
@i{Implementations} are required to provide a read syntax for
3185
@i{objects} of @i{type} @b{random-state}, but the specific nature of that syntax
3186
is @i{implementation-dependent}.
3188
@subsubheading See Also::
3194
@ref{Printing Random States}
3196
@node make-random-state, random, random-state, Numbers Dictionary
3197
@subsection make-random-state [Function]
3199
@code{make-random-state} @i{@r{&optional} state} @result{} @i{new-state}
3201
@subsubheading Arguments and Values::
3203
@i{state}---a @i{random state}, or @b{nil}, or @b{t}.
3204
The default is @b{nil}.
3206
@i{new-state}---a @i{random state} @i{object}.
3208
@subsubheading Description::
3210
Creates a @i{fresh} @i{object} of @i{type} @b{random-state} suitable
3211
for use as the @i{value} of @b{*random-state*}.
3213
If @i{state} is a @i{random state} @i{object},
3214
the @i{new-state} is a @i{copy}_5 of that @i{object}.
3215
If @i{state} is @b{nil},
3216
the @i{new-state} is a @i{copy}_5 of the @i{current random state}.
3217
If @i{state} is @b{t},
3218
the @i{new-state} is a @i{fresh} @i{random state} @i{object}
3219
that has been randomly initialized by some means.
3221
@subsubheading Examples::
3224
(let* ((rs1 (make-random-state nil))
3225
(rs2 (make-random-state t))
3226
(rs3 (make-random-state rs2))
3228
(list (loop for i from 1 to 10
3229
collect (random 100)
3231
do (setq rs4 (make-random-state)))
3232
(loop for i from 1 to 10 collect (random 100 rs1))
3233
(loop for i from 1 to 10 collect (random 100 rs2))
3234
(loop for i from 1 to 10 collect (random 100 rs3))
3235
(loop for i from 1 to 10 collect (random 100 rs4))))
3236
@result{} ((29 25 72 57 55 68 24 35 54 65)
3237
(29 25 72 57 55 68 24 35 54 65)
3238
(93 85 53 99 58 62 2 23 23 59)
3239
(93 85 53 99 58 62 2 23 23 59)
3240
(68 24 35 54 65 54 55 50 59 49))
3243
@subsubheading Exceptional Situations::
3245
Should signal an error of @i{type} @b{type-error}
3246
if @i{state} is not a @i{random state}, or @b{nil}, or @b{t}.
3248
@subsubheading See Also::
3254
@subsubheading Notes::
3256
One important use of @b{make-random-state} is to allow the same
3257
series of pseudo-random @i{numbers} to be generated many times within a
3260
@node random, random-state-p, make-random-state, Numbers Dictionary
3261
@subsection random [Function]
3263
@code{random} @i{limit @r{&optional} random-state} @result{} @i{random-number}
3265
@subsubheading Arguments and Values::
3267
@i{limit}---a positive @i{integer},
3268
or a positive @i{float}.
3270
@i{random-state}---a @i{random state}.
3271
The default is the @i{current random state}.
3273
@i{random-number}---a non-negative @i{number}
3275
and of the same @i{type} as @i{limit}.
3277
@subsubheading Description::
3279
Returns a pseudo-random number that is a non-negative @i{number}
3280
less than @i{limit} and of the same @i{type} as @i{limit}.
3282
The @i{random-state}, which is modified by this function,
3283
encodes the internal state maintained by the random number generator.
3285
An approximately uniform choice distribution is used. If @i{limit}
3286
is an @i{integer}, each of the possible results occurs with
3287
(approximate) probability 1/@i{limit}.
3289
@subsubheading Examples::
3292
(<= 0 (random 1000) 1000) @result{} @i{true}
3293
(let ((state1 (make-random-state))
3294
(state2 (make-random-state)))
3295
(= (random 1000 state1) (random 1000 state2))) @result{} @i{true}
3298
@subsubheading Side Effects::
3300
The @i{random-state} is modified.
3302
@subsubheading Exceptional Situations::
3304
Should signal an error of @i{type} @b{type-error}
3305
if @i{limit} is not a positive @i{integer} or a positive @i{real}.
3307
@subsubheading See Also::
3309
@ref{make-random-state}
3313
@subsubheading Notes::
3315
See @i{Common Lisp: The Language} for information about generating random numbers.
3317
@node random-state-p, *random-state*, random, Numbers Dictionary
3318
@subsection random-state-p [Function]
3320
@code{random-state-p} @i{object} @result{} @i{generalized-boolean}
3322
@subsubheading Arguments and Values::
3324
@i{object}---an @i{object}.
3326
@i{generalized-boolean}---a @i{generalized boolean}.
3328
@subsubheading Description::
3330
Returns @i{true} if @i{object} is of @i{type} @b{random-state};
3331
otherwise, returns @i{false}.
3333
@subsubheading Examples::
3336
(random-state-p *random-state*) @result{} @i{true}
3337
(random-state-p (make-random-state)) @result{} @i{true}
3338
(random-state-p 'test-function) @result{} @i{false}
3341
@subsubheading See Also::
3343
@ref{make-random-state}
3347
@subsubheading Notes::
3350
(random-state-p @i{object}) @equiv{} (typep @i{object} 'random-state)
3353
@node *random-state*, numberp, random-state-p, Numbers Dictionary
3354
@subsection *random-state* [Variable]
3356
@subsubheading Value Type::
3360
@subsubheading Initial Value::
3362
@i{implementation-dependent}.
3364
@subsubheading Description::
3366
The @i{current random state}, which is used, for example,
3367
by the @i{function} @b{random} when a @i{random state} is not explicitly supplied.
3369
@subsubheading Examples::
3372
(random-state-p *random-state*) @result{} @i{true}
3373
(setq snap-shot (make-random-state))
3374
;; The series from any given point is random,
3375
;; but if you backtrack to that point, you get the same series.
3376
(list (loop for i from 1 to 10 collect (random))
3377
(let ((*random-state* snap-shot))
3378
(loop for i from 1 to 10 collect (random)))
3379
(loop for i from 1 to 10 collect (random))
3380
(let ((*random-state* snap-shot))
3381
(loop for i from 1 to 10 collect (random))))
3382
@result{} ((19 16 44 19 96 15 76 96 13 61)
3383
(19 16 44 19 96 15 76 96 13 61)
3384
(16 67 0 43 70 79 58 5 63 50)
3385
(16 67 0 43 70 79 58 5 63 50))
3388
@subsubheading Affected By::
3390
The @i{implementation}.
3394
@subsubheading See Also::
3396
@ref{make-random-state}
3402
@subsubheading Notes::
3404
@i{Binding} @b{*random-state*} to a different
3405
@i{random state} @i{object} correctly saves and
3406
restores the old @i{random state} @i{object}.
3408
@node numberp, cis, *random-state*, Numbers Dictionary
3409
@subsection numberp [Function]
3411
@code{numberp} @i{object} @result{} @i{generalized-boolean}
3413
@subsubheading Arguments and Values::
3415
@i{object}---an @i{object}.
3417
@i{generalized-boolean}---a @i{generalized boolean}.
3419
@subsubheading Description::
3421
Returns @i{true} if @i{object} is of @i{type} @b{number};
3422
otherwise, returns @i{false}.
3424
@subsubheading Examples::
3427
(numberp 12) @result{} @i{true}
3428
(numberp (expt 2 130)) @result{} @i{true}
3429
(numberp #c(5/3 7.2)) @result{} @i{true}
3430
(numberp nil) @result{} @i{false}
3431
(numberp (cons 1 2)) @result{} @i{false}
3434
@subsubheading Notes::
3437
(numberp @i{object}) @equiv{} (typep @i{object} 'number)
3440
@node cis, complex, numberp, Numbers Dictionary
3441
@subsection cis [Function]
3443
@code{cis} @i{radians} @result{} @i{number}
3445
@subsubheading Arguments and Values::
3447
@i{radians}---a @i{real}.
3449
@i{number}---a @i{complex}.
3451
@subsubheading Description::
3453
@b{cis} returns the value of~@i{e}^@i{i\cdot @i{radians}},
3454
which is a @i{complex} in which the
3455
real part is equal to the cosine of @i{radians}, and the
3456
imaginary part is equal to the sine of @i{radians}.
3458
@subsubheading Examples::
3460
(cis 0) @result{} #C(1.0 0.0)
3463
@subsubheading See Also::
3465
@ref{Rule of Float Substitutability}
3467
@node complex, complexp, cis, Numbers Dictionary
3468
@subsection complex [Function]
3470
@code{complex} @i{realpart @r{&optional} imagpart} @result{} @i{complex}
3472
@subsubheading Arguments and Values::
3474
@i{realpart}---a @i{real}.
3476
@i{imagpart}---a @i{real}.
3478
@i{complex}---a @i{rational} or a @i{complex}.
3480
@subsubheading Description::
3482
@b{complex} returns a @i{number}
3483
whose real part is @i{realpart}
3484
and whose imaginary part is @i{imagpart}.
3486
If @i{realpart} is a @i{rational}
3487
and @i{imagpart} is the @i{rational} number zero,
3488
the result of @b{complex} is @i{realpart}, a @i{rational}.
3489
Otherwise, the result is a @i{complex}.
3491
If either @i{realpart} or @i{imagpart} is a @i{float},
3492
the non-@i{float} is converted to a @i{float}
3493
before the @i{complex} is created.
3494
If @i{imagpart} is not supplied, the imaginary part is a
3495
zero of the same @i{type} as @i{realpart}; @i{i.e.}, @t{(coerce 0 (type-of @i{realpart}))} is
3498
Type upgrading implies a movement upwards in the type
3500
In the case of @i{complexes}, the @i{type-specifier}
3502
[Reviewer Note by Barmar: What type specifier?]
3503
must be a subtype of
3504
@t{(upgraded-complex-part-type @i{type-specifier})}.
3505
If @i{type-specifier1} is a subtype of @i{type-specifier2}, then
3506
@t{(upgraded-complex-element-type '@i{type-specifier1})}
3507
must also be a subtype of
3508
@t{(upgraded-complex-element-type '@i{type-specifier2})}.
3509
Two disjoint types can be upgraded into
3512
@subsubheading Examples::
3514
(complex 0) @result{} 0
3515
(complex 0.0) @result{} #C(0.0 0.0)
3516
(complex 1 1/2) @result{} #C(1 1/2)
3517
(complex 1 .99) @result{} #C(1.0 0.99)
3518
(complex 3/2 0.0) @result{} #C(1.5 0.0)
3521
@subsubheading See Also::
3526
@subsubheading Notes::
3529
#c(a b) @equiv{} #.(complex a b)
3532
@node complexp, conjugate, complex, Numbers Dictionary
3533
@subsection complexp [Function]
3535
@code{complexp} @i{object} @result{} @i{generalized-boolean}
3537
@subsubheading Arguments and Values::
3539
@i{object}---an @i{object}.
3541
@i{generalized-boolean}---a @i{generalized boolean}.
3543
@subsubheading Description::
3545
Returns @i{true} if @i{object} is of @i{type} @b{complex};
3546
otherwise, returns @i{false}.
3548
@subsubheading Examples::
3550
(complexp 1.2d2) @result{} @i{false}
3551
(complexp #c(5/3 7.2)) @result{} @i{true}
3555
@subsubheading See Also::
3558
(@i{function} and @i{type}),
3561
@subsubheading Notes::
3564
(complexp @i{object}) @equiv{} (typep @i{object} 'complex)
3567
@node conjugate, phase, complexp, Numbers Dictionary
3568
@subsection conjugate [Function]
3570
@code{conjugate} @i{number} @result{} @i{conjugate}
3572
@subsubheading Arguments and Values::
3574
@i{number}---a @i{number}.
3576
@i{conjugate}---a @i{number}.
3578
@subsubheading Description::
3580
Returns the complex conjugate of @i{number}.
3587
@subsubheading Examples::
3590
(conjugate #c(0 -1)) @result{} #C(0 1)
3591
(conjugate #c(1 1)) @result{} #C(1 -1)
3592
(conjugate 1.5) @result{} 1.5
3593
(conjugate #C(3/5 4/5)) @result{} #C(3/5 -4/5)
3594
(conjugate #C(0.0D0 -1.0D0)) @result{} #C(0.0D0 1.0D0)
3595
(conjugate 3.7) @result{} 3.7
3598
@subsubheading Notes::
3600
For a @i{complex} number @t{z},
3603
(conjugate z) @equiv{} (complex (realpart z) (- (imagpart z)))
3606
@node phase, realpart, conjugate, Numbers Dictionary
3607
@subsection phase [Function]
3609
@code{phase} @i{number} @result{} @i{phase}
3611
@subsubheading Arguments and Values::
3613
@i{number}---a @i{number}.
3615
@i{phase}---a @i{number}.
3617
@subsubheading Description::
3621
of @i{number} (the angle part of its polar representation)
3622
in radians, in the range
3624
-\pi (exclusive) if minus zero is not supported, or
3625
-\pi (inclusive) if minus zero is supported,
3627
to \pi (inclusive). The phase of a positive
3632
is zero; that of a negative
3637
The phase of zero is defined to be zero.
3639
If @i{number} is a @i{complex float},
3640
the result is a @i{float} of the same @i{type}
3641
as the components of @i{number}.
3642
If @i{number} is a @i{float}, the result is a
3643
@i{float} of the same @i{type}.
3644
If @i{number} is a @i{rational} or a @i{complex rational},
3645
the result is a @i{single float}.
3647
The branch cut for @b{phase} lies along the negative real
3648
axis, continuous with quadrant II. The range consists of that portion of
3649
the real axis between -\pi (exclusive) and~\pi (inclusive).
3651
The mathematical definition of @b{phase} is as follows:
3653
@t{(phase @i{x}) = (atan (imagpart @i{x}) (realpart @i{x}))}
3655
@subsubheading Examples::
3658
(phase 1) @result{} 0.0s0
3659
(phase 0) @result{} 0.0s0
3660
(phase (cis 30)) @result{} -1.4159266
3661
(phase #c(0 1)) @result{} 1.5707964
3664
@subsubheading Exceptional Situations::
3666
Should signal @b{type-error} if its argument is not a @i{number}.
3667
Might signal @b{arithmetic-error}.
3669
@subsubheading See Also::
3671
@ref{Rule of Float Substitutability}
3673
@node realpart, upgraded-complex-part-type, phase, Numbers Dictionary
3674
@subsection realpart, imagpart [Function]
3676
@code{realpart} @i{number} @result{} @i{real}
3678
@code{imagpart} @i{number} @result{} @i{real}
3680
@subsubheading Arguments and Values::
3682
@i{number}---a @i{number}.
3684
@i{real}---a @i{real}.
3686
@subsubheading Description::
3688
@b{realpart} and @b{imagpart} return the real and
3689
imaginary parts of @i{number} respectively.
3694
then @b{realpart} returns @i{number} and @b{imagpart}
3695
returns @t{(* 0 @i{number})}, which has the effect that the
3696
imaginary part of a @i{rational} is @t{0} and that of
3697
a @i{float} is a floating-point zero of the same format.
3699
@subsubheading Examples::
3702
(realpart #c(23 41)) @result{} 23
3703
(imagpart #c(23 41.0)) @result{} 41.0
3704
(realpart #c(23 41.0)) @result{} 23.0
3705
(imagpart 23.0) @result{} 0.0
3708
@subsubheading Exceptional Situations::
3710
Should signal an error of @i{type} @b{type-error}
3711
if @i{number} is not a @i{number}.
3713
@subsubheading See Also::
3717
@node upgraded-complex-part-type, realp, realpart, Numbers Dictionary
3718
@subsection upgraded-complex-part-type [Function]
3720
@code{upgraded-complex-part-type} @i{typespec @r{&optional} environment} @result{} @i{upgraded-typespec}
3722
@subsubheading Arguments and Values::
3724
@i{typespec}---a @i{type specifier}.
3726
@i{environment}---an @i{environment} @i{object}.
3727
The default is @b{nil}, denoting the @i{null lexical environment}
3728
and the and current @i{global environment}.
3730
@i{upgraded-typespec}---a @i{type specifier}.
3732
@subsubheading Description::
3734
@b{upgraded-complex-part-type} returns the part type of the
3735
most specialized @i{complex} number representation that can
3736
hold parts of @i{type} @i{typespec}.
3738
The @i{typespec} is a @i{subtype} of
3739
(and possibly @i{type equivalent} to)
3740
the @i{upgraded-typespec}.
3742
The purpose of @b{upgraded-complex-part-type}
3743
is to reveal how an implementation does its @i{upgrading}.
3745
@subsubheading See Also::
3748
(@i{function} and @i{type})
3750
@subsubheading Notes::
3752
@node realp, numerator, upgraded-complex-part-type, Numbers Dictionary
3753
@subsection realp [Function]
3755
@code{realp} @i{object} @result{} @i{generalized-boolean}
3757
@subsubheading Arguments and Values::
3759
@i{object}---an @i{object}.
3761
@i{generalized-boolean}---a @i{generalized boolean}.
3763
@subsubheading Description::
3765
Returns @i{true} if @i{object} is of @i{type} @b{real};
3766
otherwise, returns @i{false}.
3768
@subsubheading Examples::
3770
(realp 12) @result{} @i{true}
3771
(realp #c(5/3 7.2)) @result{} @i{false}
3772
(realp nil) @result{} @i{false}
3773
(realp (cons 1 2)) @result{} @i{false}
3776
@subsubheading Notes::
3779
(realp @i{object}) @equiv{} (typep @i{object} 'real)
3782
@node numerator, rational (Function), realp, Numbers Dictionary
3783
@subsection numerator, denominator [Function]
3785
@code{numerator} @i{rational} @result{} @i{numerator}
3787
@code{denominator} @i{rational} @result{} @i{denominator}
3789
@subsubheading Arguments and Values::
3791
@i{rational}---a @i{rational}.
3793
@i{numerator}---an @i{integer}.
3795
@i{denominator}---a positive @i{integer}.
3797
@subsubheading Description::
3799
@b{numerator} and @b{denominator} reduce @i{rational}
3800
to canonical form and compute the numerator or denominator of that number.
3802
@b{numerator} and @b{denominator} return the numerator
3803
or denominator of the canonical form of @i{rational}.
3805
If @i{rational} is an @i{integer},
3806
@b{numerator} returns @i{rational}
3807
and @b{denominator} returns 1.
3809
@subsubheading Examples::
3811
(numerator 1/2) @result{} 1
3812
(denominator 12/36) @result{} 3
3813
(numerator -1) @result{} -1
3814
(denominator (/ -33)) @result{} 33
3815
(numerator (/ 8 -6)) @result{} -4
3816
(denominator (/ 8 -6)) @result{} 3
3819
@subsubheading See Also::
3823
@subsubheading Notes::
3825
(gcd (numerator x) (denominator x)) @result{} 1
3828
@node rational (Function), rationalp, numerator, Numbers Dictionary
3829
@subsection rational, rationalize [Function]
3831
@code{rational} @i{number} @result{} @i{rational}
3833
@code{rationalize} @i{number} @result{} @i{rational}
3835
@subsubheading Arguments and Values::
3837
@i{number}---a @i{real}.
3839
@i{rational}---a @i{rational}.
3841
@subsubheading Description::
3843
@b{rational} and @b{rationalize} convert
3849
If @i{number} is already @i{rational}, it is returned.
3851
If @i{number} is a @i{float},
3852
@b{rational} returns a @i{rational}
3853
that is mathematically equal in value to the @i{float}.
3854
@b{rationalize} returns a @i{rational} that
3855
approximates the @i{float} to the accuracy of
3856
the underlying floating-point representation.
3858
@b{rational} assumes that the @i{float} is completely accurate.
3860
@b{rationalize} assumes that the
3861
@i{float} is accurate only to the precision of the
3862
floating-point representation.
3864
@subsubheading Examples::
3866
(rational 0) @result{} 0
3867
(rationalize -11/100) @result{} -11/100
3868
(rational .1) @result{} 13421773/134217728 ;implementation-dependent
3869
(rationalize .1) @result{} 1/10
3872
@subsubheading Affected By::
3874
The @i{implementation}.
3876
@subsubheading Exceptional Situations::
3878
Should signal an error of @i{type} @b{type-error}
3879
if @i{number} is not a @i{real}.
3880
Might signal @b{arithmetic-error}.
3882
@subsubheading Notes::
3884
It is always the case that
3887
(float (rational x) x) @equiv{} x
3893
(float (rationalize x) x) @equiv{} x
3896
That is, rationalizing a @i{float} by either method
3897
and then converting it back
3899
of the same format produces the original @i{number}.
3901
@node rationalp, ash, rational (Function), Numbers Dictionary
3902
@subsection rationalp [Function]
3904
@code{rationalp} @i{object} @result{} @i{generalized-boolean}
3906
@subsubheading Arguments and Values::
3908
@i{object}---an @i{object}.
3910
@i{generalized-boolean}---a @i{generalized boolean}.
3912
@subsubheading Description::
3914
Returns @i{true} if @i{object} is of @i{type} @b{rational};
3915
otherwise, returns @i{false}.
3917
@subsubheading Examples::
3920
(rationalp 12) @result{} @i{true}
3921
(rationalp 6/5) @result{} @i{true}
3922
(rationalp 1.212) @result{} @i{false}
3925
@subsubheading See Also::
3927
@ref{rational (Function)}
3929
@subsubheading Notes::
3931
(rationalp @i{object}) @equiv{} (typep @i{object} 'rational)
3934
@node ash, integer-length, rationalp, Numbers Dictionary
3935
@subsection ash [Function]
3937
@code{ash} @i{integer count} @result{} @i{shifted-integer}
3939
@subsubheading Arguments and Values::
3941
@i{integer}---an @i{integer}.
3943
@i{count}---an @i{integer}.
3945
@i{shifted-integer}---an @i{integer}.
3947
@subsubheading Description::
3949
@b{ash} performs the arithmetic shift operation on the binary
3950
representation of @i{integer}, which is treated as if it were binary.
3952
@b{ash} shifts @i{integer} arithmetically left by @i{count} bit
3953
positions if @i{count} is positive,
3954
or right @i{count} bit positions if @i{count} is negative.
3955
The shifted value of the same sign
3956
as @i{integer} is returned.
3958
Mathematically speaking, @b{ash} performs the computation
3959
@t{floor}(@i{integer}\cdot 2^@i{count}).
3961
moves all of the bits in @i{integer} to the left,
3962
adding zero-bits at the right, or moves them to the right,
3965
@b{ash} is defined to behave as if @i{integer} were
3966
represented in two's complement form, regardless of
3967
how @i{integers} are represented internally.
3968
@subsubheading Examples::
3970
(ash 16 1) @result{} 32
3971
(ash 16 0) @result{} 16
3972
(ash 16 -1) @result{} 8
3973
(ash -100000000000000000000000000000000 -100) @result{} -79
3976
@subsubheading Exceptional Situations::
3978
Should signal an error of @i{type} @b{type-error}
3979
if @i{integer} is not an @i{integer}.
3980
Should signal an error of @i{type} @b{type-error}
3981
if @i{count} is not an @i{integer}.
3982
Might signal @b{arithmetic-error}.
3984
@subsubheading Notes::
3987
(logbitp @i{j} (ash @i{n} @i{k}))
3988
@equiv{} (and (>= @i{j} @i{k}) (logbitp (- @i{j} @i{k}) @i{n}))
3991
@node integer-length, integerp, ash, Numbers Dictionary
3992
@subsection integer-length [Function]
3994
@code{integer-length} @i{integer} @result{} @i{number-of-bits}
3996
@subsubheading Arguments and Values::
3998
@i{integer}---an @i{integer}.
4000
@i{number-of-bits}---a non-negative @i{integer}.
4002
@subsubheading Description::
4004
Returns the number of bits needed to represent @i{integer}
4005
in binary two's-complement format.
4007
@subsubheading Examples::
4010
(integer-length 0) @result{} 0
4011
(integer-length 1) @result{} 1
4012
(integer-length 3) @result{} 2
4013
(integer-length 4) @result{} 3
4014
(integer-length 7) @result{} 3
4015
(integer-length -1) @result{} 0
4016
(integer-length -4) @result{} 2
4017
(integer-length -7) @result{} 3
4018
(integer-length -8) @result{} 3
4019
(integer-length (expt 2 9)) @result{} 10
4020
(integer-length (1- (expt 2 9))) @result{} 9
4021
(integer-length (- (expt 2 9))) @result{} 9
4022
(integer-length (- (1+ (expt 2 9)))) @result{} 10
4025
@subsubheading Exceptional Situations::
4027
Should signal an error of @i{type} @b{type-error}
4028
if @i{integer} is not an @i{integer}.
4030
@subsubheading Notes::
4032
This function could have been defined by:
4035
(defun integer-length (integer)
4036
(ceiling (log (if (minusp integer)
4042
If @i{integer} is non-negative, then its value can be represented
4043
in unsigned binary form in a field whose width in bits is
4044
no smaller than @t{(integer-length @i{integer})}.
4045
Regardless of the sign of @i{integer}, its value can be
4046
represented in signed binary two's-complement form in a field
4047
whose width in bits is no smaller than @t{(+ (integer-length @i{integer}) 1)}.
4049
@node integerp, parse-integer, integer-length, Numbers Dictionary
4050
@subsection integerp [Function]
4052
@code{integerp} @i{object} @result{} @i{generalized-boolean}
4054
@subsubheading Arguments and Values::
4056
@i{object}---an @i{object}.
4058
@i{generalized-boolean}---a @i{generalized boolean}.
4060
@subsubheading Description::
4062
Returns @i{true} if @i{object} is of @i{type} @b{integer};
4063
otherwise, returns @i{false}.
4065
@subsubheading Examples::
4067
(integerp 1) @result{} @i{true}
4068
(integerp (expt 2 130)) @result{} @i{true}
4069
(integerp 6/5) @result{} @i{false}
4070
(integerp nil) @result{} @i{false}
4074
@subsubheading Notes::
4077
(integerp @i{object}) @equiv{} (typep @i{object} 'integer)
4080
@node parse-integer, boole, integerp, Numbers Dictionary
4081
@subsection parse-integer [Function]
4083
@code{parse-integer} @i{string @r{&key} start end radix junk-allowed} @result{} @i{integer, pos}
4085
@subsubheading Arguments and Values::
4087
@i{string}---a @i{string}.
4089
@i{start}, @i{end}---@i{bounding index designators} of @i{string}.
4090
The defaults for @i{start} and @i{end} are @t{0} and @b{nil}, respectively.
4092
@i{radix}---a @i{radix}.
4093
The default is @t{10}.
4095
@i{junk-allowed}---a @i{generalized boolean}.
4096
The default is @i{false}.
4098
@i{integer}---an @i{integer} or @i{false}.
4100
@i{pos}---a @i{bounding index} of @i{string}.
4102
@subsubheading Description::
4104
@b{parse-integer} parses an @i{integer} in the specified @i{radix}
4105
from the substring of @i{string} delimited by @i{start} and @i{end}.
4107
@b{parse-integer} expects an optional sign (@t{+} or @t{-}) followed by
4108
a a non-empty sequence of digits to be interpreted in the specified @i{radix}.
4109
Optional leading and trailing @i{whitespace}_1 is ignored.
4111
@b{parse-integer} does not recognize the syntactic radix-specifier
4112
prefixes @t{#O}, @t{#B}, @t{#X}, and @t{#@i{n}R},
4113
nor does it recognize a trailing decimal point.
4115
If @i{junk-allowed} is @i{false}, an error of @i{type} @b{parse-error} is
4116
signaled if substring does not consist entirely of the representation of a
4117
signed @i{integer}, possibly surrounded on either side by @i{whitespace}_1
4120
The first @i{value} returned is either
4121
the @i{integer} that was parsed,
4122
or else @b{nil} if no syntactically correct @i{integer}
4123
was seen but @i{junk-allowed} was @i{true}.
4125
The second @i{value} is either
4126
the index into the @i{string} of the delimiter that terminated the parse,
4127
or the upper @i{bounding index} of the substring if the parse terminated at
4128
the end of the substring (as is always the case if @i{junk-allowed}
4131
@subsubheading Examples::
4133
(parse-integer "123") @result{} 123, 3
4134
(parse-integer "123" :start 1 :radix 5) @result{} 13, 3
4135
(parse-integer "no-integer" :junk-allowed t) @result{} NIL, 0
4138
@subsubheading Exceptional Situations::
4140
If @i{junk-allowed} is @i{false},
4141
an error is signaled if substring does not consist entirely of
4142
the representation of an @i{integer},
4143
possibly surrounded on either side by
4144
@i{whitespace}_1 characters.
4146
@node boole, boole-1, parse-integer, Numbers Dictionary
4147
@subsection boole [Function]
4149
@code{boole} @i{op integer-1 integer-2} @result{} @i{result-integer}
4151
@subsubheading Arguments and Values::
4153
@i{Op}---a @i{bit-wise logical operation specifier}.
4155
@i{integer-1}---an @i{integer}.
4157
@i{integer-2}---an @i{integer}.
4159
@i{result-integer}---an @i{integer}.
4161
@subsubheading Description::
4163
@b{boole} performs bit-wise logical operations on
4164
@i{integer-1} and @i{integer-2}, which are treated as if
4165
they were binary and in two's complement representation.
4167
The operation to be performed and the return value are determined by
4170
@b{boole} returns the values
4171
specified for any @i{op} in Figure 12--16.
4179
@w{ @b{boole-1} @i{integer-1} }
4180
@w{ @b{boole-2} @i{integer-2} }
4181
@w{ @b{boole-andc1} and complement of @i{integer-1} with @i{integer-2} }
4182
@w{ @b{boole-andc2} and @i{integer-1} with complement of @i{integer-2} }
4183
@w{ @b{boole-and} and }
4184
@w{ @b{boole-c1} complement of @i{integer-1} }
4185
@w{ @b{boole-c2} complement of @i{integer-2} }
4186
@w{ @b{boole-clr} always 0 (all zero bits) }
4187
@w{ @b{boole-eqv} equivalence (exclusive nor) }
4188
@w{ @b{boole-ior} inclusive or }
4189
@w{ @b{boole-nand} not-and }
4190
@w{ @b{boole-nor} not-or }
4191
@w{ @b{boole-orc1} or complement of @i{integer-1} with @i{integer-2} }
4192
@w{ @b{boole-orc2} or @i{integer-1} with complement of @i{integer-2} }
4193
@w{ @b{boole-set} always -1 (all one bits) }
4194
@w{ @b{boole-xor} exclusive or }
4197
@w{ Figure 12--16: Bit-Wise Logical Operations }
4204
@subsubheading Examples::
4207
(boole boole-ior 1 16) @result{} 17
4208
(boole boole-and -2 5) @result{} 4
4209
(boole boole-eqv 17 15) @result{} -31
4211
;;; These examples illustrate the result of applying BOOLE and each
4212
;;; of the possible values of OP to each possible combination of bits.
4214
(format t "~&Results of (BOOLE <op> #b0011 #b0101) ...~
4216
(dolist (symbol '(boole-1 boole-2 boole-and boole-andc1
4217
boole-andc2 boole-c1 boole-c2 boole-clr
4218
boole-eqv boole-ior boole-nand boole-nor
4219
boole-orc1 boole-orc2 boole-set boole-xor))
4220
(let ((result (boole (symbol-value symbol) #b0011 #b0101)))
4221
(format t "~& ~A~13T~3,' D~23T~:*~5,' B~31T ...~4,'0B~
4222
symbol result (logand result #b1111)))))
4223
@t{ |> } Results of (BOOLE <op> #b0011 #b0101) ...
4224
@t{ |> } ---Op-------Decimal-----Binary----Bits---
4225
@t{ |> } BOOLE-1 3 11 ...0011
4226
@t{ |> } BOOLE-2 5 101 ...0101
4227
@t{ |> } BOOLE-AND 1 1 ...0001
4228
@t{ |> } BOOLE-ANDC1 4 100 ...0100
4229
@t{ |> } BOOLE-ANDC2 2 10 ...0010
4230
@t{ |> } BOOLE-C1 -4 -100 ...1100
4231
@t{ |> } BOOLE-C2 -6 -110 ...1010
4232
@t{ |> } BOOLE-CLR 0 0 ...0000
4233
@t{ |> } BOOLE-EQV -7 -111 ...1001
4234
@t{ |> } BOOLE-IOR 7 111 ...0111
4235
@t{ |> } BOOLE-NAND -2 -10 ...1110
4236
@t{ |> } BOOLE-NOR -8 -1000 ...1000
4237
@t{ |> } BOOLE-ORC1 -3 -11 ...1101
4238
@t{ |> } BOOLE-ORC2 -5 -101 ...1011
4239
@t{ |> } BOOLE-SET -1 -1 ...1111
4240
@t{ |> } BOOLE-XOR 6 110 ...0110
4244
@subsubheading Exceptional Situations::
4246
Should signal @b{type-error} if its first argument is not a
4247
@i{bit-wise logical operation specifier} or if any subsequent argument is not
4250
@subsubheading See Also::
4254
@subsubheading Notes::
4259
(boole boole-and x y) @equiv{} (logand x y)
4262
@i{Programmers} who would prefer to use numeric indices rather than
4263
@i{bit-wise logical operation specifiers} can get an equivalent effect
4264
by a technique such as the following:
4267
;; The order of the values in this `table' are such that
4268
;; (logand (boole (elt boole-n-vector n) #b0101 #b0011) #b1111) => n
4269
(defconstant boole-n-vector
4270
(vector boole-clr boole-and boole-andc1 boole-2
4271
boole-andc2 boole-1 boole-xor boole-ior
4272
boole-nor boole-eqv boole-c1 boole-orc1
4273
boole-c2 boole-orc2 boole-nand boole-set))
4274
@result{} BOOLE-N-VECTOR
4275
(proclaim '(inline boole-n))
4276
@result{} @i{implementation-dependent}
4277
(defun boole-n (n integer &rest more-integers)
4278
(apply #'boole (elt boole-n-vector n) integer more-integers))
4280
(boole-n #b0111 5 3) @result{} 7
4281
(boole-n #b0001 5 3) @result{} 1
4282
(boole-n #b1101 5 3) @result{} -3
4283
(loop for n from #b0000 to #b1111 collect (boole-n n 5 3))
4284
@result{} (0 1 2 3 4 5 6 7 -8 -7 -6 -5 -4 -3 -2 -1)
4287
@node boole-1, logand, boole, Numbers Dictionary
4288
@subsection boole-1, boole-2, boole-and, boole-andc1, boole-andc2,
4289
@subheading boole-c1, boole-c2, boole-clr, boole-eqv, boole-ior,
4290
@subheading boole-nand, boole-nor, boole-orc1, boole-orc2, boole-set,
4291
@subheading boole-xor
4293
@i{[Constant Variable]}
4296
@subsubheading Constant Value::
4298
The identity and nature of the @i{values} of each of these @i{variables}
4299
is @i{implementation-dependent},
4300
except that it must be @i{distinct} from each of the @i{values} of the others,
4301
and it must be a valid first @i{argument} to the @i{function} @b{boole}.
4303
@subsubheading Description::
4305
Each of these @i{constants} has a @i{value} which is one of the
4306
sixteen possible @i{bit-wise logical operation specifiers}.
4308
@subsubheading Examples::
4310
(boole boole-ior 1 16) @result{} 17
4311
(boole boole-and -2 5) @result{} 4
4312
(boole boole-eqv 17 15) @result{} -31
4315
@subsubheading See Also::
4319
@node logand, logbitp, boole-1, Numbers Dictionary
4320
@subsection logand, logandc1, logandc2, logeqv, logior,
4321
@subheading lognand, lognor, lognot, logorc1, logorc2,
4327
@code{logand} @i{@r{&rest} integers} @result{} @i{result-integer}
4329
@code{logandc} @i{1} @result{} @i{integer-1 integer-2}
4331
@code{logandc} @i{2} @result{} @i{integer-1 integer-2}
4333
@code{logeqv} @i{@r{&rest} integers} @result{} @i{result-integer}
4335
@code{logior} @i{@r{&rest} integers} @result{} @i{result-integer}
4337
@code{lognand} @i{integer-1 integer-2} @result{} @i{result-integer}
4339
@code{lognor} @i{integer-1 integer-2} @result{} @i{result-integer}
4341
@code{lognot} @i{integer} @result{} @i{result-integer}
4343
@code{logorc} @i{1} @result{} @i{integer-1 integer-2}
4345
@code{logorc} @i{2} @result{} @i{integer-1 integer-2}
4347
@code{logxor} @i{@r{&rest} integers} @result{} @i{result-integer}
4349
@subsubheading Arguments and Values::
4351
@i{integers}---@i{integers}.
4353
@i{integer}---an @i{integer}.
4355
@i{integer-1}---an @i{integer}.
4357
@i{integer-2}---an @i{integer}.
4359
@i{result-integer}---an @i{integer}.
4361
@subsubheading Description::
4375
perform bit-wise logical operations on their @i{arguments},
4376
that are treated as if they were binary.
4378
Figure 12--17 lists the meaning of each of the @i{functions}.
4379
Where an `identity' is shown, it indicates the @i{value} @i{yielded}
4380
by the @i{function} when no @i{arguments} are supplied.
4385
@w{ Function Identity Operation performed }
4386
@w{ @b{logandc1} --- and complement of @i{integer-1} with @i{integer-2} }
4387
@w{ @b{logandc2} --- and @i{integer-1} with complement of @i{integer-2} }
4388
@w{ @b{logand} @t{-1} and }
4389
@w{ @b{logeqv} @t{-1} equivalence (exclusive nor) }
4390
@w{ @b{logior} @t{0} inclusive or }
4391
@w{ @b{lognand} --- complement of @i{integer-1} and @i{integer-2} }
4392
@w{ @b{lognor} --- complement of @i{integer-1} or @i{integer-2} }
4393
@w{ @b{lognot} --- complement }
4394
@w{ @b{logorc1} --- or complement of @i{integer-1} with @i{integer-2} }
4395
@w{ @b{logorc2} --- or @i{integer-1} with complement of @i{integer-2} }
4396
@w{ @b{logxor} @t{0} exclusive or }
4399
@w{ Figure 12--17: Bit-wise Logical Operations on Integers }
4404
Negative @i{integers} are treated as if they were in two's-complement notation.
4406
@subsubheading Examples::
4409
(logior 1 2 4 8) @result{} 15
4410
(logxor 1 3 7 15) @result{} 10
4411
(logeqv) @result{} -1
4412
(logand 16 31) @result{} 16
4413
(lognot 0) @result{} -1
4414
(lognot 1) @result{} -2
4415
(lognot -1) @result{} 0
4416
(lognot (1+ (lognot 1000))) @result{} 999
4418
;;; In the following example, m is a mask. For each bit in
4419
;;; the mask that is a 1, the corresponding bits in x and y are
4420
;;; exchanged. For each bit in the mask that is a 0, the
4421
;;; corresponding bits of x and y are left unchanged.
4422
(flet ((show (m x y)
4429
(let ((z (logand (logxor x y) m)))
4430
(setq x (logxor z x))
4431
(setq y (logxor z y))
4433
@t{ |> } m = #o007750
4434
@t{ |> } x = #o452576
4435
@t{ |> } y = #o317407
4437
@t{ |> } m = #o007750
4438
@t{ |> } x = #o457426
4439
@t{ |> } y = #o312557
4443
@subsubheading Exceptional Situations::
4445
Should signal @b{type-error} if any argument is not an @i{integer}.
4447
@subsubheading See Also::
4451
@subsubheading Notes::
4453
@t{(logbitp @i{k} -1)} returns @i{true} for all values of @i{k}.
4455
Because the following functions are not associative,
4456
they take exactly two arguments rather than any number
4460
(lognand @i{n1} @i{n2}) @equiv{} (lognot (logand @i{n1} @i{n2}))
4461
(lognor @i{n1} @i{n2}) @equiv{} (lognot (logior @i{n1} @i{n2}))
4462
(logandc1 @i{n1} @i{n2}) @equiv{} (logand (lognot @i{n1}) @i{n2})
4463
(logandc2 @i{n1} @i{n2}) @equiv{} (logand @i{n1} (lognot @i{n2}))
4464
(logiorc1 @i{n1} @i{n2}) @equiv{} (logior (lognot @i{n1}) @i{n2})
4465
(logiorc2 @i{n1} @i{n2}) @equiv{} (logior @i{n1} (lognot @i{n2}))
4466
(logbitp @i{j} (lognot @i{x})) @equiv{} (not (logbitp @i{j} @i{x}))
4469
@node logbitp, logcount, logand, Numbers Dictionary
4470
@subsection logbitp [Function]
4472
@code{logbitp} @i{index integer} @result{} @i{generalized-boolean}
4474
@subsubheading Arguments and Values::
4476
@i{index}---a non-negative @i{integer}.
4478
@i{integer}---an @i{integer}.
4480
@i{generalized-boolean}---a @i{generalized boolean}.
4482
@subsubheading Description::
4484
@b{logbitp} is used to test the value of a particular bit
4485
in @i{integer}, that is treated as if it were binary.
4486
The value of @b{logbitp} is @i{true} if the bit in @i{integer}
4487
whose index is @i{index} (that is, its weight is 2^@i{index})
4488
is a one-bit; otherwise it is @i{false}.
4490
Negative @i{integers} are treated as if they were in
4491
two's-complement notation.
4493
@subsubheading Examples::
4495
(logbitp 1 1) @result{} @i{false}
4496
(logbitp 0 1) @result{} @i{true}
4497
(logbitp 3 10) @result{} @i{true}
4498
(logbitp 1000000 -1) @result{} @i{true}
4499
(logbitp 2 6) @result{} @i{true}
4500
(logbitp 0 6) @result{} @i{false}
4503
@subsubheading Exceptional Situations::
4505
Should signal an error of @i{type} @b{type-error}
4506
if @i{index} is not a non-negative @i{integer}.
4507
Should signal an error of @i{type} @b{type-error}
4508
if @i{integer} is not an @i{integer}.
4510
@subsubheading Notes::
4513
(logbitp @i{k} @i{n}) @equiv{} (ldb-test (byte 1 @i{k}) @i{n})
4516
@node logcount, logtest, logbitp, Numbers Dictionary
4517
@subsection logcount [Function]
4519
@code{logcount} @i{integer} @result{} @i{number-of-on-bits}
4521
@subsubheading Arguments and Values::
4523
@i{integer}---an @i{integer}.
4525
@i{number-of-on-bits}---a non-negative @i{integer}.
4527
@subsubheading Description::
4529
Computes and returns the number of bits
4530
in the two's-complement binary representation of @i{integer}
4531
that are `on' or `set'.
4532
If @i{integer} is negative, the @t{0} bits are counted;
4533
otherwise, the @t{1} bits are counted.
4535
@subsubheading Examples::
4538
(logcount 0) @result{} 0
4539
(logcount -1) @result{} 0
4540
(logcount 7) @result{} 3
4541
(logcount 13) @result{} 3 ;Two's-complement binary: ...0001101
4542
(logcount -13) @result{} 2 ;Two's-complement binary: ...1110011
4543
(logcount 30) @result{} 4 ;Two's-complement binary: ...0011110
4544
(logcount -30) @result{} 4 ;Two's-complement binary: ...1100010
4545
(logcount (expt 2 100)) @result{} 1
4546
(logcount (- (expt 2 100))) @result{} 100
4547
(logcount (- (1+ (expt 2 100)))) @result{} 1
4550
@subsubheading Exceptional Situations::
4552
Should signal @b{type-error} if its argument is not an @i{integer}.
4554
@subsubheading Notes::
4556
Even if the @i{implementation} does not represent @i{integers} internally
4557
in two's complement binary, @b{logcount} behaves as if it did.
4559
The following identity always holds:
4563
@equiv{} (logcount (- (+ @i{x} 1)))
4564
@equiv{} (logcount (lognot @i{x}))
4567
@node logtest, byte, logcount, Numbers Dictionary
4568
@subsection logtest [Function]
4570
@code{logtest} @i{integer-1 integer-2} @result{} @i{generalized-boolean}
4572
@subsubheading Arguments and Values::
4574
@i{integer-1}---an @i{integer}.
4576
@i{integer-2}---an @i{integer}.
4578
@i{generalized-boolean}---a @i{generalized boolean}.
4580
@subsubheading Description::
4582
Returns @i{true} if any of the bits designated by the 1's
4583
in @i{integer-1} is 1 in @i{integer-2};
4584
otherwise it is @i{false}.
4585
@i{integer-1} and @i{integer-2} are treated as if they were binary.
4587
Negative @i{integer-1} and @i{integer-2} are treated as if
4588
they were represented in two's-complement binary.
4590
@subsubheading Examples::
4593
(logtest 1 7) @result{} @i{true}
4594
(logtest 1 2) @result{} @i{false}
4595
(logtest -2 -1) @result{} @i{true}
4596
(logtest 0 -1) @result{} @i{false}
4599
@subsubheading Exceptional Situations::
4601
Should signal an error of @i{type} @b{type-error}
4602
if @i{integer-1} is not an @i{integer}.
4603
Should signal an error of @i{type} @b{type-error}
4604
if @i{integer-2} is not an @i{integer}.
4606
@subsubheading Notes::
4609
(logtest @i{x} @i{y}) @equiv{} (not (zerop (logand @i{x} @i{y})))
4612
@node byte, deposit-field, logtest, Numbers Dictionary
4613
@subsection byte, byte-size, byte-position [Function]
4615
@code{byte} @i{size position} @result{} @i{bytespec}
4617
@code{byte-size} @i{bytespec} @result{} @i{size}
4619
@code{byte-position} @i{bytespec} @result{} @i{position}
4621
@subsubheading Arguments and Values::
4623
@i{size}, @i{position}---a non-negative @i{integer}.
4625
@i{bytespec}---a @i{byte specifier}.
4627
@subsubheading Description::
4629
@b{byte} returns a @i{byte specifier} that indicates
4630
a @i{byte} of width @i{size} and whose bits have weights
4631
2^@i{@i{position} + @i{size} - 1\/} through 2^@i{position},
4632
and whose representation is
4633
@i{implementation-dependent}.
4635
@b{byte-size} returns the number of bits specified by @i{bytespec}.
4637
@b{byte-position} returns the position specified by @i{bytespec}.
4639
@subsubheading Examples::
4642
(setq b (byte 100 200)) @result{} #<BYTE-SPECIFIER size 100 position 200>
4643
(byte-size b) @result{} 100
4644
(byte-position b) @result{} 200
4647
@subsubheading See Also::
4653
@subsubheading Notes::
4656
(byte-size (byte @i{j} @i{k})) @equiv{} @i{j}
4657
(byte-position (byte @i{j} @i{k})) @equiv{} @i{k}
4660
A @i{byte} of @i{size} of @t{0} is permissible;
4661
it refers to a @i{byte} of width zero. For example,
4664
(ldb (byte 0 3) #o7777) @result{} 0
4665
(dpb #o7777 (byte 0 3) 0) @result{} 0
4668
@node deposit-field, dpb, byte, Numbers Dictionary
4669
@subsection deposit-field [Function]
4671
@code{deposit-field} @i{newbyte bytespec integer} @result{} @i{result-integer}
4673
@subsubheading Arguments and Values::
4675
@i{newbyte}---an @i{integer}.
4677
@i{bytespec}---a @i{byte specifier}.
4679
@i{integer}---an @i{integer}.
4681
@i{result-integer}---an @i{integer}.
4683
@subsubheading Description::
4685
Replaces a field of bits within @i{integer}; specifically,
4686
returns an @i{integer} that contains the bits of @i{newbyte}
4687
within the @i{byte} specified by @i{bytespec},
4688
and elsewhere contains the bits of @i{integer}.
4690
@subsubheading Examples::
4693
(deposit-field 7 (byte 2 1) 0) @result{} 6
4694
(deposit-field -1 (byte 4 0) 0) @result{} 15
4695
(deposit-field 0 (byte 2 1) -3) @result{} -7
4698
@subsubheading See Also::
4704
@subsubheading Notes::
4707
(logbitp @i{j} (deposit-field @i{m} (byte @i{s} @i{p}) @i{n}))
4708
@equiv{} (if (and (>= @i{j} @i{p}) (< @i{j} (+ @i{p} @i{s})))
4709
(logbitp @i{j} @i{m})
4710
(logbitp @i{j} @i{n}))
4713
@b{deposit-field} is to @b{mask-field}
4714
as @b{dpb} is to @b{ldb}.
4716
@node dpb, ldb, deposit-field, Numbers Dictionary
4717
@subsection dpb [Function]
4719
@code{dpb} @i{newbyte bytespec integer} @result{} @i{result-integer}
4721
@subsubheading Pronunciation::
4724
or pronounced ,de 'pe b
4725
or pronounced 'd\=e 'p\=e 'b\=e
4727
@subsubheading Arguments and Values::
4729
@i{newbyte}---an @i{integer}.
4731
@i{bytespec}---a @i{byte specifier}.
4733
@i{integer}---an @i{integer}.
4735
@i{result-integer}---an @i{integer}.
4737
@subsubheading Description::
4739
@b{dpb} (deposit byte) is used to
4740
replace a field of bits within @i{integer}.
4741
@b{dpb} returns an @i{integer} that is
4742
the same as @i{integer} except in the bits specified by @i{bytespec}.
4744
Let @t{s} be the size specified
4745
by @i{bytespec}; then the low @t{s} bits of @i{newbyte} appear in
4746
the result in the byte specified by @i{bytespec}.
4747
@i{Newbyte} is interpreted as
4748
being right-justified, as if it were the result of @b{ldb}.
4750
@subsubheading Examples::
4753
(dpb 1 (byte 1 10) 0) @result{} 1024
4754
(dpb -2 (byte 2 10) 0) @result{} 2048
4755
(dpb 1 (byte 2 10) 2048) @result{} 1024
4758
@subsubheading See Also::
4766
@subsubheading Notes::
4769
(logbitp @i{j} (dpb @i{m} (byte @i{s} @i{p}) @i{n}))
4770
@equiv{} (if (and (>= @i{j} @i{p}) (< @i{j} (+ @i{p} @i{s})))
4771
(logbitp (- @i{j} @i{p}) @i{m})
4772
(logbitp @i{j} @i{n}))
4778
(dpb @i{x} (byte 0 @i{y}) @i{z}) @result{} @i{z}
4781
for all valid values of @i{x}, @i{y}, and @i{z}.
4783
Historically, the name ``dpb'' comes from a DEC PDP-10 assembly language
4784
instruction meaning ``deposit byte.''
4786
@node ldb, ldb-test, dpb, Numbers Dictionary
4787
@subsection ldb [Accessor]
4789
@code{ldb} @i{bytespec integer} @result{} @i{byte}
4791
(setf (@code{ ldb} @i{bytespec place}) new-byte)@*
4793
@subsubheading Pronunciation::
4796
or pronounced 'lid e b
4797
or pronounced 'el 'd\=e 'b\=e
4799
@subsubheading Arguments and Values::
4801
@i{bytespec}---a @i{byte specifier}.
4803
@i{integer}---an @i{integer}.
4805
@i{byte}, @i{new-byte}---a non-negative @i{integer}.
4807
@subsubheading Description::
4809
@b{ldb} extracts and returns the @i{byte} of @i{integer}
4810
specified by @i{bytespec}.
4812
@b{ldb} returns an @i{integer} in which the bits with weights
4813
2^@i{(@i{s}-1)} through 2^0 are the same as those in
4814
@i{integer} with weights 2^@i{(@i{p}+@i{s}-1)}
4815
through 2^@i{p}, and all other bits zero; @i{s} is
4816
@t{(byte-size @i{bytespec})}
4817
and @i{p} is @t{(byte-position @i{bytespec})}.
4819
@b{setf} may be used with @b{ldb} to modify
4820
a byte within the @i{integer} that is stored
4821
in a given @i{place}.
4823
The order of evaluation, when an @b{ldb} form is supplied
4824
to @b{setf}, is exactly left-to-right.
4826
@ITindex{order of evaluation}
4828
@ITindex{evaluation order}
4830
The effect is to perform a @b{dpb} operation
4831
and then store the result back into the @i{place}.
4833
@subsubheading Examples::
4836
(ldb (byte 2 1) 10) @result{} 1
4837
(setq a (list 8)) @result{} (8)
4838
(setf (ldb (byte 2 1) (car a)) 1) @result{} 1
4842
@subsubheading See Also::
4850
@subsubheading Notes::
4853
(logbitp @i{j} (ldb (byte @i{s} @i{p}) @i{n}))
4854
@equiv{} (and (< @i{j} @i{s}) (logbitp (+ @i{j} @i{p}) @i{n}))
4860
(ldb (byte 0 @i{x}) @i{y}) @result{} 0
4863
for all valid values of @i{x} and @i{y}.
4865
Historically, the name ``ldb'' comes from a DEC PDP-10 assembly language
4866
instruction meaning ``load byte.''
4868
@node ldb-test, mask-field, ldb, Numbers Dictionary
4869
@subsection ldb-test [Function]
4871
@code{ldb-test} @i{bytespec integer} @result{} @i{generalized-boolean}
4873
@subsubheading Arguments and Values::
4875
@i{bytespec}---a @i{byte specifier}.
4877
@i{integer}---an @i{integer}.
4879
@i{generalized-boolean}---a @i{generalized boolean}.
4881
@subsubheading Description::
4883
Returns @i{true} if any of the bits of the byte in @i{integer}
4884
specified by @i{bytespec} is non-zero; otherwise returns @i{false}.
4886
@subsubheading Examples::
4889
(ldb-test (byte 4 1) 16) @result{} @i{true}
4890
(ldb-test (byte 3 1) 16) @result{} @i{false}
4891
(ldb-test (byte 3 2) 16) @result{} @i{true}
4894
@subsubheading See Also::
4902
@subsubheading Notes::
4904
(ldb-test bytespec n) @equiv{}
4905
(not (zerop (ldb bytespec n))) @equiv{}
4906
(logtest (ldb bytespec -1) n)
4909
@node mask-field, most-positive-fixnum, ldb-test, Numbers Dictionary
4910
@subsection mask-field [Accessor]
4912
@code{mask-field} @i{bytespec integer} @result{} @i{masked-integer}
4914
(setf (@code{ mask-field} @i{bytespec place}) new-masked-integer)@*
4916
@subsubheading Arguments and Values::
4918
@i{bytespec}---a @i{byte specifier}.
4920
@i{integer}---an @i{integer}.
4922
@i{masked-integer}, @i{new-masked-integer}---a non-negative @i{integer}.
4924
@subsubheading Description::
4926
@b{mask-field} performs a ``mask'' operation on @i{integer}.
4927
It returns an @i{integer} that has the same bits as @i{integer} in
4928
the @i{byte} specified by @i{bytespec}, but that has zero-bits everywhere else.
4930
@b{setf} may be used with @b{mask-field}
4931
to modify a byte within the @i{integer} that is stored
4932
in a given @i{place}.
4933
The effect is to perform a @b{deposit-field} operation
4934
and then store the result back into the @i{place}.
4936
@subsubheading Examples::
4939
(mask-field (byte 1 5) -1) @result{} 32
4940
(setq a 15) @result{} 15
4941
(mask-field (byte 2 0) a) @result{} 3
4943
(setf (mask-field (byte 2 0) a) 1) @result{} 1
4947
@subsubheading See Also::
4953
@subsubheading Notes::
4956
(ldb @i{bs} (mask-field @i{bs} @i{n})) @equiv{} (ldb @i{bs} @i{n})
4957
(logbitp @i{j} (mask-field (byte @i{s} @i{p}) @i{n}))
4958
@equiv{} (and (>= @i{j} @i{p}) (< @i{j} @i{s}) (logbitp @i{j} @i{n}))
4959
(mask-field @i{bs} @i{n}) @equiv{} (logand @i{n} (dpb -1 @i{bs} 0))
4962
@node most-positive-fixnum, decode-float, mask-field, Numbers Dictionary
4963
@subsection most-positive-fixnum, most-negative-fixnum [Constant Variable]
4965
@subsubheading Constant Value::
4967
@i{implementation-dependent}.
4969
@subsubheading Description::
4971
@b{most-positive-fixnum} is that @i{fixnum} closest in value
4972
to positive infinity provided by the implementation,
4974
and greater than or equal to both 2^@r{15} - 1 and
4975
@b{array-dimension-limit}.
4977
@b{most-negative-fixnum} is that @i{fixnum} closest in value
4978
to negative infinity provided by the implementation,
4980
and less than or equal to -2^@r{15}.
4982
@node decode-float, float, most-positive-fixnum, Numbers Dictionary
4983
@subsection decode-float, scale-float, float-radix, float-sign,
4984
@subheading float-digits, float-precision, integer-decode-float
4989
@code{decode-float} @i{float} @result{} @i{significand, exponent, sign}
4991
@code{scale-float} @i{float integer} @result{} @i{scaled-float}
4993
@code{float-radix} @i{float} @result{} @i{float-radix}
4995
@code{float-sign} @i{float-1 @r{&optional} float-2} @result{} @i{signed-float}
4997
@code{float-digits} @i{float} @result{} @i{digits1}
4999
@code{float-precision} @i{float} @result{} @i{digits2}
5001
@code{integer-decode-float} @i{float} @result{} @i{significand, exponent, integer-sign}
5003
@subsubheading Arguments and Values::
5005
@i{digits1}---a non-negative @i{integer}.
5007
@i{digits2}---a non-negative @i{integer}.
5009
@i{exponent}---an @i{integer}.
5011
@i{float}---a @i{float}.
5013
@i{float-1}---a @i{float}.
5015
@i{float-2}---a @i{float}.
5017
@i{float-radix}---an @i{integer}.
5019
@i{integer}---a non-negative @i{integer}.
5021
@i{integer-sign}---the @i{integer} @t{-1},
5022
or the @i{integer} @t{1}.
5024
@i{scaled-float}---a @i{float}.
5026
@i{sign}---A @i{float} of the same @i{type} as @i{float}
5027
but numerically equal to @t{1.0} or @t{-1.0}.
5029
@i{signed-float}---a @i{float}.
5031
@i{significand}---a @i{float}.
5033
@subsubheading Description::
5035
@b{decode-float} computes three values that characterize
5037
The first value is of the same @i{type}
5039
represents the significand.
5040
The second value represents the exponent
5041
to which the radix (notated in this description by @i{b}) must
5042
be raised to obtain the value that, when multiplied with the first
5043
result, produces the absolute value of @i{float}.
5044
If @i{float} is zero, any @i{integer} value may be returned,
5045
provided that the identity shown for @b{scale-float} holds.
5047
is of the same @i{type} as @i{float}
5048
and is 1.0 if @i{float} is greater
5049
than or equal to zero or -1.0 otherwise.
5052
divides @i{float} by an integral power of @i{b}
5053
so as to bring its value between 1/@i{b} (inclusive) and~1 (exclusive),
5054
and returns the quotient as the first value.
5055
If @i{float} is zero, however, the result
5056
equals the absolute value of @i{float} (that is, if there is a negative
5057
zero, its significand is considered to be a positive zero).
5059
@b{scale-float} returns
5060
@t{(* @i{float} (expt (float @i{b} @i{float})
5061
@i{integer}))\/}, where @i{b} is the radix of the floating-point
5062
representation. @i{float} is not necessarily between 1/@i{b} and~1.
5064
@b{float-radix} returns
5065
the radix of @i{float}.
5067
@b{float-sign} returns a number @t{z} such
5068
that @t{z} and @i{float-1} have the same sign and also such that
5069
@t{z} and @i{float-2} have the same absolute value.
5070
If @i{float-2} is not supplied, its value is @t{(float 1 @i{float-1})}.
5071
If an implementation
5072
has distinct representations for negative zero and positive zero,
5073
then @t{(float-sign -0.0)} @result{} @t{-1.0}.
5075
@b{float-digits} returns
5076
the number of radix @i{b} digits
5077
used in the representation of @i{float} (including any implicit
5078
digits, such as a ``hidden bit'').
5082
the number of significant radix @i{b} digits present in @i{float};
5083
if @i{float} is a @i{float}
5084
zero, then the result is an @i{integer} zero.
5086
For @i{normalized} @i{floats},
5087
the results of @b{float-digits} and @b{float-precision} are the same,
5088
but the precision is less than the number of representation digits
5089
for a @i{denormalized} or zero number.
5091
@b{integer-decode-float} computes three values that characterize
5093
the significand scaled so as to be an @i{integer},
5094
and the same last two
5095
values that are returned by @b{decode-float}.
5096
If @i{float} is zero, @b{integer-decode-float} returns
5097
zero as the first value.
5098
The second value bears the same relationship to the first value
5099
as for @b{decode-float}:
5102
(multiple-value-bind (signif expon sign)
5103
(integer-decode-float f)
5104
(scale-float (float signif f) expon)) @equiv{} (abs f)
5107
@subsubheading Examples::
5110
;; Note that since the purpose of this functionality is to expose
5111
;; details of the implementation, all of these examples are necessarily
5112
;; very implementation-dependent. Results may vary widely.
5113
;; Values shown here are chosen consistently from one particular implementation.
5114
(decode-float .5) @result{} 0.5, 0, 1.0
5115
(decode-float 1.0) @result{} 0.5, 1, 1.0
5116
(scale-float 1.0 1) @result{} 2.0
5117
(scale-float 10.01 -2) @result{} 2.5025
5118
(scale-float 23.0 0) @result{} 23.0
5119
(float-radix 1.0) @result{} 2
5120
(float-sign 5.0) @result{} 1.0
5121
(float-sign -5.0) @result{} -1.0
5122
(float-sign 0.0) @result{} 1.0
5123
(float-sign 1.0 0.0) @result{} 0.0
5124
(float-sign 1.0 -10.0) @result{} 10.0
5125
(float-sign -1.0 10.0) @result{} -10.0
5126
(float-digits 1.0) @result{} 24
5127
(float-precision 1.0) @result{} 24
5128
(float-precision least-positive-single-float) @result{} 1
5129
(integer-decode-float 1.0) @result{} 8388608, -23, 1
5132
@subsubheading Affected By::
5134
The implementation's representation for @i{floats}.
5136
@subsubheading Exceptional Situations::
5138
The functions @b{decode-float}, @b{float-radix}, @b{float-digits},
5139
@b{float-precision}, and @b{integer-decode-float} should signal an error
5140
if their only argument is not a @i{float}.
5142
The @i{function} @b{scale-float} should signal an error if its first argument
5143
is not a @i{float} or if its second argument is not an @i{integer}.
5145
The @i{function} @b{float-sign} should signal an error if its first argument
5146
is not a @i{float} or if its second argument is supplied but is
5149
@subsubheading Notes::
5151
The product of the first result of @b{decode-float} or @b{integer-decode-float},
5152
of the radix raised to the power of the second result, and of the third result
5153
is exactly equal to the value of @i{float}.
5156
(multiple-value-bind (signif expon sign)
5158
(scale-float signif expon))
5165
(multiple-value-bind (signif expon sign)
5167
(* (scale-float signif expon) sign))
5171
@node float, floatp, decode-float, Numbers Dictionary
5172
@subsection float [Function]
5174
@code{float} @i{number @r{&optional} prototype} @result{} @i{float}
5176
@subsubheading Arguments and Values::
5178
@i{number}---a @i{real}.
5180
@i{prototype}---a @i{float}.
5182
@i{float}---a @i{float}.
5184
@subsubheading Description::
5186
@b{float} converts a
5190
number to a @i{float}.
5192
If a @i{prototype} is supplied,
5193
a @i{float} is returned that is mathematically equal to @i{number}
5194
but has the same format as @i{prototype}.
5196
If @i{prototype} is not supplied,
5197
then if the @i{number} is already a @i{float}, it is returned;
5198
otherwise, a @i{float} is returned that is mathematically equal to @i{number}
5199
but is a @i{single float}.
5201
@subsubheading Examples::
5204
(float 0) @result{} 0.0
5205
(float 1 .5) @result{} 1.0
5206
(float 1.0) @result{} 1.0
5207
(float 1/2) @result{} 0.5
5210
(eql (float 1.0 1.0d0) 1.0d0) @result{} @i{true}
5213
@subsubheading See Also::
5217
@node floatp, most-positive-short-float, float, Numbers Dictionary
5218
@subsection floatp [Function]
5220
@code{floatp} @i{object}
5221
@r{generalized-boolean}
5223
@subsubheading Arguments and Values::
5225
@i{object}---an @i{object}.
5227
@i{generalized-boolean}---a @i{generalized boolean}.
5229
@subsubheading Description::
5231
Returns @i{true} if @i{object} is of @i{type} @b{float};
5232
otherwise, returns @i{false}.
5234
@subsubheading Examples::
5237
(floatp 1.2d2) @result{} @i{true}
5238
(floatp 1.212) @result{} @i{true}
5239
(floatp 1.2s2) @result{} @i{true}
5240
(floatp (expt 2 130)) @result{} @i{false}
5243
@subsubheading Notes::
5246
(floatp @i{object}) @equiv{} (typep @i{object} 'float)
5249
@node most-positive-short-float, short-float-epsilon, floatp, Numbers Dictionary
5250
@subsection most-positive-short-float, least-positive-short-float,
5251
@subheading least-positive-normalized-short-float,
5252
@subheading most-positive-double-float, least-positive-double-float,
5253
@subheading least-positive-normalized-double-float,
5254
@subheading most-positive-long-float, least-positive-long-float,
5255
@subheading least-positive-normalized-long-float,
5256
@subheading most-positive-single-float, least-positive-single-float,
5257
@subheading least-positive-normalized-single-float,
5258
@subheading most-negative-short-float, least-negative-short-float,
5259
@subheading least-negative-normalized-short-float,
5260
@subheading most-negative-single-float, least-negative-single-float,
5261
@subheading least-negative-normalized-single-float,
5262
@subheading most-negative-double-float, least-negative-double-float,
5263
@subheading least-negative-normalized-double-float,
5264
@subheading most-negative-long-float, least-negative-long-float,
5265
@subheading least-negative-normalized-long-float
5267
@i{[Constant Variable]}
5270
@subsubheading Constant Value::
5272
@i{implementation-dependent}.
5274
@subsubheading Description::
5276
These @i{constant variables} provide a way for programs to examine
5277
the @i{implementation-defined} limits for the various float formats.
5279
Of these @i{variables},
5280
each which has ``@t{-normalized}'' in its @i{name}
5281
must have a @i{value} which is a @i{normalized} @i{float}, and
5282
each which does not have ``@t{-normalized}'' in its name
5283
may have a @i{value} which is either a @i{normalized} @i{float}
5284
or a @i{denormalized} @i{float}, as appropriate.
5286
Of these @i{variables},
5287
each which has ``@t{short-float}'' in its name
5288
must have a @i{value} which is a @i{short float},
5289
each which has ``@t{single-float}'' in its name
5290
must have a @i{value} which is a @i{single float},
5291
each which has ``@t{double-float}'' in its name
5292
must have a @i{value} which is a @i{double float}, and
5293
each which has ``@t{long-float}'' in its name
5294
must have a @i{value} which is a @i{long float}.
5299
@b{most-positive-short-float},
5300
@b{most-positive-single-float},
5301
@b{most-positive-double-float},
5302
@b{most-positive-long-float}
5304
Each of these @i{constant variables} has as its @i{value}
5305
the positive @i{float} of the largest magnitude
5306
(closest in value to, but not equal to, positive infinity)
5307
for the float format implied by its name.
5310
@b{least-positive-short-float},
5311
@b{least-positive-normalized-short-float},
5312
@b{least-positive-single-float},
5313
@b{least-positive-normalized-single-float},
5314
@b{least-positive-double-float},
5315
@b{least-positive-normalized-double-float},
5316
@b{least-positive-long-float},
5317
@b{least-positive-normalized-long-float}
5319
Each of these @i{constant variables} has as its @i{value}
5320
the smallest positive (nonzero) @i{float}
5321
for the float format implied by its name.
5324
@b{least-negative-short-float},
5325
@b{least-negative-normalized-short-float},
5326
@b{least-negative-single-float},
5327
@b{least-negative-normalized-single-float},
5328
@b{least-negative-double-float},
5329
@b{least-negative-normalized-double-float},
5330
@b{least-negative-long-float},
5331
@b{least-negative-normalized-long-float}
5333
Each of these @i{constant variables} has as its @i{value}
5334
the negative (nonzero) @i{float} of the smallest magnitude
5335
for the float format implied by its name.
5336
(If an implementation supports minus zero as a @i{different}
5337
@i{object} from positive zero, this value must not be minus zero.)
5340
@b{most-negative-short-float},
5341
@b{most-negative-single-float},
5342
@b{most-negative-double-float},
5343
@b{most-negative-long-float}
5345
Each of these @i{constant variables} has as its @i{value}
5346
the negative @i{float} of the largest magnitude
5347
(closest in value to, but not equal to, negative infinity)
5348
for the float format implied by its name.
5352
@subsubheading Notes::
5354
@node short-float-epsilon, arithmetic-error, most-positive-short-float, Numbers Dictionary
5355
@subsection short-float-epsilon, short-float-negative-epsilon,
5356
@subheading single-float-epsilon, single-float-negative-epsilon,
5357
@subheading double-float-epsilon, double-float-negative-epsilon,
5358
@subheading long-float-epsilon, long-float-negative-epsilon
5360
@i{[Constant Variable]}
5363
@subsubheading Constant Value::
5365
@i{implementation-dependent}.
5367
@subsubheading Description::
5369
The value of each of the constants @b{short-float-epsilon},
5370
@b{single-float-epsilon},
5371
@b{double-float-epsilon}, and @b{long-float-epsilon} is
5372
the smallest positive @i{float} \epsilon of the given format,
5373
such that the following expression is @i{true} when evaluated:
5375
@t{(not (= (float 1 \epsilon) (+ (float 1 \epsilon) \epsilon)))\/}
5377
The value of each of the constants @b{short-float-negative-epsilon},
5378
@b{single-float-negative-epsilon},
5379
@b{double-float-negative-epsilon}, and
5380
@b{long-float-negative-epsilon} is the smallest positive
5381
@i{float} \epsilon of the given format, such that the following
5382
expression is @i{true} when evaluated:
5384
@t{(not (= (float 1 \epsilon) (- (float 1 \epsilon) \epsilon)))\/}
5386
@node arithmetic-error, arithmetic-error-operands, short-float-epsilon, Numbers Dictionary
5387
@subsection arithmetic-error [Condition Type]
5389
@subsubheading Class Precedence List::
5390
@b{arithmetic-error},
5392
@b{serious-condition},
5396
@subsubheading Description::
5398
The @i{type} @b{arithmetic-error} consists of error conditions
5399
that occur during arithmetic operations.
5400
The operation and operands are initialized with
5401
the initialization arguments named @t{:operation} and @t{:operands} to @b{make-condition},
5402
and are @i{accessed} by
5403
the functions @b{arithmetic-error-operation} and
5404
@b{arithmetic-error-operands}.
5406
@subsubheading See Also::
5408
@b{arithmetic-error-operation},
5409
@ref{arithmetic-error-operands}
5411
@node arithmetic-error-operands, division-by-zero, arithmetic-error, Numbers Dictionary
5412
@subsection arithmetic-error-operands, arithmetic-error-operation [Function]
5414
@code{arithmetic-error-operands} @i{condition} @result{} @i{operands}
5416
@code{arithmetic-error-operation} @i{condition} @result{} @i{operation}
5418
@subsubheading Arguments and Values::
5420
@i{condition}---a @i{condition} of @i{type} @b{arithmetic-error}.
5422
@i{operands}---a @i{list}.
5424
@i{operation}---a @i{function designator}.
5426
@subsubheading Description::
5428
@b{arithmetic-error-operands} returns a @i{list} of the operands
5429
which were used in the offending call to the operation that signaled
5432
@b{arithmetic-error-operation} returns a @i{list} of
5433
the offending operation in the offending call that signaled the @i{condition}.
5435
@subsubheading See Also::
5437
@b{arithmetic-error},
5440
@subsubheading Notes::
5442
@node division-by-zero, floating-point-invalid-operation, arithmetic-error-operands, Numbers Dictionary
5443
@subsection division-by-zero [Condition Type]
5445
@subsubheading Class Precedence List::
5446
@b{division-by-zero},
5447
@b{arithmetic-error},
5449
@b{serious-condition},
5453
@subsubheading Description::
5455
The @i{type} @b{division-by-zero} consists of error conditions that
5456
occur because of division by zero.
5458
@node floating-point-invalid-operation, floating-point-inexact, division-by-zero, Numbers Dictionary
5459
@subsection floating-point-invalid-operation [Condition Type]
5461
@subsubheading Class Precedence List::
5462
@b{floating-point-invalid-operation},
5463
@b{arithmetic-error},
5465
@b{serious-condition},
5469
@subsubheading Description::
5471
The @i{type} @b{floating-point-invalid-operation} consists of
5472
error conditions that occur because of certain
5473
floating point traps.
5475
It is @i{implementation-dependent} whether floating point traps
5476
occur, and whether or how they may be enabled or disabled. Therefore,
5477
conforming code may establish handlers for this condition, but must not
5478
depend on its being @i{signaled}.
5480
@node floating-point-inexact, floating-point-overflow, floating-point-invalid-operation, Numbers Dictionary
5481
@subsection floating-point-inexact [Condition Type]
5483
@subsubheading Class Precedence List::
5484
@b{floating-point-inexact},
5485
@b{arithmetic-error},
5487
@b{serious-condition},
5491
@subsubheading Description::
5493
The @i{type} @b{floating-point-inexact} consists of
5494
error conditions that occur because of certain
5495
floating point traps.
5497
It is @i{implementation-dependent} whether floating point traps
5498
occur, and whether or how they may be enabled or disabled. Therefore,
5499
conforming code may establish handlers for this condition, but must not
5500
depend on its being @i{signaled}.
5502
@node floating-point-overflow, floating-point-underflow, floating-point-inexact, Numbers Dictionary
5503
@subsection floating-point-overflow [Condition Type]
5505
@subsubheading Class Precedence List::
5506
@b{floating-point-overflow},
5507
@b{arithmetic-error},
5509
@b{serious-condition},
5513
@subsubheading Description::
5515
The @i{type} @b{floating-point-overflow} consists of error
5516
conditions that occur because of floating-point overflow.
5518
@node floating-point-underflow, , floating-point-overflow, Numbers Dictionary
5519
@subsection floating-point-underflow [Condition Type]
5521
@subsubheading Class Precedence List::
5522
@b{floating-point-underflow},
5523
@b{arithmetic-error},
5525
@b{serious-condition},
5529
@subsubheading Description::
5531
The @i{type} @b{floating-point-underflow} consists of
5532
error conditions that occur because of floating-point underflow.
5534
@c end of including dict-numbers
5536
@c %**end of chapter
added
removed
info/chap-12.texi
