X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/e18afed7d695edac870ddf55aabc85c0a95a4b5f..41278b775bd3ebc213ff8b9eda2f2c04a5354bba:/doc/lispref/numbers.texi

diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi
index f19dea6903..8d1d3a798e 100644
--- a/doc/lispref/numbers.texi
+++ b/doc/lispref/numbers.texi
@@ -1,21 +1,22 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2012
-@c   Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software
+@c Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
-@node Numbers, Strings and Characters, Lisp Data Types, Top
+@node Numbers
 @chapter Numbers
 @cindex integers
 @cindex numbers
 
   GNU Emacs supports two numeric data types: @dfn{integers} and
-@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 that is multiplied by 1.5.  Floating point values are not
-exact; they have a fixed, limited amount of precision.
+@dfn{floating-point numbers}.  Integers are whole numbers such as
+@minus{}3, 0, 7, 13, and 511.  Floating-point numbers are numbers with
+fractional parts, such as @minus{}4.5, 0.0, and 2.71828.  They can
+also be expressed in exponential notation: @samp{1.5e2} is the same as
+@samp{150.0}; here, @samp{e2} stands for ten to the second power, and
+that is multiplied by 1.5.  Integer computations are exact, though
+they may overflow.  Floating-point computations often involve rounding
+errors, as the numbers have a fixed amount of precision.
 
 @menu
 * Integer Basics::            Representation and range of integers.
@@ -24,34 +25,32 @@ exact; they have a fixed, limited amount of precision.
 * Comparison of Numbers::     Equality and inequality predicates.
 * Numeric Conversions::       Converting float to integer and vice versa.
 * Arithmetic Operations::     How to add, subtract, multiply and divide.
-* Rounding Operations::       Explicitly rounding floating point numbers.
+* Rounding Operations::       Explicitly rounding floating-point numbers.
 * Bitwise Operations::        Logical and, or, not, shifting.
 * Math Functions::            Trig, exponential and logarithmic functions.
 * Random Numbers::            Obtaining random integers, predictable or not.
 @end menu
 
 @node Integer Basics
-@comment  node-name,  next,  previous,  up
 @section Integer Basics
 
   The range of values for an integer depends on the machine.  The
-minimum range is @minus{}536870912 to 536870911 (30 bits; i.e.,
+minimum range is @minus{}536,870,912 to 536,870,911 (30 bits; i.e.,
 @ifnottex
--2**29
+@minus{}2**29
 @end ifnottex
 @tex
 @math{-2^{29}}
 @end tex
 to
 @ifnottex
-2**29 - 1),
+2**29 @minus{} 1),
 @end ifnottex
 @tex
 @math{2^{29}-1}),
 @end tex
-but some machines provide a wider range.  Many examples in this
-chapter assume that an integer has 30 bits and that floating point
-numbers are IEEE double precision.
+but many machines provide a wider range.  Many examples in this
+chapter assume the minimum integer width of 30 bits.
 @cindex overflow
 
   The Lisp reader reads an integer as a sequence of digits with optional
@@ -63,7 +62,8 @@ Emacs range is treated as a floating-point number.
  1.              ; @r{The integer 1.}
 +1               ; @r{Also the integer 1.}
 -1               ; @r{The integer @minus{}1.}
- 1073741825      ; @r{The floating point number 1073741825.0.}
+ 9000000000000000000
+                 ; @r{The floating-point number 9e18.}
  0               ; @r{The integer 0.}
 -0               ; @r{The integer 0.}
 @end example
@@ -116,15 +116,15 @@ use the @samp{...} notation to make binary integers easier to read.)
 @minus{}1 is represented as 30 ones.  (This is called @dfn{two's
 complement} notation.)
 
-  The negative integer, @minus{}5, is creating by subtracting 4 from
-@minus{}1.  In binary, the decimal integer 4 is 100.  Consequently,
+  Subtracting 4 from @minus{}1 returns the negative integer @minus{}5.
+In binary, the decimal integer 4 is 100.  Consequently,
 @minus{}5 looks like this:
 
 @example
 1111...111011 (30 bits total)
 @end example
 
