diff --git a/src/java.base/share/classes/java/lang/Double.java b/src/java.base/share/classes/java/lang/Double.java index 277e1c14480..5f4c0b3f40f 100644 --- a/src/java.base/share/classes/java/lang/Double.java +++ b/src/java.base/share/classes/java/lang/Double.java @@ -116,8 +116,8 @@ 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} uses representation - * equivalence, defining NaN arguments to be equal to each other, + * Double#equals equals} uses {@linkplain ##repEquivalence 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 @@ -591,6 +591,23 @@ public final class Double extends Number *

To create localized string representations of a floating-point * value, use subclasses of {@link java.text.NumberFormat}. * + * @apiNote + * This method corresponds to the general functionality of the + * convertToDecimalCharacter operation defined in IEEE 754; + * however, that operation is defined in terms of specifying the + * number of significand digits used in the conversion. + * Code to do such a conversion in the Java platform includes + * converting the {@code double} to a {@link java.math.BigDecimal + * BigDecimal} exactly and then rounding the {@code BigDecimal} to + * the desired number of digits; sample code: + * {@snippet lang=java : + * double d = 0.1; + * int digits = 25; + * BigDecimal bd = new BigDecimal(d); + * String result = bd.round(new MathContext(digits, RoundingMode.HALF_UP)); + * // 0.1000000000000000055511151 + * } + * * @param d the {@code double} to be converted. * @return a string representation of the argument. */ @@ -671,6 +688,11 @@ public final class Double extends Number * {@code 0x0.0000000000001p-1022} * * + * + * @apiNote + * This method corresponds to the convertToHexCharacter operation + * defined in IEEE 754. + * * @param d the {@code double} to be converted. * @return a hex string representation of the argument. * @since 1.5 @@ -897,6 +919,10 @@ public final class Double extends Number * where {@code l} is the desired locale, or * {@link java.util.Locale#ROOT} if locale insensitive. * + * @apiNote + * This method corresponds to the convertFromDecimalCharacter and + * convertFromHexCharacter operations defined in IEEE 754. + * * @param s the string to be parsed. * @return a {@code Double} object holding the value * represented by the {@code String} argument. @@ -1087,6 +1113,7 @@ public final class Double extends Number * @jls 5.1.3 Narrowing Primitive Conversion * @since 1.1 */ + @Override public byte byteValue() { return (byte)value; } @@ -1100,6 +1127,7 @@ public final class Double extends Number * @jls 5.1.3 Narrowing Primitive Conversion * @since 1.1 */ + @Override public short shortValue() { return (short)value; } @@ -1109,9 +1137,14 @@ public final class Double extends Number * after a narrowing primitive conversion. * @jls 5.1.3 Narrowing Primitive Conversion * + * @apiNote + * This method corresponds to the convertToIntegerTowardZero + * operation defined in IEEE 754. + * * @return the {@code double} value represented by this object * converted to type {@code int} */ + @Override public int intValue() { return (int)value; } @@ -1120,10 +1153,15 @@ public final class Double extends Number * Returns the value of this {@code Double} as a {@code long} * after a narrowing primitive conversion. * + * @apiNote + * This method corresponds to the convertToIntegerTowardZero + * operation defined in IEEE 754. + * * @return the {@code double} value represented by this object * converted to type {@code long} * @jls 5.1.3 Narrowing Primitive Conversion */ + @Override public long longValue() { return (long)value; } @@ -1141,6 +1179,7 @@ public final class Double extends Number * @jls 5.1.3 Narrowing Primitive Conversion * @since 1.0 */ + @Override public float floatValue() { return (float)value; } @@ -1150,6 +1189,7 @@ public final class Double extends Number * * @return the {@code double} value represented by this object */ + @Override @IntrinsicCandidate public double doubleValue() { return value; @@ -1210,9 +1250,8 @@ public final class Double extends Number * on {@code double} values since the {@code ==} operator does * not define an equivalence relation and to satisfy the * {@linkplain Object#equals equals contract} an equivalence - * relation must be implemented; see this discussion for details of - * floating-point equality and equivalence. + * relation must be implemented; see {@linkplain ##equivalenceRelation + * this discussion for details of floating-point equality and equivalence}. * * @see java.lang.Double#doubleToLongBits(double) * @jls 15.21.1 Numerical Equality Operators == and != @@ -1389,9 +1428,9 @@ public final class Double extends Number * This ensures that the natural ordering of {@code Double} * objects imposed by this method is consistent with - * equals; see this - * discussion for details of floating-point comparison and - * ordering. + * equals; see {@linkplain ##equivalenceRelation this + * discussion for details of floating-point comparison and + * ordering}. * * @param anotherDouble the {@code Double} to be compared. * @return the value {@code 0} if {@code anotherDouble} is @@ -1405,6 +1444,7 @@ public final class Double extends Number * @jls 15.20.1 Numerical Comparison Operators {@code <}, {@code <=}, {@code >}, and {@code >=} * @since 1.2 */ + @Override public int compareTo(Double anotherDouble) { return Double.compare(value, anotherDouble.value); } diff --git a/src/java.base/share/classes/java/lang/Float.java b/src/java.base/share/classes/java/lang/Float.java index 63a4cc0fab2..02b66007773 100644 --- a/src/java.base/share/classes/java/lang/Float.java +++ b/src/java.base/share/classes/java/lang/Float.java @@ -307,6 +307,23 @@ public final class Float extends Number *

To create localized string representations of a floating-point * value, use subclasses of {@link java.text.NumberFormat}. * + * @apiNote + * This method corresponds to the general functionality of the + * convertToDecimalCharacter operation defined in IEEE 754; + * however, that operation is defined in terms of specifying the + * number of significand digits used in the conversion. + * Code to do such a conversion in the Java platform includes + * converting the {@code float} to a {@link java.math.BigDecimal + * BigDecimal} exactly and then rounding the {@code BigDecimal} to + * the desired number of digits; sample code: + * {@snippet lang=java : + * floatf = 0.1f; + * int digits = 15; + * BigDecimal bd = new BigDecimal(f); + * String result = bd.round(new MathContext(digits, RoundingMode.HALF_UP)); + * // 0.100000001490116 + * } + * * @param f the {@code float} to be converted. * @return a string representation of the argument. */ @@ -387,6 +404,11 @@ public final class Float extends Number * {@code 0x0.000002p-126} * * + * + * @apiNote + * This method corresponds to the convertToHexCharacter operation + * defined in IEEE 754. + * * @param f the {@code float} to be converted. * @return a hex string representation of the argument. * @since 1.5 @@ -524,6 +546,10 @@ public final class Float extends Number * where {@code l} is the desired locale, or * {@link java.util.Locale#ROOT} if locale insensitive. * + * @apiNote + * This method corresponds to the convertFromDecimalCharacter and + * convertFromHexCharacter operations defined in IEEE 754. + * * @param s the string to be parsed. * @return a {@code Float} object holding the value * represented by the {@code String} argument. @@ -729,6 +755,7 @@ public final class Float extends Number * converted to type {@code byte} * @jls 5.1.3 Narrowing Primitive Conversion */ + @Override public byte byteValue() { return (byte)value; } @@ -742,6 +769,7 @@ public final class Float extends Number * @jls 5.1.3 Narrowing Primitive Conversion * @since 1.1 */ + @Override public short shortValue() { return (short)value; } @@ -750,10 +778,15 @@ public final class Float extends Number * Returns the value of this {@code Float} as an {@code int} after * a narrowing primitive conversion. * + * @apiNote + * This method corresponds to the convertToIntegerTowardZero + * operation defined in IEEE 754. + * * @return the {@code float} value represented by this object * converted to type {@code int} * @jls 5.1.3 Narrowing Primitive Conversion */ + @Override public int intValue() { return (int)value; } @@ -762,10 +795,15 @@ public final class Float extends Number * Returns value of this {@code Float} as a {@code long} after a * narrowing primitive conversion. * + * @apiNote + * This method corresponds to the convertToIntegerTowardZero + * operation defined in IEEE 754. + * * @return the {@code float} value represented by this object * converted to type {@code long} * @jls 5.1.3 Narrowing Primitive Conversion */ + @Override public long longValue() { return (long)value; } @@ -775,6 +813,7 @@ public final class Float extends Number * * @return the {@code float} value represented by this object */ + @Override @IntrinsicCandidate public float floatValue() { return value; @@ -792,6 +831,7 @@ public final class Float extends Number * object converted to type {@code double} * @jls 5.1.2 Widening Primitive Conversion */ + @Override public double doubleValue() { return (double)value; } @@ -839,9 +879,8 @@ public final class Float extends Number * {@code float} values since the {@code ==} operator does * not define an equivalence relation and to satisfy the * {@linkplain Object#equals equals contract} an equivalence - * relation must be implemented; see this discussion for - * details of floating-point equality and equivalence. + * relation must be implemented; see {@linkplain Double##equivalenceRelation + * this discussion for details of floating-point equality and equivalence}. * * @param obj the object to be compared * @return {@code true} if the objects are the same; @@ -1092,7 +1131,7 @@ public final class Float extends Number *

  • If the argument is a NaN, the result is a NaN. * * - * The binary16 format is discussed in + * The {@linkplain ##binary16Format binary16 format} is discussed in * more detail in the {@link #float16ToFloat} method. * * @apiNote @@ -1208,9 +1247,9 @@ public final class Float extends Number * * This ensures that the natural ordering of {@code Float} * objects imposed by this method is consistent with - * equals; see this - * discussion for details of floating-point comparison and - * ordering. + * equals; see {@linkplain Double##equivalenceRelation this + * discussion for details of floating-point comparison and + * ordering}. * * * @param anotherFloat the {@code Float} to be compared. @@ -1225,6 +1264,7 @@ public final class Float extends Number * @jls 15.20.1 Numerical Comparison Operators {@code <}, {@code <=}, {@code >}, and {@code >=} * @since 1.2 */ + @Override public int compareTo(Float anotherFloat) { return Float.compare(value, anotherFloat.value); } diff --git a/src/java.base/share/classes/java/lang/Math.java b/src/java.base/share/classes/java/lang/Math.java index fa45b6436c7..61b59784e0e 100644 --- a/src/java.base/share/classes/java/lang/Math.java +++ b/src/java.base/share/classes/java/lang/Math.java @@ -225,7 +225,7 @@ public final class Math { /** * Returns the arc sine of a value; the returned angle is in the - * range -pi/2 through pi/2. Special cases: + * range −pi/2 through pi/2. Special cases: *