procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Clarify documentation wrt floating point division by zero and NaN

Browse source 
* doc/lispref/numbers.texi (Float Basics)
(Arithmetic Operations): Document what happens on a VAX.
Tested on NetBSD 9.3.
This commit is contained in:
Po Lu 2023-05-04 22:08:44 +08:00
parent 94e984e670
commit 2f3a514b6d
1 changed files with 26 additions and 13 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

39
doc/lispref/numbers.texi
View file

@ -219,17 +219,25 @@ creates huge integers.
@cindex @acronym{IEEE} floating point @cindex @acronym{IEEE} floating point
Floating-point numbers are useful for representing numbers that are Floating-point numbers are useful for representing numbers that are
not integral. The range of floating-point numbers is not integral. The range of floating-point numbers is the same as the
the same as the range of the C data type @code{double} on the machine range of the C data type @code{double} on the machine you are using.
you are using. On all computers supported by Emacs, this is On almost all computers supported by Emacs, this is @acronym{IEEE}
@acronym{IEEE} binary64 floating point format, which is standardized by binary64 floating point format, which is standardized by
@url{https://standards.ieee.org/standard/754-2019.html,,IEEE Std 754-2019} @url{https://standards.ieee.org/standard/754-2019.html,,IEEE Std
and is discussed further in David Goldberg's paper 754-2019} and is discussed further in David Goldberg's paper
``@url{https://docs.oracle.com/cd/E19957-01/806-3568/ncg_goldberg.html, ``@url{https://docs.oracle.com/cd/E19957-01/806-3568/ncg_goldberg.html,
What Every Computer Scientist Should Know About Floating-Point Arithmetic}''. What Every Computer Scientist Should Know About Floating-Point
On modern platforms, floating-point operations follow the IEEE-754 Arithmetic}''. On modern platforms, floating-point operations follow
standard closely; however, results are not always rounded correctly on the IEEE-754 standard closely; however, results are not always rounded
some obsolescent platforms, notably 32-bit x86. correctly on some systems, notably 32-bit x86.
On some old computer systems, Emacs may not use IEEE floating-point.
We know of one such system on which Emacs runs correctly, but does not
follow IEEE-754: the VAX running NetBSD using GCC 10.4.0, where the
VAX @samp{D_Floating} format is used instead. IBM System/370-derived
mainframes and their XL/C compiler are also capable of utilizing a
hexadecimal floating point format, but Emacs has not yet been built in
such a configuration.
The read syntax for floating-point numbers requires either a decimal The read syntax for floating-point numbers requires either a decimal
point, an exponent, or both. Optional signs (@samp{+} or @samp{-}) point, an exponent, or both. Optional signs (@samp{+} or @samp{-})
@ -262,6 +270,10 @@ two NaNs as equal when their
signs and significands agree. Significands of NaNs are signs and significands agree. Significands of NaNs are
machine-dependent, as are the digits in their string representation. machine-dependent, as are the digits in their string representation.
NaNs are not available on systems which do not use IEEE
floating-point arithmetic; if the read syntax for a NaN is used on a
VAX, for example, the reader signals an error.
When NaNs and signed zeros are involved, non-numeric functions like When NaNs and signed zeros are involved, non-numeric functions like
@code{eql}, @code{equal}, @code{sxhash-eql}, @code{sxhash-equal} and @code{eql}, @code{equal}, @code{sxhash-eql}, @code{sxhash-equal} and
@code{gethash} determine whether values are indistinguishable, not @code{gethash} determine whether values are indistinguishable, not
@ -742,9 +754,10 @@ by rounding the quotient towards zero after each division.
@cindex @code{arith-error} in division @cindex @code{arith-error} in division
If you divide an integer by the integer 0, Emacs signals an If you divide an integer by the integer 0, Emacs signals an
@code{arith-error} error (@pxref{Errors}). Floating-point division of @code{arith-error} error (@pxref{Errors}). On systems using IEEE-754
a nonzero number by zero yields either positive or negative infinity floating-point, floating-point division of a nonzero number by zero
(@pxref{Float Basics}). yields either positive or negative infinity (@pxref{Float Basics});
otherwise, an @code{arith-error} is signaled as usual.
@end defun @end defun
@defun % dividend divisor @defun % dividend divisor