@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2003
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003,
+@c 2004, 2005, 2006 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/numbers
@node Numbers, Strings and Characters, Lisp Data Types, Top
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
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
-doesn't try to distinguish them. Here are the read syntaxes for
-these special floating point values:
+doesn't try to distinguish them (but it does report the sign, if you
+print it). Here are the read syntaxes for these special floating
+point values:
@table @asis
@item positive infinity
@samp{1.0e+INF}
@item negative infinity
@samp{-1.0e+INF}
-@item Not-a-number
-@samp{0.0e+NaN}.
+@item Not-a-number
+@samp{0.0e+NaN} or @samp{-0.0e+NaN}.
@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).
+ To test whether a floating point value is a NaN, compare it with
+itself using @code{=}. That returns @code{nil} for a NaN, and
+@code{t} for any other floating point value.
+
+ The value @code{-0.0} is distinguishable from ordinary zero in
+@acronym{IEEE} floating point, but Emacs Lisp @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 numeric 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,
@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
@result{} 2.5
(/ 25 3 2)
@result{} 4
+@group
(/ -17 6)
- @result{} -2
+ @result{} -2 @r{(could in theory be @minus{}3 on some machines)}
+@end group
@end example
-
-The result of @code{(/ -17 6)} could in principle be -3 on some
-machines.
@end defun
@defun % dividend divisor
sequence of @dfn{bits} (digits which are either zero or one). A bitwise
operation acts on the individual bits of such a sequence. For example,
@dfn{shifting} moves the whole sequence left or right one or more places,
-reproducing the same pattern ``moved over''.
+reproducing the same pattern ``moved over.''
The bitwise operations in Emacs Lisp apply only to integers.
@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