From 96d77f9eb882b68e994e187ed9c2156a23e3279d Mon Sep 17 00:00:00 2001 From: Paul Eggert Date: Thu, 19 Jul 2018 13:29:28 -0700 Subject: [PATCH] =?utf8?q?Improve=20doc=20for=20floating=20point=20?= =?utf8?q?=E2=80=98=3D=E2=80=99=20vs=20=E2=80=98eql=E2=80=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit * doc/lispref/numbers.texi (Float Basics, Comparison of Numbers): Improve documentation of ‘=’ vs ‘eq’, ‘eql’ and ‘equal’ when NaNs and signed zeros are involved. --- doc/lispref/numbers.texi | 31 +++++++++++++++++++++---------- 1 file changed, 21 insertions(+), 10 deletions(-) diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi index 6c51b849d35..70bb1030411 100644 --- a/doc/lispref/numbers.texi +++ b/doc/lispref/numbers.texi @@ -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 -- 2.39.2