RFR: JDK-8294539: Augment discussion of equivlance relations on floating-point values

[John R Rose]

On Thu, 29 Sep 2022 22:14:24 GMT, Joe Darcy <darcy at openjdk.org> wrote:

> While the floating-point == operation is *not* an equivalence relation, there are useful equivalence relations that can be defined over floating-point values. Text is added to java.lang.Double to discuss and name those relations.

src/java.base/share/classes/java/lang/Double.java line 157:

> 155:  * Under this relation, {@code +0.0} and {@code -0.0} are distinguished
> 156:  * from each other and every bit pattern encoding a NaN is distinguished
> 157:  * form other bit patterns encoding a NaN.

s/form/from

src/java.base/share/classes/java/lang/Double.java line 180:

> 178:  * of equivalence to test the behavior of {@linkplain StrictMath math
> 179:  * libraries}.
> 180:  * </dd>

This list deserves to include the not-quite-equivalence relation `==`.  Suggest:

 - numerical equivalence
 - {@code +0.0} and {@code -0.0} are equivalent to each other.
 - infinite numbers of the same sign are equivalent to each other

The two floating point numbers represent the same mathematical finite value or signed infinity.

Expressions implementing this ER include `x == y`, `x > y | x < y`, etc.

Numerical equivalence does not apply to NaN, as NaN violates the reflexive property required of all equivalences, but on the domain of all non-NaNs, numerical equivalence is in fact an equivalence relation.

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

PR: https://git.openjdk.org/jdk/pull/10498