-  In this implementation, the largest 30-bit binary integer value is
+  In this implementation, the largest 30-bit binary integer is
 536,870,911 in decimal.  In binary, it looks like this:
 
 @example
@@ -147,102 +147,137 @@ 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.
 
-@cindex largest Lisp integer number
-@cindex maximum Lisp integer number
+@cindex largest Lisp integer
+@cindex maximum Lisp integer
 @defvar most-positive-fixnum
-The value of this variable is the largest integer that Emacs Lisp
-can handle.
+The value of this variable is the largest integer that Emacs Lisp can
+handle.  Typical values are
+@ifnottex
+2**29 @minus{} 1
+@end ifnottex
+@tex
+@math{2^{29}-1}
+@end tex
+on 32-bit and
+@ifnottex
+2**61 @minus{} 1
+@end ifnottex
+@tex
+@math{2^{61}-1}
+@end tex
+on 64-bit platforms.
 @end defvar
 
-@cindex smallest Lisp integer number
-@cindex minimum Lisp integer number
+@cindex smallest Lisp integer
+@cindex minimum Lisp integer
 @defvar most-negative-fixnum
 The value of this variable is the smallest integer that Emacs Lisp can
-handle.  It is negative.
+handle.  It is negative.  Typical values are
+@ifnottex
+@minus{}2**29
+@end ifnottex
+@tex
+@math{-2^{29}}
+@end tex
+on 32-bit and
+@ifnottex
+@minus{}2**61
+@end ifnottex
+@tex
+@math{-2^{61}}
+@end tex
+on 64-bit platforms.
 @end defvar
 
-  @xref{Character Codes, max-char}, for the maximum value of a valid
-character codepoint.
+  In Emacs Lisp, text characters are represented by integers.  Any
+integer between zero and the value of @code{(max-char)}, inclusive, is
+considered to be valid as a character.  @xref{Character Codes}.
 
 @node Float Basics
-@section Floating Point Basics
+@section Floating-Point Basics
 
 @cindex @acronym{IEEE} floating point
-  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.  Emacs uses the
-@acronym{IEEE} floating point standard where possible (the standard is
-supported by most modern computers).
-
-  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}.
-
-  Emacs Lisp treats @code{-0.0} as equal to ordinary zero (with
-respect to @code{equal} and @code{=}), even though the two are
-distinguishable in the @acronym{IEEE} floating point standard.
+  Floating-point numbers are useful for representing numbers that are
+not integral.  The range of floating-point numbers is
+the same as the range of the C data type @code{double} on the machine
+you are using.  On all computers currently supported by Emacs, this is
+double-precision @acronym{IEEE} floating point.
+
+  The read syntax for floating-point numbers requires either a decimal
+point, an exponent, or both.  Optional signs (@samp{+} or @samp{-})
+precede the number and its exponent.  For example, @samp{1500.0},
+@samp{+15e2}, @samp{15.0e+2}, @samp{+1500000e-3}, and @samp{.15e4} are
+five ways of writing a floating-point number whose value is 1500.
+They are all equivalent.  Like Common Lisp, Emacs Lisp requires at
+least one digit after any decimal point in a floating-point number;
+@samp{1500.} is an integer, not a floating-point number.
+
+  Emacs Lisp treats @code{-0.0} as numerically equal to ordinary zero
+with respect to @code{equal} and @code{=}.  This follows the
+@acronym{IEEE} floating-point standard, which says @code{-0.0} and
+@code{0.0} are numerically equal even though other operations can
+distinguish them.
 
 @cindex positive infinity
 @cindex negative infinity
 @cindex infinity
 @cindex NaN
-  The @acronym{IEEE} floating point standard supports positive
-infinity and negative infinity as floating point values.  It also
+  The @acronym{IEEE} floating-point standard supports 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{(/ 0.0 0.0)} returns a NaN.  (NaN
-values can also carry a sign, but for practical purposes there's no
-significant difference between different NaN values in Emacs Lisp.)
-Here are the read syntaxes for these special floating point values:
+correct answer.  For example, @code{(/ 0.0 0.0)} returns a NaN@.
+Although NaN values carry a sign, for practical purposes there is no other
+significant difference between different NaN values in Emacs Lisp.
+
+Here are 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} or @samp{-0.0e+NaN}.
+@item infinity
+@samp{1.0e+INF} and @samp{-1.0e+INF}
+@item not-a-number
+@samp{0.0e+NaN} and @samp{-0.0e+NaN}
 @end table
 
