*** empty log message ***

1 files changed, 69 insertions, 79 deletions

diff --git a/lispref/numbers.texi b/lispref/numbers.texi
index f2e0a7df07a..e3456efbb20 100644
--- a/lispref/numbers.texi
+++ b/lispref/numbers.texi
@@ -3,7 +3,7 @@
 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. 
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/numbers
-@node Numbers, Strings and Characters, Types of Lisp Object, Top
+@node Numbers, Strings and Characters, Lisp Data Types, Top
 @chapter Numbers
 @cindex integers
 @cindex numbers
@@ -12,8 +12,8 @@
 @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 an exponential notation as well:
-thus, 1.5e2 equals 150; in this example, @samp{e2} stands for ten to the
+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
 exact; they have a fixed, limited amount of precision.
 
@@ -75,7 +75,7 @@ initial sign and optional final period.
 bitwise operators (@pxref{Bitwise Operations}), it is often helpful to
 view the numbers in their binary form.
 
-  In 24 bit binary, the decimal integer 5 looks like this:
+  In 24-bit binary, the decimal integer 5 looks like this:
 
 @example
 0000 0000  0000 0000  0000 0101
@@ -104,7 +104,7 @@ complement} notation.)
 1111 1111  1111 1111  1111 1011
 @end example
 
-  In this implementation, the largest 24 bit binary integer is the
+  In this implementation, the largest 24-bit binary integer is the
 decimal integer 8,388,607.  In binary, it looks like this:
 
 @example
@@ -112,8 +112,8 @@ decimal integer 8,388,607.  In binary, it looks like this:
 @end example
 
   Since the arithmetic functions do not check whether integers go
-outside their range, when you add 1 to 8,388,607, the value is negative
-integer @minus{}8,388,608:
+outside their range, when you add 1 to 8,388,607, the value is the
+negative integer @minus{}8,388,608:
 
 @example
 (+ 1 8388607)
@@ -157,11 +157,14 @@ a minus sign to write negative floating point numbers, as in
 @cindex NaN
    Most modern computers support the IEEE floating point standard, which
 provides for positive infinity and negative infinity as floating point
-values.  It also provides for a value called NaN or ``not-a-number''
-which is the result you get from numerical functions in cases where
-there is no correct answer.  For example, @code{(sqrt -1.0)} returns
-NaN.  There is no read syntax for NaN or infinities; perhaps we should
-create a syntax in the future.
+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
+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.
 
   You can use @code{logb} to extract the binary exponent of a floating
 point number (or estimate the logarithm of an integer):
@@ -200,19 +203,15 @@ This predicate tests whether its argument is a number (either integer or
 floating point), and returns @code{t} if so, @code{nil} otherwise.
 @end defun
 
-@defun natnump object
+@defun wholenump object
 @cindex natural numbers
-The @code{natnump} predicate (whose name comes from the phrase
-``natural-number-p'') tests to see whether its argument is a nonnegative
+The @code{wholenump} predicate (whose name comes from the phrase
+``whole-number-p'') tests to see whether its argument is a nonnegative
 integer, and returns @code{t} if so, @code{nil} otherwise.  0 is
 considered non-negative.
 
-Markers are not converted to integers, hence @code{natnump} of a marker
-is always @code{nil}.
-
-People have pointed out that this function is misnamed, because the term
-``natural number'' is usually understood as excluding zero.  We are open
-to suggestions for a better name to use in a future version.
+@findex natnump
+@code{natnump} is an obsolete synonym for @code{wholenump}.
 @end defun
 
 @defun zerop number
@@ -226,19 +225,22 @@ These two forms are equivalent: @code{(zerop x)} @equiv{} @code{(= x 0)}.
 @section Comparison of Numbers
 @cindex number equality
 
