RFR: 8310033: Clarify return value of Java Time compareTo methods [v3]

[Joe Darcy]

On Wed, 21 Jun 2023 16:29:40 GMT, Roger Riggs <rriggs at openjdk.org> wrote:

>> In java.time packages, clarify timeline order javadoc to mention "before" and "after" in the value of the `compareTo` method return values. 
>> Add javadoc @see tags to isBefore and isAfter methods
>> 
>> Replace use of "negative" and positive with "less than zero" and "greater than zero" in javadoc @return
>> The term "positive" is ambiguous, zero is considered positive and indicates equality.
>
> Roger Riggs has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Clarify return values of date time classes

> 

Adding a bit more context, floating-point arithmetic is an approximation to real arithmetic. Real arithmetic has a single zero value. The signed zeros of IEEE 754 floating-point are a computational artifact.

More specifically, IEEE 754 floating-point is an approximation to the real numbers extended with infinite values. There are two ways to extend the reals with infinity: affine (signed infinities) and projective (one unsigned infinity). Early drafts of the IEEE 754 standard supported both affine and project infinity, as did the original 8087 floating-point which predated IEEE 754. The final IEEE 754 only supports signed infinities and because there are two infinities, there are two distinguished (but numerically equal) zero values.

The floating-point signum methods in the Java math library return a same-signed zero for a zero input; +1.0 is *not* returned for +0.0 and -1.0 is *not* returned for -0.0. While a zero value has a sign bit in its representation, neither zero value is "positive" or "negative" in the mathematical sense of the term.

-------------

PR Comment: https://git.openjdk.org/jdk/pull/14479#issuecomment-1610132362