-@defun isnan number
-This predicate tests whether its argument is NaN, and returns @code{t}
-if so, @code{nil} otherwise.  The argument must be a number.
-@end defun
-
-  The following functions are specialized for handling floating point
+  The following functions are specialized for handling floating-point
 numbers:
 
-@defun frexp x
-This function returns a cons cell @code{(@var{sig} . @var{exp})},
-where @var{sig} and @var{exp} are respectively the significand and
-exponent of the floating point number @var{x}:
+@defun isnan x
+This predicate returns @code{t} if its floating-point argument is a NaN,
+@code{nil} otherwise.
+@end defun
 
-@smallexample
-@var{x} = @var{sig} * 2^@var{exp}
-@end smallexample
+@defun frexp x
+This function returns a cons cell @code{(@var{s} . @var{e})},
+where @var{s} and @var{e} are respectively the significand and
+exponent of the floating-point number @var{x}.
 
-@var{sig} is a floating point number between 0.5 (inclusive) and 1.0
-(exclusive).  If @var{x} is zero, the return value is @code{(0 . 0)}.
+If @var{x} is finite, then @var{s} is a floating-point number between 0.5
+(inclusive) and 1.0 (exclusive), @var{e} is an integer, and
+@ifnottex
+@var{x} = @var{s} * 2**@var{e}.
+@end ifnottex
+@tex
+@math{x = s 2^e}.
+@end tex
+If @var{x} is zero or infinity, then @var{s} is the same as @var{x}.
+If @var{x} is a NaN, then @var{s} is also a NaN@.
+If @var{x} is zero, then @var{e} is 0.
 @end defun
 
 @defun ldexp sig &optional exp
-This function returns a floating point number corresponding to the
+This function returns a floating-point number corresponding to the
 significand @var{sig} and exponent @var{exp}.
 @end defun
 
 @defun copysign x1 x2
 This function copies the sign of @var{x2} to the value of @var{x1},
-and returns the result.  @var{x1} and @var{x2} must be floating point
-numbers.
+and returns the result.  @var{x1} and @var{x2} must be floating point.
 @end defun
 
-@defun logb number
-This function returns the binary exponent of @var{number}.  More
-precisely, the value is the logarithm of @var{number} base 2, rounded
+@defun logb x
+This function returns the binary exponent of @var{x}.  More
+precisely, the value is the logarithm base 2 of @math{|x|}, rounded
 down to an integer.
 
 @example
@@ -265,8 +300,8 @@ its argument.  See also @code{integer-or-marker-p} and
 @code{number-or-marker-p}, in @ref{Predicates on Markers}.
 
 @defun floatp object
-This predicate tests whether its argument is a floating point
-number and returns @code{t} if so, @code{nil} otherwise.
+This predicate tests whether its argument is floating point
+and returns @code{t} if so, @code{nil} otherwise.
 @end defun
 
 @defun integerp object
@@ -286,8 +321,8 @@ tests to see whether its argument is a nonnegative integer, and
 returns @code{t} if so, @code{nil} otherwise.  0 is considered
 non-negative.
 
-@findex wholenump number
-This is a synonym for @code{natnump}.
+@findex wholenump
+@code{wholenump} is a synonym for @code{natnump}.
 @end defun
 
 @defun zerop number
@@ -303,37 +338,36 @@ if so, @code{nil} otherwise.  The argument must be a number.
 @cindex comparing numbers
 
   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
+@code{=}, not @code{eq}.  There can be many distinct floating-point
+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.
+  In Emacs Lisp, each integer is a unique Lisp object.
 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
-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.
-
-  Sometimes it is useful to compare numbers with @code{equal}; it
+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 better programming practice to
+use @code{=} if you can, even for comparing integers.
+
+  Sometimes it is useful to compare numbers with @code{equal}, which
 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.
