@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 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.
-2**27
@end ifinfo
@tex
-$-2^{27}$
+@math{-2^{27}}
@end tex
to
@ifinfo
2**27 - 1),
@end ifinfo
@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.
@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
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
+ 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.
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.
@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},
+the @var{more-numbers-or-markers} from @var{number-or-marker},
cumulatively. If there are no arguments, the result is 0.
@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},
@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;
@example
@group
-;; @r{Decimal 134.217,727}
+;; @r{Decimal 134,217,727}
0111 1111 1111 1111 1111 1111 1111
@end group
@end example
@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
+@ifinfo
+@minus{}pi/2
+@end ifinfo
+@tex
+@math{-\pi/2}
+@end tex
+and
+@ifinfo
+pi/2
+@end ifinfo
+@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
+@ifinfo
+pi
+@end ifinfo
+@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
+@ifinfo
+@minus{}pi/2
+@end ifinfo
+@tex
+@math{-\pi/2}
+@end tex
+and
+@ifinfo
+pi/2
+@end ifinfo
+@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
+@ifinfo
+@i{e}
+@end ifinfo
+to the power @var{arg}.
+@tex
+@math{e}
+@end tex
+@ifinfo
+@i{e}
+@end ifinfo
+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
+@ifinfo
+@i{e}
+@end ifinfo
+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