[m-dev.] [m-users.] Comparison in the reference manual

[Mark Brown]

On Mon, Nov 23, 2015 at 11:10 AM, Julien Fischer <jfischer at opturion.com> wrote:
>
> Hi Mark,
>
> On Tue, 17 Nov 2015, Mark Brown wrote:
>
>>>> float: We can at least say that < and > never contradict the
>>>> mathematical ordering, even if = can due to lack of precision. Can we
>>>> assume implementations may use +/- infinity?
>>>
>>>
>>>
>>> If we are assuming IEEE 754 floats, yes.   For all of our current
>>> backends that is definitely yes.
>>
>>
>> For ints and floats I've decided to keep it conservative, and just say
>> that implementations are allowed to be inconsistent if literals are
>> out-of-range.
>
>
> I think that's too conservative.  The implementation should just reject
> int literals that will overflow (i.e. what is does now).  For systems
> with IEEE floats we should replace overflows with +/- infinity.  What to
> do on systems that don't provide IEEE fp is a more open question, but we
> don't currently have any of those.

Okay. Note that I have used "should", and not "may" or "must". Just
checking that this is what you meant.

> Ignoring the matter of NaNs for a moment, the order for floats should be
> specified as it is in, for example, Java and C#:
>
>   -infinity < -max < ... < -min < -0.0 == +0.0 < +min < ... < +max <
> +infinity

Done.

>
> Not-a-number (NaN) values complicate matters.  The current implementation of
> builtin.compare/3 is broken, for example the following evaluates to true:
>
>     NaN = 0.0 * infinity,
>     compare((=), NaN, 0.0)
>
> but:
>
>     NaN = 0.0 * infinity,
>     unify(NaN, 0.0)
>
> evaluates to false.
>
> The IEEE 754-2008 standard (section 5.10) defines a total ordering on float
> values, but I don't think that will work for us.  Java's Double.CompareTo
> method treats NaN values as equal to themselves and greater than all other
> float values (including +infinity), mainly so that you can use them in data
> structures.  IIRC, C# does something similar.
>
> My inclination is that we should simply make builtin.compare/3 throw an
> exception for NaN values on the basis that they are not ordered w.r.t other
> float values (or indeed themselves).

Fine by me.

> For completeness, you should say something about strings here too (e.g.
> what's currently in the comment at the head of the string module.)

Done.

Additional diff is attached. I'll commit the change soon if there are
no further comments.

Thanks,
Mark
-------------- next part --------------
diff --git a/doc/reference_manual.texi b/doc/reference_manual.texi
index 64a72e3..ba43b40 100644
--- a/doc/reference_manual.texi
+++ b/doc/reference_manual.texi
@@ -2543,20 +2543,32 @@ As such, the standard ordering for most types is not fully defined.
 
 For the builtin type @code{int},
 the standard ordering is the usual numerical ordering.
-Implementations are permitted to give inconsistent results
-for overflowing literals.
+Implementations should reject code containing overflowing integer literals.
 
 For the builtin type @code{float},
 the standard ordering approximates the usual numerical ordering.
 If the result of @code{builtin.compare/3} is @code{(<)} or @code{(>)}
 then this relation holds in the numerical ordering,
 but this is not necessarily the case for @code{(=)} due to lack of precision.
-Implementations are permitted to give inconsistent results
-for overflowing literals.
+In the standard ordering, ``negative'' and ``positive'' zero values are equal.
+Implementations should replace overflowing literals
+with the infinity of the same sign;
+in the standard ordering positive infinity is greater than all finite values
+and negative infinity is less than all finite values.
+Implementations must throw an exception when comparing
+a ``not a number'' (NaN) value.
 
 For the builtin type @code{char}, the standard ordering is
 the numerical ordering of the Unicode code point values.
 
+For the builtin type @code{string},
+the standard ordering is implementation dependent.
+The current implementation performs string comparison using
+the C @code{strcmp()} function,
+the Java @code{String.compareTo()} method, and
+the C# @code{System.String.CompareOrdinal()} method,
+when compiling to C, Java and C#, respectively.
+
 For tuple types, corresponding arguments are compared,
 with the first argument being the most significant.