Commit 1917cf46 authored by Paul Eggert's avatar 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 <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}.
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!
Please register or to comment