@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 Free Software Foundation, Inc.
+@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
@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.,
+minimum range is @minus{}268435456 to 268435455 (29 bits; i.e.,
@ifnottex
--2**27
+-2**28
@end ifnottex
-@tex
-@math{-2^{27}}
+@tex
+@math{-2^{28}}
@end tex
-to
+to
@ifnottex
-2**27 - 1),
+2**28 - 1),
@end ifnottex
-@tex
-@math{2^{27}-1}),
+@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
+ 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.
+
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
@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):
@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
(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
@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 arg
-The value of @code{(atan @var{arg})} is a number between
+@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
-(exclusive) whose tangent is @var{arg}.
+(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
@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
@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
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
HCoop / bpt / emacs.git / blobdiff