Commit 1917cf46 by 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.```
parent 53e84c5f
 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. ... ...
 ... ... @@ -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 ... ...
 ... ... @@ -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. ... ...
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!