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.
This commit is contained in:
Paul Eggert
parent
53e84c5f28
commit
1917cf46bb
3 changed files with 110 additions and 71 deletions
|
|
@ -1,3 +1,14 @@
|
|||
2014-03-18 Paul Eggert <eggert@cs.ucla.edu>
|
||||
|
||||
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 <monnier@iro.umontreal.ca>
|
||||
|
||||
* 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}.
|
||||
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{=}), 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
|
||||
@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.)
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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 isnan x
|
||||
This predicate returns @code{t} if its floating-point argument is a NaN,
|
||||
@code{nil} otherwise.
|
||||
@end 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}:
|
||||
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}.
|
||||
|
||||
@smallexample
|
||||
@var{x} = @var{sig} * 2^@var{exp}
|
||||
@end smallexample
|
||||
|
||||
@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.
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue