[Emacs-diffs] trunk r116789: Improve documentation for integer and floating-point basics.

[Paul Eggert]

------------------------------------------------------------
revno: 116789
revision-id: address@hidden
parent: address@hidden
committer: Paul Eggert <address@hidden>
branch nick: trunk
timestamp: Mon 2014-03-17 21:03:59 -0700
message:
  Improve documentation for integer and floating-point basics.
  
  * numbers.texi (Numbers, Integer Basics, Float Basics):
  Document the basics a bit more precisely.  Say more clearly
  that Emacs floating-point numbers are IEEE doubles on all
  current platforms.  Give more details about frexp.
  Say more clearly that '1.' is an integer.
  (Predicates on Numbers): Fix wholenump typo.
  * objects.texi (Integer Type): Adjust to match numbers.texi.
modified:
  doc/lispref/ChangeLog          changelog-20091113204419-o5vbwnq5f7feedwu-6155
  doc/lispref/numbers.texi       
numbers.texi-20091113204419-o5vbwnq5f7feedwu-6203
  doc/lispref/objects.texi       
objects.texi-20091113204419-o5vbwnq5f7feedwu-6204

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2014-03-18 03:22:59 +0000
+++ b/doc/lispref/ChangeLog     2014-03-18 04:03:59 +0000
@@ -1,3 +1,14 @@
+2014-03-18  Paul Eggert  <address@hidden>
+
+       Improve documentation for integer and floating-point basics.
+       * numbers.texi (Numbers, Integer Basics, Float Basics):
+       Document the basics a bit more precisely.  Say more clearly
+       that Emacs floating-point numbers are IEEE doubles on all
+       current platforms.  Give more details about frexp.
+       Say more clearly that '1.' is an integer.
+       (Predicates on Numbers): Fix wholenump typo.
+       * objects.texi (Integer Type): Adjust to match numbers.texi.
+
 2014-03-18  Stefan Monnier  <address@hidden>
 
        * functions.texi (Advising Functions): Try and improve the text.

=== modified file 'doc/lispref/numbers.texi'
--- a/doc/lispref/numbers.texi  2014-03-18 01:19:03 +0000
+++ b/doc/lispref/numbers.texi  2014-03-18 04:03:59 +0000
@@ -9,13 +9,14 @@
 @cindex numbers
 
   GNU Emacs supports two numeric data types: @dfn{integers} and
address@hidden point numbers}.  Integers are whole numbers such as
address@hidden, 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.
address@hidden numbers}.  Integers are whole numbers such as
address@hidden, 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
address@hidden; 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.
@@ -34,7 +35,7 @@
 @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
 @minus{}2**29
 @end ifnottex
@@ -61,7 +62,8 @@
  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
@@ -148,15 +150,43 @@
 @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
address@hidden
+2**29 @minus{} 1
address@hidden ifnottex
address@hidden
address@hidden
address@hidden tex
+on 32-bit and
address@hidden
+2**61 @minus{} 1
address@hidden ifnottex
address@hidden
address@hidden
address@hidden tex
+on 64-bit platforms.
 @end defvar
 
 @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
address@hidden
address@hidden
address@hidden ifnottex
address@hidden
address@hidden
address@hidden tex
+on 32-bit and
address@hidden
address@hidden
address@hidden ifnottex
address@hidden
address@hidden
address@hidden tex
+on 64-bit platforms.
 @end defvar
 
   In Emacs Lisp, text characters are represented by integers.  Any
@@ -168,22 +198,25 @@
 
 @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
address@hidden on the machine you are using.  Emacs uses the
address@hidden floating-point standard, which is supported by all
-modern computers.
+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 (with at least one digit following), an exponent, or both.  For
-example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, @samp{1.5e3}, and
address@hidden 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}.
+point, an exponent, or both.  Optional signs (@samp{+} or @samp{-})
+precede the number and its exponent.  For example, @samp{1500.0},
address@hidden, @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;
address@hidden 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{=}), even though the two are
-distinguishable in the @acronym{IEEE} floating-point standard.
+  Emacs Lisp treats @code{-0.0} as numerically equal to ordinary zero
+with respect to @code{equal} and @code{=}.  This follows the
address@hidden floating-point standard, which says @code{-0.0} and
address@hidden are numerically equal even though other operations can
+distinguish them.
 
 @cindex positive infinity
 @cindex negative infinity