-  Floating point numbers in Emacs Lisp actually take up storage, and
-there can be many distinct floating point number objects with the same
-numeric value.  If you use @code{eq} to compare them, then you test
-whether two values are the same @emph{object}.  If you want to test for
-numerical equality, use @code{=}.
-
-  If you use @code{eq} to compare two integers, it always returns
-@code{t} if they have the same value.  This is sometimes useful, because
-@code{eq} accepts arguments of any type and never causes an error, 
-whereas @code{=} signals an error if the arguments are not 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.
+  To test numbers for numerical equality, you should normally use
+@code{=}, not @code{eq}.  There can be many distinct floating point
+number objects with the same numeric value.  If you use @code{eq} to
+compare them, then you test whether two values are the same
+@emph{object}.  By contrast, @code{=} compares only the numeric values
+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
+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
+type.  By contrast, @code{=} signals an error if the arguments are not
+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.
 
   There is another wrinkle: because floating point arithmetic is not
 exact, it is often a bad idea to check for equality of two floating
@@ -255,7 +257,7 @@ Here's a function to do this:
 
 @cindex CL note---integers vrs @code{eq}
 @quotation
-@b{Common Lisp note:} comparing numbers in Common Lisp always requires
+@b{Common Lisp note:} Comparing numbers in Common Lisp always requires
 @code{=} because Common Lisp implements multi-word integers, and two
 distinct integer objects can have the same numeric value.  Emacs Lisp
 can have just one integer object for any given value because it has a
@@ -458,7 +460,7 @@ not check for overflow.
 @end defun
 
 @defun / dividend divisor &rest divisors
-This function divides @var{dividend} by @var{divisors} and returns the
+This function divides @var{dividend} by @var{divisor} and returns the
 quotient.  If there are additional arguments @var{divisors}, then it
 divides @var{dividend} by each divisor in turn.  Each argument may be a
 number or a marker.
@@ -573,7 +575,7 @@ The functions @code{ffloor}, @code{fceil}, @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{fceil}, the nearest integer above;
-@code{ftrucate}, the nearest integer in the direction towards zero;
+@code{ftruncate}, the nearest integer in the direction towards zero;
 @code{fround}, the nearest integer.
 
 @defun ffloor float
@@ -586,7 +588,7 @@ This function rounds @var{float} to the next higher integral value, and
 returns that value as a floating point number.
 @end defun
 
-@defun ftrunc float
+@defun ftruncate float
 This function rounds @var{float} towards zero to an integral value, and
 returns that value as a floating point number.
 @end defun
@@ -610,22 +612,15 @@ reproducing the same pattern ``moved over''.
 @defun lsh integer1 count
 @cindex logical shift
 @code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the
-bits in @var{integer1} to the left @var{count} places, or to the
-right if @var{count} is negative.  If @var{count} is negative,
-@code{lsh} shifts zeros into the most-significant bit, producing a
-positive result even if @var{integer1} is negative.  Contrast this with
-@code{ash}, below.
-
-Thus, the decimal number 5 is the binary number 00000101.  Shifted once
-to the left, with a zero put in the one's place, the number becomes
-00001010, decimal 10.
-
-Here are two examples of shifting the pattern of bits one place to the
-left.  Since the contents of the rightmost place has been moved one
-place to the left, a value has to be inserted into the rightmost place.
-With @code{lsh}, a zero is placed into the rightmost place.  (These
-examples show only the low-order eight bits of the binary pattern; the
-rest are all zero.)
+bits in @var{integer1} to the left @var{count} places, or to the right
+if @var{count} is negative, bringing zeros into the vacated bits.  If
+@var{count} is negative, @code{lsh} shifts zeros into the leftmost
+(most-significant) bit, producing a positive result even if
+@var{integer1} is negative.  Contrast this with @code{ash}, below.
+
+Here are two examples of @code{lsh}, shifting a pattern of bits one
+place to the left.  We show only the low-order eight bits of the binary
+pattern; the rest are all zero.
 
 @example
 @group
@@ -646,18 +641,17 @@ 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.
 
-Note, however that functions do not check for overflow, and a returned
-value may be negative (and in any case, no more than a 24 bit value)
-when an integer is sufficiently left shifted.  
-
-For example, left shifting 8,388,607 produces @minus{}2:
+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 24 bit implementation, the numbers looks like this:
+In binary, in the 24-bit implementation, the argument looks like this:
 
 @example
 @group
