X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/94b00316b8909d64003a181b76c98c6210c139ad..70c750c0e8e54947399245af6c8b49f908c8939c:/lispref/numbers.texi

diff --git a/lispref/numbers.texi b/lispref/numbers.texi
index 6bcd9b1c6c..eaa2250a3f 100644
--- a/lispref/numbers.texi
+++ b/lispref/numbers.texi
@@ -1,6 +1,7 @@
 @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
@@ -12,15 +13,11 @@
 @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.
@@ -30,7 +27,7 @@ where Emacs does not support them.
 * 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
 
@@ -40,18 +37,18 @@ where Emacs does not support them.
 
   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.
@@ -103,8 +100,8 @@ complement} notation.)
 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
@@ -120,34 +117,26 @@ negative integer @minus{}134,217,728:
      @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
@@ -161,9 +150,22 @@ values.  It also provides for a class of values called NaN or
 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):
@@ -172,6 +174,13 @@ 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
@@ -232,7 +241,7 @@ compare them, then you test whether two values are the same
 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
@@ -241,6 +250,11 @@ numbers or markers.  However, it is a good idea to use @code{=} if you
 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.
@@ -249,9 +263,10 @@ Here's a function to do this:
 @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}
@@ -298,6 +313,8 @@ otherwise.
 
 @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)
@@ -305,12 +322,14 @@ This function returns the largest of its arguments.
 (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)
@@ -318,6 +337,10 @@ This function returns the smallest of its arguments.
 @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
@@ -344,9 +367,9 @@ 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.
+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
@@ -356,7 +379,9 @@ This returns @var{number}, converted to an integer by rounding upward
 
 @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
@@ -371,9 +396,9 @@ commonly used.
   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.
@@ -386,8 +411,8 @@ For example,
      @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
@@ -407,13 +432,9 @@ like this:
 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
 (+)
@@ -425,13 +446,12 @@ This function adds its arguments together.  When given no arguments,
 @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)
@@ -445,8 +465,7 @@ function does not check for overflow.
 
 @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
 (*)
@@ -473,14 +492,24 @@ permits machine-dependent rounding.  As a practical matter, all known
 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)
@@ -540,16 +569,26 @@ quotient to compute the remainder.
 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},
@@ -562,15 +601,16 @@ 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;
@@ -640,36 +680,7 @@ As the examples illustrate, shifting the pattern of bits one place to
 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
@@ -681,8 +692,7 @@ like this (with 8-bit binary numbers):
 @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
@@ -701,8 +711,37 @@ looks like this:
 @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
@@ -713,8 +752,8 @@ is negative.
 
 @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:
@@ -903,14 +942,13 @@ bit is one in the result if, and only if, the @var{n}th bit is zero in
 @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
@@ -920,31 +958,83 @@ in radians.
 @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
 
@@ -1000,17 +1090,16 @@ first call to @code{(random)} after you start Emacs always returns
 -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.