diff options
Diffstat (limited to 'doc/lispref/numbers.texi')
| -rw-r--r-- | doc/lispref/numbers.texi | 36 |
1 files changed, 26 insertions, 10 deletions
diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi index d9fb43258ea..89205f9df39 100644 --- a/doc/lispref/numbers.texi +++ b/doc/lispref/numbers.texi @@ -213,7 +213,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. @@ -227,8 +227,20 @@ 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@. -Although NaN values carry a sign, for practical purposes there is no other -significant difference between different NaN values in Emacs Lisp. +A NaN is never numerically equal to any value, not even to itself. +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, as are the digits in their string representation. + + 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: @@ -358,11 +370,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 -and large integer 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 and large +integer 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 small integer is a unique Lisp object. Therefore, @code{eq} is equivalent to @code{=} where small integers are @@ -829,7 +845,7 @@ reproducing the same pattern moved over. bits in @var{integer1} to the left @var{count} places, or to the right if @var{count} is negative, bringing zeros into the vacated bits. If @var{count} is negative, @code{lsh} shifts zeros into the leftmost -(most-significant) bit, producing a positive result even if +(most-significant) bit, producing a nonnegative result even if @var{integer1} is negative. Contrast this with @code{ash}, below. Here are two examples of @code{lsh}, shifting a pattern of bits one @@ -1167,7 +1183,7 @@ returns a NaN. @defun expt x y This function returns @var{x} raised to power @var{y}. If both -arguments are integers and @var{y} is positive, the result is an +arguments are integers and @var{y} is nonnegative, the result is an integer; in this case, overflow causes truncation, so watch out. If @var{x} is a finite negative number and @var{y} is a finite non-integer, @code{expt} returns a NaN. |