diff --git a/src/java.base/share/classes/java/lang/Double.java b/src/java.base/share/classes/java/lang/Double.java index a321aeff914..b699b1e94ea 100644 --- a/src/java.base/share/classes/java/lang/Double.java +++ b/src/java.base/share/classes/java/lang/Double.java @@ -58,7 +58,7 @@ import jdk.internal.vm.annotation.IntrinsicCandidate; * * IEEE 754 floating-point values include finite nonzero values, * signed zeros ({@code +0.0} and {@code -0.0}), signed infinities - * {@linkplain Double#POSITIVE_INFINITY positive infinity} and + * ({@linkplain Double#POSITIVE_INFINITY positive infinity} and * {@linkplain Double#NEGATIVE_INFINITY negative infinity}), and * {@linkplain Double#NaN NaN} (not-a-number). * @@ -116,12 +116,13 @@ import jdk.internal.vm.annotation.IntrinsicCandidate; *

To provide the appropriate semantics for {@code equals} and * {@code compareTo} methods, those methods cannot simply be wrappers * around {@code ==} or ordered comparison operations. Instead, {@link - * Double#equals equals} defines NaN arguments to be equal to each - * other and defines {@code +0.0} to not be equal to {@code - * -0.0}, restoring reflexivity. For comparisons, {@link - * Double#compareTo compareTo} defines a total order where {@code - * -0.0} is less than {@code +0.0} and where a NaN is equal to itself - * and considered greater than positive infinity. + * Double#equals equals} uses representation + * equivalence, defining NaN arguments to be equal to each other, + * restoring reflexivity, and defining {@code +0.0} to not be + * equal to {@code -0.0}. For comparisons, {@link Double#compareTo + * compareTo} defines a total order where {@code -0.0} is less than + * {@code +0.0} and where a NaN is equal to itself and considered + * greater than positive infinity. * *

The operational semantics of {@code equals} and {@code * compareTo} are expressed in terms of {@linkplain #doubleToLongBits @@ -143,6 +144,62 @@ import jdk.internal.vm.annotation.IntrinsicCandidate; * elements of a {@link java.util.SortedSet SortedSet} or as keys of a * {@link java.util.SortedMap SortedMap}. * + *

Comparing numerical equality to various useful equivalence + * relations that can be defined over floating-point values: + * + *

+ *
numerical equality ({@code ==} + * operator): (Not an equivalence relation)
+ *
Two floating-point values represent the same extended real + * number. The extended real numbers are the real numbers augmented + * with positive infinity and negative infinity. Under numerical + * equality, {@code +0.0} and {@code -0.0} are equal since they both + * map to the same real value, 0. A NaN does not map to any real + * number and is not equal to any value, including itself. + *
+ * + *
bit-wise equivalence:
+ *
The bits of the two floating-point values are the same. This + * equivalence relation for {@code double} values {@code a} and {@code + * b} is implemented by the expression + *
{@code Double.doubleTo}Raw{@code LongBits(a) == Double.doubleTo}Raw{@code LongBits(b)}
+ * Under this relation, {@code +0.0} and {@code -0.0} are + * distinguished from each other and every bit pattern encoding a NaN + * is distinguished from every other bit pattern encoding a NaN. + *
+ * + *
representation equivalence:
+ *
The two floating-point values represent the the same IEEE 754 + * datum. In particular, for {@linkplain #isFinite(double) + * finite} values, the sign, {@linkplain Math#getExponent(double) + * exponent}, and significand components of the + * floating-point values are the same. Under this relation: + * + * Expressions implementing this equivalence relation include: + * + * Note that representation equivalence is often an appropriate notion + * of equivalence to test the behavior of {@linkplain StrictMath math + * libraries}. + *
+ *
+ * + * For two binary floating-point values {@code a} and {@code b}, if + * neither of {@code a} and {@code b} is zero or NaN, then the three + * relations numerical equality, bit-wise equivalence, and + * representation equivalence of {@code a} and {@code b} have the same + * {@code true}/{@code false} value. In other words, for binary + * floating-point values, the three relations only differ if at least + * one argument is zero or NaN. + * * @jls 4.2.3 Floating-Point Types, Formats, and Values * @jls 4.2.4. Floating-Point Operations * @jls 15.21.1 Numerical Equality Operators == and != diff --git a/src/java.base/share/classes/java/math/BigDecimal.java b/src/java.base/share/classes/java/math/BigDecimal.java index a2003c382c6..017910eaae4 100644 --- a/src/java.base/share/classes/java/math/BigDecimal.java +++ b/src/java.base/share/classes/java/math/BigDecimal.java @@ -3087,6 +3087,10 @@ public class BigDecimal extends Number implements Comparable { * @apiNote * Note: this class has a natural ordering that is inconsistent with equals. + * The behavior of comparing the result of this method for + * equality to 0 is analogous to checking the numerical + * equality of {@code double} values. * * @param val {@code BigDecimal} to which this {@code BigDecimal} is * to be compared. @@ -3179,6 +3183,9 @@ public class BigDecimal extends Number implements Comparable { * HALF_UP)} which evaluates to 0.7 and
* {@code new BigDecimal("2.00").divide(BigDecimal.valueOf(3), * HALF_UP)} which evaluates to 0.67. + * The behavior of this method is analogous to checking the representation + * equivalence of {@code double} values. * * @param x {@code Object} to which this {@code BigDecimal} is * to be compared.