@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 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
@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.,
-@ifinfo
--2**27
-@end ifinfo
-@tex
-$-2^{27}$
+minimum range is @minus{}268435456 to 268435455 (29 bits; i.e.,
+@ifnottex
+-2**28
+@end ifnottex
+@tex
+@math{-2^{28}}
@end tex
-to
-@ifinfo
-2**27 - 1),
-@end ifinfo
-@tex
-$2^{27}-1$),
+to
+@ifnottex
+2**28 - 1),
+@end ifnottex
+@tex
+@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 integers in specific radix
+@cindex radix for reading an integer
+@cindex base for reading an integer
+@cindex hex numbers
+@cindex octal numbers
+@cindex reading numbers in hex, octal, and binary
+ 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
give these arguments the name @var{number-or-marker}. When the argument
value is a marker, its position value is used and its buffer is ignored.
+@defvar most-positive-fixnum
+The value of this variable is the largest integer that Emacs Lisp
+can handle.
+@end defvar
+
+@defvar most-negative-fixnum
+The value of this variable is the smallest integer that Emacs Lisp can
+handle. It is negative.
+@end defvar
+
@node Float Basics
@section Floating Point Basics
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.
+@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
point values. Usually it is better to test for approximate equality.
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 arguments is floating-point, the value is returned
+as floating point, even if it was given as an integer.
@example
(max 20)
(max 1 2.5)
@result{} 2.5
(max 1 3 2.5)
- @result{} 3
+ @result{} 3.0
@end example
@end defun
@defun min number-or-marker &rest numbers-or-markers
This function returns the smallest of its arguments.
+If any of the arguments is floating-point, the value is returned
+as floating point, even if it was given as an integer.
@example
(min -4 1)
@end defun
@defun abs number
-This returns the absolute value of @var{number}.
+This function returns the absolute value of @var{number}.
@end defun
@node Numeric Conversions
@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.
+
+@example
+(truncate 1.2)
+ @result{} 1
+(truncate 1.7)
+ @result{} 1
+(truncate -1.2)
+ @result{} -1
+(truncate -1.7)
+ @result{} -1
+@end example
@end defun
@defun floor number &optional divisor
This returns @var{number}, converted to an integer by rounding downward
(towards negative infinity).
-If @var{divisor} is specified, @var{number} is divided by @var{divisor}
-before the floor is taken; this is the division operation that
-corresponds to @code{mod}. 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)
+ @result{} 1
+(floor 1.7)
+ @result{} 1
+(floor -1.2)
+ @result{} -2
+(floor -1.7)
+ @result{} -2
+(floor 5.99 3)
+ @result{} 1
+@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).
+
+@example
+(ceiling 1.2)
+ @result{} 2
+(ceiling 1.7)
+ @result{} 2
+(ceiling -1.2)
+ @result{} -1
+(ceiling -1.7)
+ @result{} -1
+@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,
depending on your machine.
+
+@example
+(round 1.2)
+ @result{} 1
+(round 1.7)
+ @result{} 2
+(round -1.2)
+ @result{} -1
+(round -1.7)
+ @result{} -2
+@end example
@end defun
@node Arithmetic Operations
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
@section Rounding Operations
@cindex rounding without conversion
-The functions @code{ffloor}, @code{fceiling}, @code{fround} and
+The functions @code{ffloor}, @code{fceiling}, @code{fround}, and
@code{ftruncate} take a floating point argument and return a floating
point result whose value is a nearby integer. @code{ffloor} returns the
nearest integer below; @code{fceiling}, the nearest integer above;
(lsh 3 2)
@result{} 12
;; @r{Decimal 3 becomes decimal 12.}
-00000011 @result{} 00001100
+00000011 @result{} 00001100
@end group
@end example
(lsh 6 -1)
@result{} 3
;; @r{Decimal 6 becomes decimal 3.}
-00000110 @result{} 00000011
+00000110 @result{} 00000011
@end group
@group
(lsh 5 -1)
@result{} 2
;; @r{Decimal 5 becomes decimal 2.}
-00000101 @result{} 00000010
+00000101 @result{} 00000010
@end group
@end 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
@example
@group
-(ash -6 -1) @result{} -3
+(ash -6 -1) @result{} -3
;; @r{Decimal @minus{}6 becomes decimal @minus{}3.}
-1111 1111 1111 1111 1111 1111 1010
- @result{}
-1111 1111 1111 1111 1111 1111 1101
+1 1111 1111 1111 1111 1111 1111 1010
+ @result{}
+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
- @result{}
-0111 1111 1111 1111 1111 1111 1101
+(lsh -6 -1) @result{} 268435453
+;; @r{Decimal @minus{}6 becomes decimal 268,435,453.}
+1 1111 1111 1111 1111 1111 1111 1010
+ @result{}
+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
@var{integer}, and vice-versa.
@example
-(lognot 5)
+(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
@end defun
@defun asin arg
-The value of @code{(asin @var{arg})} is a number between @minus{}pi/2
-and pi/2 (inclusive) whose sine is @var{arg}; if, however, @var{arg}
-is out of range (outside [-1, 1]), then the result is a NaN.
+The value of @code{(asin @var{arg})} is a number between
+@ifnottex
+@minus{}pi/2
+@end ifnottex
+@tex
+@math{-\pi/2}
+@end tex
+and
+@ifnottex
+pi/2
+@end ifnottex
+@tex
+@math{\pi/2}
+@end tex
+(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
-The value of @code{(acos @var{arg})} is a number between 0 and pi
-(inclusive) whose cosine is @var{arg}; if, however, @var{arg}
-is out of range (outside [-1, 1]), then the result is a NaN.
+The value of @code{(acos @var{arg})} is a number between 0 and
+@ifnottex
+pi
+@end ifnottex
+@tex
+@math{\pi}
+@end tex
+(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 arg
-The value of @code{(atan @var{arg})} is a number between @minus{}pi/2
-and pi/2 (exclusive) whose tangent is @var{arg}.
+@defun atan y &optional x
+The value of @code{(atan @var{y})} is a number between
+@ifnottex
+@minus{}pi/2
+@end ifnottex
+@tex
+@math{-\pi/2}
+@end tex
+and
+@ifnottex
+pi/2
+@end ifnottex
+@tex
+@math{\pi/2}
+@end tex
+(exclusive) whose tangent is @var{y}. If the optional second
+argument @var{x} is given, the value of @code{(atan y x)} is the
+angle in radians between the vector @code{[@var{x}, @var{y}]} and the
+@code{X} axis.
@end defun
@defun exp arg
-This is the exponential function; it returns @i{e} to the power
-@var{arg}. @i{e} is a fundamental mathematical constant also called the
-base of natural logarithms.
+This is the exponential function; it returns
+@tex
+@math{e}
+@end tex
+@ifnottex
+@i{e}
+@end ifnottex
+to the power @var{arg}.
+@tex
+@math{e}
+@end tex
+@ifnottex
+@i{e}
+@end ifnottex
+is a fundamental mathematical constant also called the base of natural
+logarithms.
@end defun
@defun log arg &optional base
This function returns the logarithm of @var{arg}, with base @var{base}.
-If you don't specify @var{base}, the base @var{e} is used. If @var{arg}
-is negative, the result is a NaN.
+If you don't specify @var{base}, the base
+@tex
+@math{e}
+@end tex
+@ifnottex
+@i{e}
+@end ifnottex
+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
-1457731, and the second one always returns -7692030. This
repeatability is helpful for debugging.
-If you want truly unpredictable random numbers, execute @code{(random
-t)}. This chooses a new seed based on the current time of day and on
-Emacs's process @sc{id} number.
+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 @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
of @code{random}. On other machines, the result can never be larger
than a certain maximum or less than a certain (negative) minimum.
@end defun
+
+@ignore
+ arch-tag: 574e8dd2-d513-4616-9844-c9a27869782e
+@end ignore