Spacing and punctuation fixes

[gnu-emacs] / doc / lispref / numbers.texi

diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi
index f19dea690363c363e237bac7daaa47e00258533d..8d1d3a798eb3e3be845c47571ee8f0f75283b2cb 100644 (file)
--- 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 -*-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.
 @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
 @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.
 
 @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.
 * 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
 * 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
 @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
 @ifnottex

--2**29
+@minus{}2**29

 @end ifnottex
 @tex
 @math{-2^{29}}
 @end tex
 to
 @ifnottex
 @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
 @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
 @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.}
  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
  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.)
 
 @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
 
 @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
 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.
 
 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
 @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
 
 @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
 @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
 
 @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
 
 @node Float Basics

-@section Floating Point Basics
+@section Floating-Point Basics

 
 @cindex @acronym{IEEE} floating point
 
 @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
 
 @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
 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
 
 @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
 
 @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:
 
 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
 @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},
 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
 
 @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
 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
 @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
 @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.
 
 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
 @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
 @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.
 
 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
 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,
 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}.
 
 @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)
 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)))
       (< (/ (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
 @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
 
 @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
 @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
 
 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
 
 @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
 
 @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
 
 @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.
 @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
 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.
 
 @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
 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.
 
 @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
 
 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
 @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
 
 @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
 @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)
 
 @example
 (round 1.2)


@@ -517,17 +548,15 @@ depending on your machine.
 @section Arithmetic Operations
 @cindex arithmetic operations
 
 @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
 @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.
 
 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
 
 @example
 @group
 (/ 6 2)
      @result{} 3
 @end group

+@group

 (/ 5 2)
      @result{} 2
 (/ 5 2)
      @result{} 2

+@end group
+@group

 (/ 5.0 2)
      @result{} 2.5
 (/ 5.0 2)
      @result{} 2.5

+@end group
+@group

 (/ 5 2.0)
      @result{} 2.5
 (/ 5 2.0)
      @result{} 2.5

+@end group
+@group

 (/ 5.0 2.0)
      @result{} 2.5
 (/ 5.0 2.0)
      @result{} 2.5

+@end group
+@group

 (/ 25 3 2)
      @result{} 4
 (/ 25 3 2)
      @result{} 4

+@end group

 @group
 (/ -17 6)
 @group
 (/ -17 6)

-     @result{} -2   @r{(could in theory be @minus{}3 on some machines)}
+     @result{} -2

 @end group
 @end example
 @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
 @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.
 
 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)
 
 @example
 (% 9 4)


@@ -669,18 +710,6 @@ An @code{arith-error} results if @var{divisor} is 0.
 (% -9 -4)
      @result{} -1
 @end example
 (% -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
 @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.
 
 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
 
 @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
 
 @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
 
 Conversions}.
 @end defun
 


@@ -740,30 +770,31 @@ Conversions}.
 @cindex rounding without conversion
 
 The functions @code{ffloor}, @code{fceiling}, @code{fround}, and
 @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
 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
 @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
 @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,
 @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
 @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
 
 @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
 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
 @end defun
 
 @defun asin arg


@@ -1097,8 +1128,8 @@ pi/2
 @tex
 @math{\pi/2}
 @end tex
 @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
 @end defun
 
 @defun acos arg


@@ -1109,8 +1140,8 @@ pi
 @tex
 @math{\pi}
 @end tex
 @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
 @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
 @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.
 @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
 @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
 @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
 
 @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
 
 @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
 @end defun