From 1917cf46bba74cdd0bcd1d0545cbd688db4e76f9 Mon Sep 17 00:00:00 2001 From: Paul Eggert Date: Mon, 17 Mar 2014 21:03:59 -0700 Subject: [PATCH] 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. --- doc/lispref/ChangeLog | 11 +++ doc/lispref/numbers.texi | 158 +++++++++++++++++++++++---------------- doc/lispref/objects.texi | 14 ++-- 3 files changed, 111 insertions(+), 72 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 639d7e2dc9..8bf25baeee 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,14 @@ +2014-03-18 Paul Eggert + + 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 * functions.texi (Advising Functions): Try and improve the text. diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi index d202877e8a..1758a44baa 100644 --- a/doc/lispref/numbers.texi +++ b/doc/lispref/numbers.texi @@ -9,13 +9,14 @@ @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. @@ -34,7 +35,7 @@ exact; they have a fixed, limited amount of precision. @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 @@ 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 @@ -148,15 +150,43 @@ value is a marker, its position value is used and its buffer is ignored. @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 @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 In Emacs Lisp, text characters are represented by integers. Any @@ -168,22 +198,25 @@ considered to be valid as a character. @xref{String 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, 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 -@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 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. +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 @@ -193,58 +226,53 @@ distinguishable in the @acronym{IEEE} floating-point standard. 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.) - -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 -non-@acronym{IEEE} platforms it returns an implementation-defined -value. +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 the read syntaxes for these special floating-point values: +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, @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, @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 @@ 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 @@ -532,8 +560,8 @@ 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. - 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 diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi index 086abecded..4e8182ccf3 100644 --- a/doc/lispref/objects.texi +++ b/doc/lispref/objects.texi @@ -161,8 +161,8 @@ latter are unique to Emacs Lisp. @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 @@ to @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 -@code{(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 +@code{(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 @@ this records a power of 2 rather than a power of 10. The printed representation for floating-point numbers requires either a decimal point (with at least one digit following), an exponent, or -both. For example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, -@samp{1.5e3}, and @samp{.15e4} are five ways of writing a floating-point +both. 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. @xref{Numbers}, for more information. -- 2.20.1