+@code{=} can treat an integer and a floating-point number as equal.
 @xref{Equality Predicates}.
 
-  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.
+  There is another wrinkle: because floating-point arithmetic is not
+exact, it is often a bad idea to check for equality of floating-point
+values.  Usually it is better to test for approximate equality.
 Here's a function to do this:
 
 @example
 (defvar fuzz-factor 1.0e-6)
 (defun approx-equal (x y)
-  (or (and (= x 0) (= y 0))
+  (or (= x y)
       (< (/ (abs (- x y))
             (max (abs x) (abs y)))
          fuzz-factor)))
@@ -345,12 +379,12 @@ Here's a function to do this:
 @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
-limited range of integer values.
+limited range of integers.
 @end quotation
 
-@defun = number-or-marker1 number-or-marker2
-This function tests whether its arguments are numerically equal, and
-returns @code{t} if so, @code{nil} otherwise.
+@defun = number-or-marker &rest number-or-markers
+This function tests whether all its arguments are numerically equal,
+and returns @code{t} if so, @code{nil} otherwise.
 @end defun
 
 @defun eql value1 value2
@@ -365,32 +399,29 @@ This function tests whether its arguments are numerically equal, and
 returns @code{t} if they are not, and @code{nil} if they are.
 @end defun
 
-@defun <  number-or-marker1 number-or-marker2
-This function tests whether its first argument is strictly less than
-its second argument.  It returns @code{t} if so, @code{nil} otherwise.
+@defun <  number-or-marker &rest number-or-markers
+This function tests whether each argument is strictly less than the
+following argument.  It returns @code{t} if so, @code{nil} otherwise.
 @end defun
 
-@defun <=  number-or-marker1 number-or-marker2
-This function tests whether its first argument is less than or equal
-to its second argument.  It returns @code{t} if so, @code{nil}
-otherwise.
+@defun <= number-or-marker &rest number-or-markers
+This function tests whether each argument is less than or equal to
+the following argument.  It returns @code{t} if so, @code{nil} otherwise.
 @end defun
 
-@defun >  number-or-marker1 number-or-marker2
-This function tests whether its first argument is strictly greater
-than its second argument.  It returns @code{t} if so, @code{nil}
-otherwise.
+@defun > number-or-marker &rest number-or-markers
+This function tests whether each argument is strictly greater than
+the following argument.  It returns @code{t} if so, @code{nil} otherwise.
 @end defun
 
-@defun >=  number-or-marker1 number-or-marker2
-This function tests whether its first argument is greater than or
-equal to its second argument.  It returns @code{t} if so, @code{nil}
-otherwise.
+@defun >= number-or-marker &rest number-or-markers
+This function tests whether each argument is greater than or equal to
+the following argument.  It returns @code{t} if so, @code{nil} otherwise.
 @end defun
 
 @defun max number-or-marker &rest numbers-or-markers
 This function returns the largest of its arguments.
-If any of the arguments is floating-point, the value is returned
+If any of the arguments is floating point, the value is returned
 as floating point, even if it was given as an integer.
 
 @example
@@ -405,7 +436,7 @@ as floating point, even if it was given as an integer.
 
 @defun min number-or-marker &rest numbers-or-markers
 This function returns the smallest of its arguments.
-If any of the arguments is floating-point, the value is returned
+If any of the arguments is floating point, the value is returned
 as floating point, even if it was given as an integer.
 
 @example
@@ -428,19 +459,20 @@ To convert an integer to floating point, use the function @code{float}.
 
 @defun float number
 This returns @var{number} converted to floating point.
-If @var{number} is already a floating point number, @code{float} returns
+If @var{number} is already floating point, @code{float} returns
 it unchanged.
 @end defun
 
-There are four functions to convert floating point numbers to integers;
-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
+  There are four functions to convert floating-point numbers to
+integers; 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.
+integer.  If @var{divisor} is zero (whether integer or
+floating point), Emacs signals an @code{arith-error} error.
 
 @defun truncate number &optional divisor
 This returns @var{number}, converted to an integer by rounding towards
@@ -498,8 +530,7 @@ This returns @var{number}, converted to an integer by rounding upward
 @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,
-depending on your machine.
+returns the even integer.
 
 @example
 (round 1.2)
@@ -517,17 +548,15 @@ depending on your machine.
 @section Arithmetic Operations
 @cindex arithmetic operations
 
-  Emacs Lisp provides the traditional four arithmetic operations:
-addition, subtraction, multiplication, and division.  Remainder and modulus
-functions supplement the division functions.  The functions to
-add or subtract 1 are provided because they are traditional in Lisp and
-commonly used.
+  Emacs Lisp provides the traditional four arithmetic operations
+(addition, subtraction, multiplication, and division), as well as
+remainder and modulus functions, and functions to add or subtract 1.
+Except for @code{%}, each of these functions accepts both integer and
+floating-point arguments, and returns a floating-point number if any
+argument is floating point.
 
-  All of these functions except @code{%} return a floating point value
-if any argument is floating.
-
-  It is important to note that in Emacs Lisp, arithmetic functions
-do not check for overflow.  Thus @code{(1+ 536870911)} may evaluate to
+  Emacs Lisp arithmetic functions do not check for integer overflow.
+Thus @code{(1+ 536870911)} may evaluate to
 @minus{}536870912, depending on your hardware.
 
 @defun 1+ number-or-marker
@@ -613,40 +642,45 @@ 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.
 
-If all the arguments are integers, then the result is an integer too.
-This means the result has to be rounded.  On most machines, the result
-is rounded towards zero after each division, but some machines may round
-differently with negative arguments.  This is because the Lisp function
-@code{/} is implemented using the C division operator, which also
-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 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 @acronym{IEEE} floating point;
-otherwise, it signals an @code{arith-error} error.
+If all the arguments are integers, the result is an integer, obtained
+by rounding the quotient towards zero after each division.
 
 @example
 @group
 (/ 6 2)
      @result{} 3
 @end group
+@group
 (/ 5 2)
      @result{} 2
+@end group
+@group
 (/ 5.0 2)
      @result{} 2.5
+@end group
+@group
 (/ 5 2.0)
      @result{} 2.5
+@end group
+@group
 (/ 5.0 2.0)
      @result{} 2.5
+@end group
+@group
 (/ 25 3 2)
      @result{} 4
+@end group
 @group
 (/ -17 6)
-     @result{} -2   @r{(could in theory be @minus{}3 on some machines)}
+     @result{} -2
 @end group
 @end example
+
+@cindex @code{arith-error} in division
+If you divide an integer by the integer 0, Emacs signals an
+@code{arith-error} error (@pxref{Errors}).  Floating-point division of
+a nonzero number by zero yields either positive or negative infinity
+(@pxref{Float Basics}).
 @end defun
 
 @defun % dividend divisor
@@ -654,10 +688,17 @@ otherwise, it signals an @code{arith-error} error.
 This function returns the integer remainder after division of @var{dividend}
 by @var{divisor}.  The arguments must be integers or markers.
 
-For negative arguments, the remainder is in principle machine-dependent
-since the quotient is; but in practice, all known machines behave alike.
+For any two integers @var{dividend} and @var{divisor},
 
-An @code{arith-error} results if @var{divisor} is 0.
+@example
+@group
+(+ (% @var{dividend} @var{divisor})
+   (* (/ @var{dividend} @var{divisor}) @var{divisor}))
+@end group
+@end example
+
+@noindent
+always equals @var{dividend} if @var{divisor} is nonzero.
 
 @example
 (% 9 4)
@@ -669,18 +710,6 @@ An @code{arith-error} results if @var{divisor} is 0.
 (% -9 -4)
      @result{} -1
 @end example
-
-For any two integers @var{dividend} and @var{divisor},
-
-@example
-@group
-(+ (% @var{dividend} @var{divisor})
-   (* (/ @var{dividend} @var{divisor}) @var{divisor}))
-@end group
-@end example
-
-@noindent
-always equals @var{dividend}.
 @end defun
 
 @defun mod dividend divisor
@@ -690,12 +719,12 @@ in other words, the remainder after division of @var{dividend}
 by @var{divisor}, but with the same sign as @var{divisor}.
 The arguments must be numbers or markers.
 
-Unlike @code{%}, @code{mod} returns a well-defined result for negative
-arguments.  It also permits floating point arguments; it rounds the
-quotient downward (towards minus infinity) to an integer, and uses that
-quotient to compute the remainder.
+Unlike @code{%}, @code{mod} permits floating-point arguments; it
+rounds the quotient downward (towards minus infinity) to an integer,
+and uses that quotient to compute the remainder.
 
-An @code{arith-error} results if @var{divisor} is 0.
+If @var{divisor} is zero, @code{mod} signals an @code{arith-error}
+error if both arguments are integers, and returns a NaN otherwise.
 
 @example
 @group
@@ -731,7 +760,8 @@ For any two numbers @var{dividend} and @var{divisor},
 
 @noindent
 always equals @var{dividend}, subject to rounding error if either
-argument is floating point.  For @code{floor}, see @ref{Numeric
+argument is floating point and to an @code{arith-error} if @var{dividend} is an
+integer and @var{divisor} is 0.  For @code{floor}, see @ref{Numeric
 Conversions}.
 @end defun
 
@@ -740,30 +770,31 @@ Conversions}.
 @cindex rounding without conversion
 
 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
+@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;
 @code{ftruncate}, the nearest integer in the direction towards zero;
 @code{fround}, the nearest integer.
 
 @defun ffloor float
 This function rounds @var{float} to the next lower integral value, and
-returns that value as a floating point number.
+returns that value as a floating-point number.
 @end defun
 
 @defun fceiling float
 This function rounds @var{float} to the next higher integral value, and
-returns that value as a floating point number.
+returns that value as a floating-point number.
 @end defun
 
 @defun ftruncate float
 This function rounds @var{float} towards zero to an integral value, and
-returns that value as a floating point number.
+returns that value as a floating-point number.
 @end defun
 
 @defun fround float
 This function rounds @var{float} to the nearest integral value,
-and returns that value as a floating point number.
+and returns that value as a floating-point number.
+Rounding a value equidistant between two integers returns the even integer.
 @end defun
 
 @node Bitwise Operations
@@ -1072,14 +1103,14 @@ bit is one in the result if, and only if, the @var{n}th bit is zero in
 @cindex mathematical functions
 @cindex floating-point functions
 
-  These mathematical functions allow integers as well as floating point
+  These mathematical functions allow integers as well as floating-point
 numbers as arguments.
 
 @defun sin arg
 @defunx cos arg
 @defunx tan arg
-These are the ordinary trigonometric functions, with argument measured
-in radians.
+These are the basic trigonometric functions, with argument @var{arg}
+measured in radians.
 @end defun
 
 @defun asin arg
@@ -1097,8 +1128,8 @@ pi/2
 @tex
 @math{\pi/2}
 @end tex
-(inclusive) whose sine is @var{arg}; if, however, @var{arg} is out of
-range (outside [@minus{}1, 1]), it signals a @code{domain-error} error.
+(inclusive) whose sine is @var{arg}.  If @var{arg} is out of range
+(outside [@minus{}1, 1]), @code{asin} returns a NaN.
 @end defun
 
 @defun acos arg
@@ -1109,8 +1140,8 @@ pi
 @tex
 @math{\pi}
 @end tex
-(inclusive) whose cosine is @var{arg}; if, however, @var{arg} is out
-of range (outside [@minus{}1, 1]), it signals a @code{domain-error} error.
+(inclusive) whose cosine is @var{arg}.  If @var{arg} is out of range
+(outside [@minus{}1, 1]), @code{acos} returns a NaN.
 @end defun
 
 @defun atan y &optional x
@@ -1142,40 +1173,21 @@ This is the exponential function; it returns @math{e} to the power
 @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 natural base
-@math{e} is used.  If @var{arg} is negative, it signals a
-@code{domain-error} error.
-@end defun
-
-@ignore
-@defun expm1 arg
-This function returns @code{(1- (exp @var{arg}))}, but it is more
-accurate than that when @var{arg} is negative and @code{(exp @var{arg})}
-is close to 1.
-@end defun
-
-@defun log1p arg
-This function returns @code{(log (1+ @var{arg}))}, but it is more
-accurate than that when @var{arg} is so small that adding 1 to it would
-lose accuracy.
-@end defun
-@end ignore
-
-@defun log10 arg
-This function returns the logarithm of @var{arg}, with base 10.  If
-@var{arg} is negative, it signals a @code{domain-error} error.
-@code{(log10 @var{x})} @equiv{} @code{(log @var{x} 10)}, at least
-approximately.
+@math{e} is used.  If @var{arg} or @var{base} is negative, @code{log}
+returns a NaN.
 @end defun
 
 @defun expt x y
 This function returns @var{x} raised to power @var{y}.  If both
 arguments are integers and @var{y} is positive, the result is an
 integer; in this case, overflow causes truncation, so watch out.
+If @var{x} is a finite negative number and @var{y} is a finite
+non-integer, @code{expt} returns a NaN.
 @end defun
 
 @defun sqrt arg
-This returns the square root of @var{arg}.  If @var{arg} is negative,
-it signals a @code{domain-error} error.
+This returns the square root of @var{arg}.  If @var{arg} is finite
+and less than zero, @code{sqrt} returns a NaN.
 @end defun
 
 In addition, Emacs defines the following common mathematical
@@ -1193,37 +1205,41 @@ The mathematical constant @math{pi} (3.14159@dots{}).
 @section Random Numbers
 @cindex random numbers
 
-A deterministic computer program cannot generate true random numbers.
-For most purposes, @dfn{pseudo-random numbers} suffice.  A series of
-pseudo-random numbers is generated in a deterministic fashion.  The
-numbers are not truly random, but they have certain properties that
-mimic a random series.  For example, all possible values occur equally
-often in a pseudo-random series.
-
-In Emacs, pseudo-random numbers are generated from a ``seed'' number.
-Starting from any given seed, the @code{random} function always
-generates the same sequence of numbers.  Emacs always starts with the
-same seed value, so the sequence of values of @code{random} is actually
-the same in each Emacs run!  For example, in one operating system, the
-first call to @code{(random)} after you start Emacs always returns
-@minus{}1457731, and the second one always returns @minus{}7692030.  This
-repeatability is helpful for debugging.
-
-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 @acronym{ID} number.
+  A deterministic computer program cannot generate true random
+numbers.  For most purposes, @dfn{pseudo-random numbers} suffice.  A
+series of pseudo-random numbers is generated in a deterministic
+fashion.  The numbers are not truly random, but they have certain
+properties that mimic a random series.  For example, all possible
+values occur equally often in a pseudo-random series.
+
+  Pseudo-random numbers are generated from a ``seed''.  Starting from
+any given seed, the @code{random} function always generates the same
+sequence of numbers.  By default, Emacs initializes the random seed at
+startup, in such a way that the sequence of values of @code{random}
+(with overwhelming likelihood) differs in each Emacs run.
+
+  Sometimes you want the random number sequence to be repeatable.  For
+example, when debugging a program whose behavior depends on the random
+number sequence, it is helpful to get the same behavior in each
+program run.  To make the sequence repeat, execute @code{(random "")}.
+This sets the seed to a constant value for your particular Emacs
+executable (though it may differ for other Emacs builds).  You can use
+other strings to choose various seed values.
 
 @defun random &optional limit
 This function returns a pseudo-random integer.  Repeated calls return a
 series of pseudo-random integers.
 
 If @var{limit} is a positive integer, the value is chosen to be
-nonnegative and less than @var{limit}.
+nonnegative and less than @var{limit}.  Otherwise, the value might be
+any integer representable in Lisp, i.e., an integer between
+@code{most-negative-fixnum} and @code{most-positive-fixnum}
+(@pxref{Integer Basics}).
+
+If @var{limit} is @code{t}, it means to choose a new seed as if Emacs
+were restarting.
 
-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 @acronym{ID} number.
+If @var{limit} is a string, it means to choose a new seed based on the
+string's contents.
 
-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