@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2003
@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/numbers
@section Integer Basics
The range of values for an integer depends on the machine. The
-minimum range is @minus{}134217728 to 134217727 (28 bits; i.e.,
+minimum range is @minus{}268435456 to 268435455 (29 bits; i.e.,
@ifnottex
--2**27
+-2**28
@end ifnottex
@tex
-@math{-2^{27}}
+@math{-2^{28}}
@end tex
to
@ifnottex
-2**27 - 1),
+2**28 - 1),
@end ifnottex
@tex
-@math{2^{27}-1}),
+@math{2^{28}-1}),
@end tex
but some machines may provide a wider range. Many examples in this
-chapter assume an integer has 28 bits.
+chapter assume an integer has 29 bits.
@cindex overflow
The Lisp reader reads an integer as a sequence of digits with optional
1. ; @r{The integer 1.}
+1 ; @r{Also the integer 1.}
-1 ; @r{The integer @minus{}1.}
- 268435457 ; @r{Also the integer 1, due to overflow.}
+ 536870913 ; @r{Also the integer 1, due to overflow.}
0 ; @r{The integer 0.}
-0 ; @r{The integer 0.}
@end example
@cindex hex numbers
@cindex octal numbers
@cindex reading numbers in hex, octal, and binary
- In addition, the Lisp reader recognizes a syntax for integers in
-bases other than 10: @samp{#B@var{integer}} reads @var{integer} in
-binary (radix 2), @samp{#O@var{integer}} reads @var{integer} in octal
-(radix 8), @samp{#X@var{integer}} reads @var{integer} in hexadecimal
-(radix 16), and @samp{#@var{radix}r@var{integer}} reads @var{integer}
-in radix @var{radix} (where @var{radix} is between 2 and 36,
-inclusively). Case is not significant for the letter after @samp{#}
-(@samp{B}, @samp{O}, etc.) that denotes the radix.
+ The syntax for integers in bases other than 10 uses @samp{#}
+followed by a letter that specifies the radix: @samp{b} for binary,
+@samp{o} for octal, @samp{x} for hex, or @samp{@var{radix}r} to
+specify radix @var{radix}. Case is not significant for the letter
+that specifies the radix. Thus, @samp{#b@var{integer}} reads
+@var{integer} in binary, and @samp{#@var{radix}r@var{integer}} reads
+@var{integer} in radix @var{radix}. Allowed values of @var{radix} run
+from 2 to 36. For example:
+
+@example
+#b101100 @result{} 44
+#o54 @result{} 44
+#x2c @result{} 44
+#24r1k @result{} 44
+@end example
To understand how various functions work on integers, especially the
bitwise operators (@pxref{Bitwise Operations}), it is often helpful to
view the numbers in their binary form.
- In 28-bit binary, the decimal integer 5 looks like this:
+ In 29-bit binary, the decimal integer 5 looks like this:
@example
-0000 0000 0000 0000 0000 0000 0101
+0 0000 0000 0000 0000 0000 0000 0101
@end example
@noindent
The integer @minus{}1 looks like this:
@example
-1111 1111 1111 1111 1111 1111 1111
+1 1111 1111 1111 1111 1111 1111 1111
@end example
@noindent
@cindex two's complement
-@minus{}1 is represented as 28 ones. (This is called @dfn{two's
+@minus{}1 is represented as 29 ones. (This is called @dfn{two's
complement} notation.)
The negative integer, @minus{}5, is creating by subtracting 4 from
@minus{}5 looks like this:
@example
-1111 1111 1111 1111 1111 1111 1011
+1 1111 1111 1111 1111 1111 1111 1011
@end example
- In this implementation, the largest 28-bit binary integer value is
-134,217,727 in decimal. In binary, it looks like this:
+ In this implementation, the largest 29-bit binary integer value is
+268,435,455 in decimal. In binary, it looks like this:
@example
-0111 1111 1111 1111 1111 1111 1111
+0 1111 1111 1111 1111 1111 1111 1111
@end example
Since the arithmetic functions do not check whether integers go
-outside their range, when you add 1 to 134,217,727, the value is the
-negative integer @minus{}134,217,728:
+outside their range, when you add 1 to 268,435,455, the value is the
+negative integer @minus{}268,435,456:
@example
-(+ 1 134217727)
- @result{} -134217728
- @result{} 1000 0000 0000 0000 0000 0000 0000
+(+ 1 268435455)
+ @result{} -268435456
+ @result{} 1 0000 0000 0000 0000 0000 0000 0000
@end example
Many of the functions described in this chapter accept markers for
value is 1500. They are all equivalent. You can also use a minus sign
to write negative floating point numbers, as in @samp{-1.0}.
-@cindex IEEE floating point
+@cindex @acronym{IEEE} floating point
@cindex positive infinity
@cindex negative infinity
@cindex infinity
@cindex NaN
- Most modern computers support the IEEE floating point standard, which
-provides for positive infinity and negative infinity as floating point
+ Most modern computers support the @acronym{IEEE} floating point standard,
+which provides for positive infinity and negative infinity as floating point
values. It also provides for a class of values called NaN or
``not-a-number''; numerical functions return such values in cases where
-there is no correct answer. For example, @code{(sqrt -1.0)} returns a
+there is no correct answer. For example, @code{(/ 0.0 0.0)} returns a
NaN. For practical purposes, there's no significant difference between
different NaN values in Emacs Lisp, and there's no rule for precisely
which NaN value should be used in a particular case, so Emacs Lisp
@end table
In addition, the value @code{-0.0} is distinguishable from ordinary
-zero in IEEE floating point (although @code{equal} and @code{=} consider
-them equal values).
+zero in @acronym{IEEE} floating point (although @code{equal} and
+@code{=} consider them equal values).
You can use @code{logb} to extract the binary exponent of a floating
point number (or estimate the logarithm of an integer):
@node Predicates on Numbers
@section Type Predicates for Numbers
- The functions in this section test whether the argument is a number or
-whether it is a certain sort of number. The functions @code{integerp}
-and @code{floatp} can take any type of Lisp object as argument (the
-predicates would not be of much use otherwise); but the @code{zerop}
-predicate requires a number as its argument. See also
-@code{integer-or-marker-p} and @code{number-or-marker-p}, in
-@ref{Predicates on Markers}.
+ The functions in this section test for numbers, or for a specific
+type of number. The functions @code{integerp} and @code{floatp} can
+take any type of Lisp object as argument (they would not be of much
+use otherwise), but the @code{zerop} predicate requires a number as
+its argument. See also @code{integer-or-marker-p} and
+@code{number-or-marker-p}, in @ref{Predicates on Markers}.
@defun floatp object
This predicate tests whether its argument is a floating point
This predicate tests whether its argument is zero, and returns @code{t}
if so, @code{nil} otherwise. The argument must be a number.
-These two forms are equivalent: @code{(zerop x)} @equiv{} @code{(= x 0)}.
+@code{(zerop x)} is equivalent to @code{(= x 0)}.
@end defun
@node Comparison of Numbers
can, even for comparing integers, just in case we change the
representation of integers in a future Emacs version.
- Sometimes it is useful to compare numbers with @code{equal}; it treats
-two numbers as equal if they have the same data type (both integers, or
-both floating point) and the same value. By contrast, @code{=} can
-treat an integer and a floating point number as equal.
+ Sometimes it is useful to compare numbers with @code{equal}; it
+treats two numbers as equal if they have the same data type (both
+integers, or both floating point) and the same value. By contrast,
+@code{=} can treat an integer and a floating point number as equal.
+@xref{Equality Predicates}.
There is another wrinkle: because floating point arithmetic is not
exact, it is often a bad idea to check for equality of two floating
returns @code{t} if so, @code{nil} otherwise.
@end defun
+@defun eql value1 value2
+This function acts like @code{eq} except when both arguments are
+numbers. It compares numbers by type and numberic value, so that
+@code{(eql 1.0 1)} returns @code{nil}, but @code{(eql 1.0 1.0)} and
+@code{(eql 1 1)} both return @code{t}.
+@end defun
+
@defun /= number-or-marker1 number-or-marker2
This function tests whether its arguments are numerically equal, and
returns @code{t} if they are not, and @code{nil} if they are.
@defun max number-or-marker &rest numbers-or-markers
This function returns the largest of its arguments.
-If any of the argument is floating-point, the value is returned
+If any of the arguments is floating-point, the value is returned
as floating point, even if it was given as an integer.
@example
@defun min number-or-marker &rest numbers-or-markers
This function returns the smallest of its arguments.
-If any of the argument is floating-point, the value is returned
+If any of the arguments is floating-point, the value is returned
as floating point, even if it was given as an integer.
@example
@end defun
There are four functions to convert floating point numbers to integers;
-they differ in how they round. These functions accept integer arguments
-also, and return such arguments unchanged.
-
-@defun truncate number
+they differ in how they round. All accept an argument @var{number}
+and an optional argument @var{divisor}. Both arguments may be
+integers or floating point numbers. @var{divisor} may also be
+@code{nil}. If @var{divisor} is @code{nil} or omitted, these
+functions convert @var{number} to an integer, or return it unchanged
+if it already is an integer. If @var{divisor} is non-@code{nil}, they
+divide @var{number} by @var{divisor} and convert the result to an
+integer. An @code{arith-error} results if @var{divisor} is 0.
+
+@defun truncate number &optional divisor
This returns @var{number}, converted to an integer by rounding towards
zero.
This returns @var{number}, converted to an integer by rounding downward
(towards negative infinity).
-If @var{divisor} is specified, @code{floor} divides @var{number} by
-@var{divisor} and then converts to an integer; this uses the kind of
-division operation that corresponds to @code{mod}, rounding downward.
-An @code{arith-error} results if @var{divisor} is 0.
+If @var{divisor} is specified, this uses the kind of division
+operation that corresponds to @code{mod}, rounding downward.
@example
(floor 1.2)
@end example
@end defun
-@defun ceiling number
+@defun ceiling number &optional divisor
This returns @var{number}, converted to an integer by rounding upward
(towards positive infinity).
@end example
@end defun
-@defun round number
+@defun round number &optional divisor
This returns @var{number}, converted to an integer by rounding towards the
nearest integer. Rounding a value equidistant between two integers
may choose the integer closer to zero, or it may prefer an even integer,
if any argument is floating.
It is important to note that in Emacs Lisp, arithmetic functions
-do not check for overflow. Thus @code{(1+ 134217727)} may evaluate to
-@minus{}134217728, depending on your hardware.
+do not check for overflow. Thus @code{(1+ 268435455)} may evaluate to
+@minus{}268435456, depending on your hardware.
@defun 1+ number-or-marker
This function returns @var{number-or-marker} plus 1.
@cindex @code{arith-error} in division
If you divide an integer by 0, an @code{arith-error} error is signaled.
(@xref{Errors}.) Floating point division by zero returns either
-infinity or a NaN if your machine supports IEEE floating point;
+infinity or a NaN if your machine supports @acronym{IEEE} floating point;
otherwise, it signals an @code{arith-error} error.
@example
The function @code{lsh}, like all Emacs Lisp arithmetic functions, does
not check for overflow, so shifting left can discard significant bits
and change the sign of the number. For example, left shifting
-134,217,727 produces @minus{}2 on a 28-bit machine:
+268,435,455 produces @minus{}2 on a 29-bit machine:
@example
-(lsh 134217727 1) ; @r{left shift}
+(lsh 268435455 1) ; @r{left shift}
@result{} -2
@end example
-In binary, in the 28-bit implementation, the argument looks like this:
+In binary, in the 29-bit implementation, the argument looks like this:
@example
@group
-;; @r{Decimal 134,217,727}
-0111 1111 1111 1111 1111 1111 1111
+;; @r{Decimal 268,435,455}
+0 1111 1111 1111 1111 1111 1111 1111
@end group
@end example
@example
@group
;; @r{Decimal @minus{}2}
-1111 1111 1111 1111 1111 1111 1110
+1 1111 1111 1111 1111 1111 1111 1110
@end group
@end example
@end defun
@group
(ash -6 -1) @result{} -3
;; @r{Decimal @minus{}6 becomes decimal @minus{}3.}
-1111 1111 1111 1111 1111 1111 1010
+1 1111 1111 1111 1111 1111 1111 1010
@result{}
-1111 1111 1111 1111 1111 1111 1101
+1 1111 1111 1111 1111 1111 1111 1101
@end group
@end example
@example
@group
-(lsh -6 -1) @result{} 134217725
-;; @r{Decimal @minus{}6 becomes decimal 134,217,725.}
-1111 1111 1111 1111 1111 1111 1010
+(lsh -6 -1) @result{} 268435453
+;; @r{Decimal @minus{}6 becomes decimal 268,435,453.}
+1 1111 1111 1111 1111 1111 1111 1010
@result{}
-0111 1111 1111 1111 1111 1111 1101
+0 1111 1111 1111 1111 1111 1111 1101
@end group
@end example
@c with smallbook but not with regular book! --rjc 16mar92
@smallexample
@group
- ; @r{ 28-bit binary values}
+ ; @r{ 29-bit binary values}
-(lsh 5 2) ; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
- @result{} 20 ; = @r{0000 0000 0000 0000 0000 0001 0100}
+(lsh 5 2) ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101}
+ @result{} 20 ; = @r{0 0000 0000 0000 0000 0000 0001 0100}
@end group
@group
(ash 5 2)
@result{} 20
-(lsh -5 2) ; -5 = @r{1111 1111 1111 1111 1111 1111 1011}
- @result{} -20 ; = @r{1111 1111 1111 1111 1111 1110 1100}
+(lsh -5 2) ; -5 = @r{1 1111 1111 1111 1111 1111 1111 1011}
+ @result{} -20 ; = @r{1 1111 1111 1111 1111 1111 1110 1100}
(ash -5 2)
@result{} -20
@end group
@group
-(lsh 5 -2) ; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
- @result{} 1 ; = @r{0000 0000 0000 0000 0000 0000 0001}
+(lsh 5 -2) ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101}
+ @result{} 1 ; = @r{0 0000 0000 0000 0000 0000 0000 0001}
@end group
@group
(ash 5 -2)
@result{} 1
@end group
@group
-(lsh -5 -2) ; -5 = @r{1111 1111 1111 1111 1111 1111 1011}
- @result{} 4194302 ; = @r{0011 1111 1111 1111 1111 1111 1110}
+(lsh -5 -2) ; -5 = @r{1 1111 1111 1111 1111 1111 1111 1011}
+ @result{} 134217726 ; = @r{0 0111 1111 1111 1111 1111 1111 1110}
@end group
@group
-(ash -5 -2) ; -5 = @r{1111 1111 1111 1111 1111 1111 1011}
- @result{} -2 ; = @r{1111 1111 1111 1111 1111 1111 1110}
+(ash -5 -2) ; -5 = @r{1 1111 1111 1111 1111 1111 1111 1011}
+ @result{} -2 ; = @r{1 1111 1111 1111 1111 1111 1111 1110}
@end group
@end smallexample
@end defun
@smallexample
@group
- ; @r{ 28-bit binary values}
+ ; @r{ 29-bit binary values}
-(logand 14 13) ; 14 = @r{0000 0000 0000 0000 0000 0000 1110}
- ; 13 = @r{0000 0000 0000 0000 0000 0000 1101}
- @result{} 12 ; 12 = @r{0000 0000 0000 0000 0000 0000 1100}
+(logand 14 13) ; 14 = @r{0 0000 0000 0000 0000 0000 0000 1110}
+ ; 13 = @r{0 0000 0000 0000 0000 0000 0000 1101}
+ @result{} 12 ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100}
@end group
@group
-(logand 14 13 4) ; 14 = @r{0000 0000 0000 0000 0000 0000 1110}
- ; 13 = @r{0000 0000 0000 0000 0000 0000 1101}
- ; 4 = @r{0000 0000 0000 0000 0000 0000 0100}
- @result{} 4 ; 4 = @r{0000 0000 0000 0000 0000 0000 0100}
+(logand 14 13 4) ; 14 = @r{0 0000 0000 0000 0000 0000 0000 1110}
+ ; 13 = @r{0 0000 0000 0000 0000 0000 0000 1101}
+ ; 4 = @r{0 0000 0000 0000 0000 0000 0000 0100}
+ @result{} 4 ; 4 = @r{0 0000 0000 0000 0000 0000 0000 0100}
@end group
@group
(logand)
- @result{} -1 ; -1 = @r{1111 1111 1111 1111 1111 1111 1111}
+ @result{} -1 ; -1 = @r{1 1111 1111 1111 1111 1111 1111 1111}
@end group
@end smallexample
@end defun
@smallexample
@group
- ; @r{ 28-bit binary values}
+ ; @r{ 29-bit binary values}
-(logior 12 5) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100}
- ; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
- @result{} 13 ; 13 = @r{0000 0000 0000 0000 0000 0000 1101}
+(logior 12 5) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100}
+ ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101}
+ @result{} 13 ; 13 = @r{0 0000 0000 0000 0000 0000 0000 1101}
@end group
@group
-(logior 12 5 7) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100}
- ; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
- ; 7 = @r{0000 0000 0000 0000 0000 0000 0111}
- @result{} 15 ; 15 = @r{0000 0000 0000 0000 0000 0000 1111}
+(logior 12 5 7) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100}
+ ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101}
+ ; 7 = @r{0 0000 0000 0000 0000 0000 0000 0111}
+ @result{} 15 ; 15 = @r{0 0000 0000 0000 0000 0000 0000 1111}
@end group
@end smallexample
@end defun
@smallexample
@group
- ; @r{ 28-bit binary values}
+ ; @r{ 29-bit binary values}
-(logxor 12 5) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100}
- ; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
- @result{} 9 ; 9 = @r{0000 0000 0000 0000 0000 0000 1001}
+(logxor 12 5) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100}
+ ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101}
+ @result{} 9 ; 9 = @r{0 0000 0000 0000 0000 0000 0000 1001}
@end group
@group
-(logxor 12 5 7) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100}
- ; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
- ; 7 = @r{0000 0000 0000 0000 0000 0000 0111}
- @result{} 14 ; 14 = @r{0000 0000 0000 0000 0000 0000 1110}
+(logxor 12 5 7) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100}
+ ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101}
+ ; 7 = @r{0 0000 0000 0000 0000 0000 0000 0111}
+ @result{} 14 ; 14 = @r{0 0000 0000 0000 0000 0000 0000 1110}
@end group
@end smallexample
@end defun
@example
(lognot 5)
@result{} -6
-;; 5 = @r{0000 0000 0000 0000 0000 0000 0101}
+;; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101}
;; @r{becomes}
-;; -6 = @r{1111 1111 1111 1111 1111 1111 1010}
+;; -6 = @r{1 1111 1111 1111 1111 1111 1111 1010}
@end example
@end defun
@tex
@math{\pi/2}
@end tex
-(inclusive) whose sine is @var{arg}; if, however, @var{arg}
-is out of range (outside [-1, 1]), then the result is a NaN.
+(inclusive) whose sine is @var{arg}; if, however, @var{arg} is out of
+range (outside [-1, 1]), it signals a @code{domain-error} error.
@end defun
@defun acos arg
@tex
@math{\pi}
@end tex
-(inclusive) whose cosine is @var{arg}; if, however, @var{arg}
-is out of range (outside [-1, 1]), then the result is a NaN.
+(inclusive) whose cosine is @var{arg}; if, however, @var{arg} is out
+of range (outside [-1, 1]), it signals a @code{domain-error} error.
@end defun
@defun atan y &optional x
@ifnottex
@i{e}
@end ifnottex
-is used. If @var{arg}
-is negative, the result is a NaN.
+is used. If @var{arg} is negative, it signals a @code{domain-error}
+error.
@end defun
@ignore
@defun log10 arg
This function returns the logarithm of @var{arg}, with base 10. If
-@var{arg} is negative, the result is a NaN. @code{(log10 @var{x})}
-@equiv{} @code{(log @var{x} 10)}, at least approximately.
+@var{arg} is negative, it signals a @code{domain-error} error.
+@code{(log10 @var{x})} @equiv{} @code{(log @var{x} 10)}, at least
+approximately.
@end defun
@defun expt x y
This function returns @var{x} raised to power @var{y}. If both
arguments are integers and @var{y} is positive, the result is an
-integer; in this case, it is truncated to fit the range of possible
-integer values.
+integer; in this case, overflow causes truncation, so watch out.
@end defun
@defun sqrt arg
This returns the square root of @var{arg}. If @var{arg} is negative,
-the value is a NaN.
+it signals a @code{domain-error} error.
@end defun
@node Random Numbers
If you want random numbers that don't always come out the same, execute
@code{(random t)}. This chooses a new seed based on the current time of
-day and on Emacs's process @sc{id} number.
+day and on Emacs's process @acronym{ID} number.
@defun random &optional limit
This function returns a pseudo-random integer. Repeated calls return a
nonnegative and less than @var{limit}.
If @var{limit} is @code{t}, it means to choose a new seed based on the
-current time of day and on Emacs's process @sc{id} number.
+current time of day and on Emacs's process @acronym{ID} number.
@c "Emacs'" is incorrect usage!
On some machines, any integer representable in Lisp may be the result