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

Improve doc for floating point ‘=’ vs ‘eql’

Browse source 
* doc/lispref/numbers.texi (Float Basics, Comparison of Numbers):
Improve documentation of ‘=’ vs ‘eq’, ‘eql’ and ‘equal’
when NaNs and signed zeros are involved.
This commit is contained in:
Paul Eggert 2018-07-19 13:29:28 -07:00
parent 3a91c5e4a2
commit 96d77f9eb8
1 changed files with 21 additions and 10 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

31
doc/lispref/numbers.texi
View file

@ -223,7 +223,7 @@ 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
with respect to numeric comparisons like @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.
@ -232,19 +232,26 @@ distinguish them.
@cindex negative infinity
@cindex infinity
@cindex NaN
@findex eql
@findex sxhash-eql
The @acronym{IEEE} floating-point standard supports positive
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@.
A NaN is never numerically equal to any value, not even to itself.
NaNs carry a sign and a significand, and non-numeric functions like
@code{eql} and @code{sxhash-eql} treat two NaNs as equal when their
NaNs carry a sign and a significand, and non-numeric functions treat
two NaNs as equal when their
signs and significands agree. Significands of NaNs are
machine-dependent and are not directly visible to Emacs Lisp.
When NaNs and signed zeros are involved, non-numeric functions like
@code{eql}, @code{equal}, @code{sxhash-eql}, @code{sxhash-equal} and
@code{gethash} determine whether values are indistinguishable, not
whether they are numerically equal. For example, when @var{x} and
@var{y} are the same NaN, @code{(equal x y)} returns @code{t} whereas
@code{(= x y)} uses numeric comparison and returns @code{nil};
conversely, @code{(equal 0.0 -0.0)} returns @code{nil} whereas
@code{(= 0.0 -0.0)} returns @code{t}.
Here are read syntaxes for these special floating-point values:
@table @asis
@ -359,11 +366,15 @@ if so, @code{nil} otherwise. The argument must be a number.
@cindex comparing numbers
To test numbers for numerical equality, you should normally use
@code{=}, not @code{eq}. There can be many distinct floating-point
objects with the same numeric value. If you use @code{eq} to
compare them, then you test whether two values are the same
@emph{object}. By contrast, @code{=} compares only the numeric values
of the objects.
@code{=} instead of non-numeric comparison predicates like @code{eq},
@code{eql} and @code{equal}. Distinct floating-point objects can be
numerically equal. If you use @code{eq} to compare them, you test
whether they are the same @emph{object}; if you use @code{eql} or
@code{equal}, you test whether their values are
@emph{indistinguishable}. In contrast, @code{=} uses numeric
comparison, and sometimes returns @code{t} when a non-numeric
comparison would return @code{nil} and vice versa. @xref{Float
Basics}.
In Emacs Lisp, each integer is a unique Lisp object.
Therefore, @code{eq} is equivalent to @code{=} where integers are