@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
+@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
@dfn{floating point numbers}. Integers are whole numbers such as
@minus{}3, 0, 7, 13, and 511. Their values are exact. Floating point
numbers are numbers with fractional parts, such as @minus{}4.5, 0.0, or
-2.71828. They can also be expressed in exponential notation:
-1.5e2 equals 150; in this example, @samp{e2} stands for ten to the
-second power, and is multiplied by 1.5. Floating point values are not
+2.71828. They can also be expressed in exponential notation: 1.5e2
+equals 150; in this example, @samp{e2} stands for ten to the second
+power, and that is multiplied by 1.5. Floating point values are not
exact; they have a fixed, limited amount of precision.
- Support for floating point numbers is a new feature in Emacs 19, and it
-is controlled by a separate compilation option, so you may encounter a site
-where Emacs does not support them.
-
@menu
* Integer Basics:: Representation and range of integers.
* Float Basics:: Representation and range of floating point.
* Arithmetic Operations:: How to add, subtract, multiply and divide.
* Rounding Operations:: Explicitly rounding floating point numbers.
* Bitwise Operations:: Logical and, or, not, shifting.
-* Transcendental Functions:: Trig, exponential and logarithmic functions.
+* Math Functions:: Trig, exponential and logarithmic functions.
* Random Numbers:: Obtaining random integers, predictable or not.
@end menu
The range of values for an integer depends on the machine. The
minimum range is @minus{}134217728 to 134217727 (28 bits; i.e.,
-@ifinfo
+@ifnottex
-2**27
-@end ifinfo
+@end ifnottex
@tex
-$-2^{27}$
+@math{-2^{27}}
@end tex
to
-@ifinfo
+@ifnottex
2**27 - 1),
-@end ifinfo
+@end ifnottex
@tex
-$2^{27}-1$),
+@math{2^{27}-1}),
@end tex
but some machines may provide a wider range. Many examples in this
chapter assume an integer has 28 bits.
1111 1111 1111 1111 1111 1111 1011
@end example
- In this implementation, the largest 28-bit binary integer is the
-decimal integer 134,217,727. In binary, it looks like this:
+ In this implementation, the largest 28-bit binary integer value is
+134,217,727 in decimal. In binary, it looks like this:
@example
0111 1111 1111 1111 1111 1111 1111
@result{} 1000 0000 0000 0000 0000 0000 0000
@end example
- Many of the following functions accept markers for arguments as well
-as integers. (@xref{Markers}.) More precisely, the actual arguments to
-such functions may be either integers or markers, which is why we often
-give these arguments the name @var{int-or-marker}. When the argument
+ Many of the functions described in this chapter accept markers for
+arguments in place of numbers. (@xref{Markers}.) Since the actual
+arguments to such functions may be either numbers or markers, we often
+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.
-@ignore
- In version 19, except where @emph{integer} is specified as an
-argument, all of the functions for markers and integers also work for
-floating point numbers.
-@end ignore
-
@node Float Basics
@section Floating Point Basics
-@cindex @code{LISP_FLOAT_TYPE} configuration macro
- Emacs version 19 supports floating point numbers, if compiled with the
-macro @code{LISP_FLOAT_TYPE} defined. The precise range of floating
-point numbers is machine-specific; it is the same as the range of the C
-data type @code{double} on the machine in question.
+ Floating point numbers are useful for representing numbers that are
+not integral. The precise range of floating point numbers is
+machine-specific; it is the same as the range of the C data type
+@code{double} on the machine you are using.
- The printed representation for floating point numbers requires either
-a decimal point (with at least one digit following), an exponent, or
-both. For example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2},
-@samp{1.5e3}, and @samp{.15e4} are five ways of writing a floating point
-number whose 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}.
+ The read-syntax for floating point numbers requires either a decimal
+point (with at least one digit following), an exponent, or both. For
+example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, @samp{1.5e3}, and
+@samp{.15e4} are five ways of writing a floating point number whose
+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 positive infinity
there is no correct answer. For example, @code{(sqrt -1.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 this manual
-doesn't try to distinguish them. Emacs Lisp has no read syntax for NaNs
-or infinities; perhaps we should create a syntax in the future.
+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:
+
+@table @asis
+@item positive infinity
+@samp{1.0e+INF}
+@item negative infinity
+@samp{-1.0e+INF}
+@item Not-a-number
+@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).
You can use @code{logb} to extract the binary exponent of a floating
point number (or estimate the logarithm of an integer):
This function returns the binary exponent of @var{number}. More
precisely, the value is the logarithm of @var{number} base 2, rounded
down to an integer.
+
+@example
+(logb 10)
+ @result{} 3
+(logb 10.0e20)
+ @result{} 69
+@end example
@end defun
@node Predicates on Numbers
of the objects.
At present, each integer value has a unique Lisp object in Emacs Lisp.
-Therefore, @code{eq} is equivalent @code{=} where integers are
+Therefore, @code{eq} is equivalent to @code{=} where integers are
concerned. It is sometimes convenient to use @code{eq} for comparing an
unknown value with an integer, because @code{eq} does not report an
error if the unknown value is not a number---it accepts arguments of any
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.
+
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.
@example
(defvar fuzz-factor 1.0e-6)
(defun approx-equal (x y)
- (< (/ (abs (- x y))
- (max (abs x) (abs y)))
- fuzz-factor))
+ (or (and (= x 0) (= y 0))
+ (< (/ (abs (- x y))
+ (max (abs x) (abs y)))
+ fuzz-factor)))
@end example
@cindex CL note---integers vrs @code{eq}
@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
+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 argument is floating-point, the value is returned
+as floating point, even if it was given as an integer.
@example
(min -4 1)
@end example
@end defun
+@defun abs number
+This function returns the absolute value of @var{number}.
+@end defun
+
@node Numeric Conversions
@section Numeric Conversions
@cindex rounding in conversions
(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.
+before the floor is taken; this uses the kind of division operation that
+corresponds to @code{mod}, rounding downward. An @code{arith-error}
+results if @var{divisor} is 0.
@end defun
@defun ceiling number
@defun round number
This returns @var{number}, converted to an integer by rounding towards the
-nearest integer.
+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.
@end defun
@node Arithmetic Operations
All of these functions except @code{%} return a floating point value
if any argument is floating.
- It is important to note that in GNU Emacs Lisp, arithmetic functions
-do not check for overflow. Thus @code{(1+ 8388607)} may evaluate to
-@minus{}8388608, depending on your hardware.
+ 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.
@defun 1+ number-or-marker
This function returns @var{number-or-marker} plus 1.
@result{} 5
@end example
-This function is not analogous to the C operator @code{++}---it does
-not increment a variable. It just computes a sum. Thus,
+This function is not analogous to the C operator @code{++}---it does not
+increment a variable. It just computes a sum. Thus, if we continue,
@example
foo
This function returns @var{number-or-marker} minus 1.
@end defun
-@defun abs number
-This returns the absolute value of @var{number}.
-@end defun
-
@defun + &rest numbers-or-markers
This function adds its arguments together. When given no arguments,
-@code{+} returns 0. It does not check for overflow.
+@code{+} returns 0.
@example
(+)
@end example
@end defun
-@defun - &optional number-or-marker &rest other-numbers-or-markers
+@defun - &optional number-or-marker &rest more-numbers-or-markers
The @code{-} function serves two purposes: negation and subtraction.
When @code{-} has a single argument, the value is the negative of the
argument. When there are multiple arguments, @code{-} subtracts each of
-the @var{other-numbers-or-markers} from @var{number-or-marker},
-cumulatively. If there are no arguments, the result is 0. This
-function does not check for overflow.
+the @var{more-numbers-or-markers} from @var{number-or-marker},
+cumulatively. If there are no arguments, the result is 0.
@example
(- 10 1 2 3 4)
@defun * &rest numbers-or-markers
This function multiplies its arguments together, and returns the
-product. When given no arguments, @code{*} returns 1. It does
-not check for overflow.
+product. When given no arguments, @code{*} returns 1.
@example
(*)
machines round in the standard fashion.
@cindex @code{arith-error} in division
-If you divide by 0, an @code{arith-error} error is signaled.
-(@xref{Errors}.)
+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;
+otherwise, it signals an @code{arith-error} error.
@example
+@group
(/ 6 2)
@result{} 3
+@end group
(/ 5 2)
@result{} 2
+(/ 5.0 2)
+ @result{} 2.5
+(/ 5 2.0)
+ @result{} 2.5
+(/ 5.0 2.0)
+ @result{} 2.5
(/ 25 3 2)
@result{} 4
(/ -17 6)
An @code{arith-error} results if @var{divisor} is 0.
@example
+@group
(mod 9 4)
@result{} 1
+@end group
+@group
(mod -9 4)
@result{} 3
+@end group
+@group
(mod 9 -4)
@result{} -3
+@end group
+@group
(mod -9 -4)
@result{} -1
+@end group
+@group
(mod 5.5 2.5)
@result{} .5
+@end group
@end example
For any two numbers @var{dividend} and @var{divisor},
@end example
@noindent
-always equals @var{dividend}, subject to rounding error if
-either argument is floating point.
+always equals @var{dividend}, subject to rounding error if either
+argument is floating point. For @code{floor}, see @ref{Numeric
+Conversions}.
@end defun
@node Rounding Operations
@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;
the left produces a number that is twice the value of the previous
number.
-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 8,388,607
-produces @minus{}2 on a 24-bit machine:
-
-@example
-(lsh 8388607 1) ; @r{left shift}
- @result{} -2
-@end example
-
-In binary, in the 28-bit implementation, the argument looks like this:
-
-@example
-@group
-;; @r{Decimal 134.217,727}
-0111 1111 1111 1111 1111 1111 1111
-@end group
-@end example
-
-@noindent
-which becomes the following when left shifted:
-
-@example
-@group
-;; @r{Decimal @minus{}2}
-1111 1111 1111 1111 1111 1111 1110
-@end group
-@end example
-
-Shifting the pattern of bits two places to the left produces results
+Shifting a pattern of bits two places to the left produces results
like this (with 8-bit binary numbers):
@example
@end group
@end example
-On the other hand, shifting the pattern of bits one place to the right
-looks like this:
+On the other hand, shifting one place to the right looks like this:
@example
@group
@end example
@noindent
-As the example illustrates, shifting the pattern of bits one place to
-the right divides the value of the binary number by two, rounding downward.
+As the example illustrates, shifting one place to the right divides the
+value of a positive integer by two, rounding downward.
+
+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:
+
+@example
+(lsh 134217727 1) ; @r{left shift}
+ @result{} -2
+@end example
+
+In binary, in the 28-bit implementation, the argument looks like this:
+
+@example
+@group
+;; @r{Decimal 134,217,727}
+0111 1111 1111 1111 1111 1111 1111
+@end group
+@end example
+
+@noindent
+which becomes the following when left shifted:
+
+@example
+@group
+;; @r{Decimal @minus{}2}
+1111 1111 1111 1111 1111 1111 1110
+@end group
+@end example
@end defun
@defun ash integer1 count
@code{ash} gives the same results as @code{lsh} except when
@var{integer1} and @var{count} are both negative. In that case,
-@code{ash} puts a one in the leftmost position, while @code{lsh} puts
-a zero in the leftmost position.
+@code{ash} puts ones in the empty bit positions on the left, while
+@code{lsh} puts zeros in those bit positions.
Thus, with @code{ash}, shifting the pattern of bits one place to the right
looks like this:
@end example
@end defun
-@node Transcendental Functions
-@section Transcendental Functions
+@node Math Functions
+@section Standard Mathematical Functions
@cindex transcendental functions
@cindex mathematical functions
-These mathematical functions are available if floating point is
-supported. They allow integers as well as floating point numbers
-as arguments.
+ These mathematical functions allow integers as well as floating point
+numbers as arguments.
@defun sin arg
@defunx cos arg
@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}
+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]), then the result is a NaN.
@end defun
@defun acos arg
-The value of @code{(acos @var{arg})} is a number between 0 and pi
+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]), then the result is a NaN.
@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}.
+The value of @code{(atan @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
+(exclusive) whose tangent is @var{arg}.
@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}
+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, the result is a NaN.
@end defun
-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 @sc{id} number.
@defun random &optional limit
This function returns a pseudo-random integer. Repeated calls return a
series of pseudo-random integers.
-If @var{limit} is @code{nil}, then the value may in principle be any
-integer. If @var{limit} is a positive integer, the value is chosen to
-be nonnegative and less than @var{limit} (only in Emacs 19).
+If @var{limit} is a positive integer, the value is chosen to be
+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.