bignum branch

[Paul Eggert <eggert@cs.ucla.edu>]

[-- Attachment #1: Type: text/plain, Size: 1030 bytes --]

On 07/18/2018 12:25 PM, Achim Gratz wrote:
> the established FP math says these
> two values should not compare equal anyway.

Sure, and = still does that. = is about numeric comparison; eql is about value 
comparison. Neither dominates the other: for example, they disagree about 0.0 vs 
-0.0 (= says they're equal, but eql says they're distinguishable values and so 
are not equal), and conversely they disagree about 0.0e+NaN versus 0.0e+NaN (= 
says they're not equal, whereas eql says they're indistinguishable values are so 
are equal).

> If you stray from that
> convention there should be a really good reason for that and it needs to
> be prominently documented.

There is good reason: eq, eql, and equal are about distinguishing objects (vital 
for hash tables, e.g.) whereas = is about numeric comparison. These are 
different things, and the numeric-comparison rule for NaNs is inconsistent with 
how hash tables should work. I gave a shot at documenting this by installing the 
attached patch.


[-- Attachment #2: 0001-Improve-doc-for-floating-point-vs-eql.txt --]
[-- Type: text/plain, Size: 3844 bytes --]

From 96d77f9eb882b68e994e187ed9c2156a23e3279d Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Thu, 19 Jul 2018 13:29:28 -0700
Subject: [PATCH] =?UTF-8?q?Improve=20doc=20for=20floating=20point=20?=
 =?UTF-8?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=UTF-8
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 6c51b84..70bb103 100644
--- a/doc/lispref/numbers.texi
+++ b/doc/lispref/numbers.texi
@@ -223,7 +223,7 @@ Float Basics
 @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 @@ Float Basics
 @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 @@ Comparison of Numbers
 @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.7.4