@@ -749,10 +743,6 @@ In contrast, shifting the pattern of bits one place to the right with
 @end group
 @end example
 
-@noindent
-In this case, the 1 in the leftmost position is shifted one place to the
-right, and a zero is shifted into the leftmost position.
-
 Here are other examples:
 
 @c !!! Check if lined up in smallbook format!  XDVI shows problem
@@ -762,19 +752,19 @@ Here are other examples:
                    ;  @r{             24-bit binary values}
 
 (lsh 5 2)          ;   5  =  @r{0000 0000  0000 0000  0000 0101}
-     @result{} 20         ;  20  =  @r{0000 0000  0000 0000  0001 0100}
+     @result{} 20         ;      =  @r{0000 0000  0000 0000  0001 0100}
 @end group
 @group
 (ash 5 2)
      @result{} 20
 (lsh -5 2)         ;  -5  =  @r{1111 1111  1111 1111  1111 1011}
-     @result{} -20        ; -20  =  @r{1111 1111  1111 1111  1110 1100}
+     @result{} -20        ;      =  @r{1111 1111  1111 1111  1110 1100}
 (ash -5 2)
      @result{} -20
 @end group
 @group
 (lsh 5 -2)         ;   5  =  @r{0000 0000  0000 0000  0000 0101}
-     @result{} 1          ;   1  =  @r{0000 0000  0000 0000  0000 0001}
+     @result{} 1          ;      =  @r{0000 0000  0000 0000  0000 0001}
 @end group
 @group
 (ash 5 -2)
@@ -782,11 +772,11 @@ Here are other examples:
 @end group
 @group
 (lsh -5 -2)        ;  -5  =  @r{1111 1111  1111 1111  1111 1011}
-     @result{} 4194302    ;         @r{0011 1111  1111 1111  1111 1110}
+     @result{} 4194302    ;      =  @r{0011 1111  1111 1111  1111 1110}
 @end group
 @group
 (ash -5 -2)        ;  -5  =  @r{1111 1111  1111 1111  1111 1011}
-     @result{} -2         ;  -2  =  @r{1111 1111  1111 1111  1111 1110}
+     @result{} -2         ;      =  @r{1111 1111  1111 1111  1111 1110}
 @end group
 @end smallexample
 @end defun
@@ -801,7 +791,6 @@ rather than 0.)
 
 For example, using 4-bit binary numbers, the ``logical and'' of 13 and
 12 is 12: 1101 combined with 1100 produces 1100.
-
 In both the binary numbers, the leftmost two bits are set (i.e., they
 are 1's), so the leftmost two bits of the returned value are set.
 However, for the rightmost two bits, each is zero in at least one of
@@ -876,10 +865,10 @@ passed just one argument, it returns that argument.
 @cindex bitwise exclusive or
 @cindex logical exclusive or
 This function returns the ``exclusive or'' of its arguments: the
-@var{n}th bit is set in the result if, and only if, the @var{n}th bit
-is set in an odd number of the arguments.  If there are no arguments,
-the result is 0.  If @code{logxor} is passed just one argument, it returns
-that argument.
+@var{n}th bit is set in the result if, and only if, the @var{n}th bit is
+set in an odd number of the arguments.  If there are no arguments, the
+result is 0, which is an identity element for this operation.  If
+@code{logxor} is passed just one argument, it returns that argument.
 
 @smallexample
 @group
@@ -932,8 +921,8 @@ 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 @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.
 @end defun
 
@@ -944,8 +933,8 @@ 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 @minus{}pi/2
+and pi/2 (exclusive) whose tangent is @var{arg}.
 @end defun
 
 @defun exp arg
@@ -976,7 +965,8 @@ lose accuracy.
 
 @defun log10 arg
 This function returns the logarithm of @var{arg}, with base 10.  If
-@var{arg} is negative, the result is a NaN.
+@var{arg} is negative, the result is a NaN.  @code{(log10 @var{x})}
+@equiv{} @code{(log @var{x} 10)}, at least approximately.
 @end defun
 
 @defun expt x y