@@ -193,58 +226,53 @@
 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 address@hidden  (NaN
-values can also carry a sign, but for practical purposes there's no
-significant difference between different NaN values in Emacs Lisp.)
-
-When a function is documented to return a NaN, it returns an
-implementation-defined value when Emacs is running on one of the
-now-rare platforms that do not use @acronym{IEEE} floating point.  For
-example, @code{(log -1.0)} typically returns a NaN, but on
address@hidden platforms it returns an implementation-defined
-value.
-
-Here are the read syntaxes for these special floating-point values:
+correct answer.  For example, @code{(/ 0.0 0.0)} returns a address@hidden
+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
address@hidden positive infinity
address@hidden
address@hidden negative infinity
address@hidden
address@hidden Not-a-number
address@hidden or @samp{-0.0e+NaN}.
address@hidden infinity
address@hidden and @samp{-1.0e+INF}
address@hidden not-a-number
address@hidden and @samp{-0.0e+NaN}
 @end table
 
address@hidden 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.
address@hidden defun
-
-  The following functions are specialized for handling floating point
+  The following functions are specialized for handling floating-point
 numbers:
 
address@hidden isnan x
+This predicate returns @code{t} if its floating-point argument is a NaN,
address@hidden otherwise.
address@hidden defun
+
 @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}:
-
address@hidden
address@hidden = @var{sig} * address@hidden
address@hidden smallexample
-
address@hidden 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)}.
+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}.
+
+If @var{x} is finite, @var{s} is a floating-point number between 0.5
+(inclusive) and 1.0 (exclusive), @var{e} is an integer, and
address@hidden
address@hidden = @var{s} * address@hidden
address@hidden ifnottex
address@hidden
address@hidden = s 2^e}.
address@hidden tex
+If @var{x} is zero or infinity, @var{s} is the same as @var{x}.
+If @var{x} is a NaN, @var{s} is also a NaN.
+If @var{x} is zero, @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
@@ -293,8 +321,8 @@
 returns @code{t} if so, @code{nil} otherwise.  0 is considered
 non-negative.
 
address@hidden wholenump number
-This is a synonym for @code{natnump}.
address@hidden wholenump
address@hidden is a synonym for @code{natnump}.
 @end defun
 
 @defun zerop number
@@ -532,8 +560,8 @@
 floating-point arguments, and returns a floating-point number if any
 argument is floating point.
 
-  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

=== modified file 'doc/lispref/objects.texi'
--- a/doc/lispref/objects.texi  2014-03-18 01:19:03 +0000
+++ b/doc/lispref/objects.texi  2014-03-18 04:03:59 +0000
@@ -161,8 +161,8 @@
 @node Integer Type
 @subsection Integer Type
 
-  The range of values for integers in Emacs Lisp is @minus{}536870912 to
-536870911 (30 bits; i.e.,
+  The range of values for an integer depends on the machine.  The
+minimum range is @minus{}536,870,912 to 536,870,911 (30 bits; i.e.,
 @ifnottex
 @minus{}2**29
 @end ifnottex
@@ -176,9 +176,9 @@
 @tex
 @math{2^{29}-1})
 @end tex
-on typical 32-bit machines.  (Some machines provide a wider range.)
-Emacs Lisp arithmetic functions do not check for overflow.  Thus
address@hidden(1+ 536870911)} is @minus{}536870912 if Emacs integers are 30 
bits.
+but many machines provide a wider range.
+Emacs Lisp arithmetic functions do not check for integer overflow.  Thus
address@hidden(1+ 536870911)} is @minus{}536,870,912 if Emacs integers are 30 
bits.
 
   The read syntax for integers is a sequence of (base ten) digits with an
 optional sign at the beginning and an optional period at the end.  The
@@ -215,8 +215,8 @@
 
   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},
address@hidden, and @samp{.15e4} are five ways of writing a floating-point
+both.  For example, @samp{1500.0}, @samp{+15e2}, @samp{15.0e+2},
address@hidden, and @samp{.15e4} are five ways of writing a floating-point
 number whose value is 1500.  They are all equivalent.
 
   @xref{Numbers}, for more information.