8273346: Expand library mappings to IEEE 754 operations

Reviewed-by: bpb

Author: jddarcy

src/java.base/share/classes/java/lang/Double.java

@@ -739,6 +739,10 @@ public static double parseDouble(String s) throws NumberFormatException {
      * Returns {@code true} if the specified number is a
      * Not-a-Number (NaN) value, {@code false} otherwise.
      *
+     * @apiNote
+     * This method corresponds to the isNaN operation defined in IEEE
+     * 754.
+     *
      * @param   v   the value to be tested.
      * @return  {@code true} if the value of the argument is NaN;
      *          {@code false} otherwise.
@@ -751,6 +755,10 @@ public static boolean isNaN(double v) {
      * Returns {@code true} if the specified number is infinitely
      * large in magnitude, {@code false} otherwise.
      *
+     * @apiNote
+     * This method corresponds to the isInfinite operation defined in
+     * IEEE 754.
+     *
      * @param   v   the value to be tested.
      * @return  {@code true} if the value of the argument is positive
      *          infinity or negative infinity; {@code false} otherwise.
@@ -765,6 +773,10 @@ public static boolean isInfinite(double v) {
      * value; returns {@code false} otherwise (for NaN and infinity
      * arguments).
      *
+     * @apiNote
+     * This method corresponds to the isFinite operation defined in
+     * IEEE 754.
+     *
      * @param d the {@code double} value to be tested
      * @return {@code true} if the argument is a finite
      * floating-point value, {@code false} otherwise.
@@ -908,6 +920,10 @@ public long longValue() {
      * Returns the value of this {@code Double} as a {@code float}
      * after a narrowing primitive conversion.
      *
+     * @apiNote
+     * This method corresponds to the convertFormat operation defined
+     * in IEEE 754.
+     *
      * @return  the {@code double} value represented by this object
      *          converted to type {@code float}
      * @jls 5.1.3 Narrowing Primitive Conversion
@@ -1217,6 +1233,9 @@ public static int compare(double d1, double d2) {
     /**
      * Adds two {@code double} values together as per the + operator.
      *
+     * @apiNote This method corresponds to the addition operation
+     * defined in IEEE 754.
+     *
      * @param a the first operand
      * @param b the second operand
      * @return the sum of {@code a} and {@code b}
@@ -1232,6 +1251,10 @@ public static double sum(double a, double b) {
      * Returns the greater of two {@code double} values
      * as if by calling {@link Math#max(double, double) Math.max}.
      *
+     * @apiNote
+     * This method corresponds to the maximum operation defined in
+     * IEEE 754.
+     *
      * @param a the first operand
      * @param b the second operand
      * @return the greater of {@code a} and {@code b}
@@ -1246,6 +1269,10 @@ public static double max(double a, double b) {
      * Returns the smaller of two {@code double} values
      * as if by calling {@link Math#min(double, double) Math.min}.
      *
+     * @apiNote
+     * This method corresponds to the minimum operation defined in
+     * IEEE 754.
+     *
      * @param a the first operand
      * @param b the second operand
      * @return the smaller of {@code a} and {@code b}.

src/java.base/share/classes/java/lang/Float.java

@@ -559,6 +559,10 @@ public static float parseFloat(String s) throws NumberFormatException {
      * Returns {@code true} if the specified number is a
      * Not-a-Number (NaN) value, {@code false} otherwise.
      *
+     * @apiNote
+     * This method corresponds to the isNaN operation defined in IEEE
+     * 754.
+     *
      * @param   v   the value to be tested.
      * @return  {@code true} if the argument is NaN;
      *          {@code false} otherwise.
@@ -571,6 +575,10 @@ public static boolean isNaN(float v) {
      * Returns {@code true} if the specified number is infinitely
      * large in magnitude, {@code false} otherwise.
      *
+     * @apiNote
+     * This method corresponds to the isInfinite operation defined in
+     * IEEE 754.
+     *
      * @param   v   the value to be tested.
      * @return  {@code true} if the argument is positive infinity or
      *          negative infinity; {@code false} otherwise.
@@ -586,6 +594,10 @@ public static boolean isInfinite(float v) {
      * value; returns {@code false} otherwise (for NaN and infinity
      * arguments).
      *
+     * @apiNote
+     * This method corresponds to the isFinite operation defined in
+     * IEEE 754.
+     *
      * @param f the {@code float} value to be tested
      * @return {@code true} if the argument is a finite
      * floating-point value, {@code false} otherwise.
@@ -754,6 +766,10 @@ public float floatValue() {
      * Returns the value of this {@code Float} as a {@code double}
      * after a widening primitive conversion.
      *
+     * @apiNote
+     * This method corresponds to the convertFormat operation defined
+     * in IEEE 754.
+     *
      * @return the {@code float} value represented by this
      *         object converted to type {@code double}
      * @jls 5.1.2 Widening Primitive Conversion
@@ -1039,6 +1055,9 @@ public static int compare(float f1, float f2) {
     /**
      * Adds two {@code float} values together as per the + operator.
      *
+     * @apiNote This method corresponds to the addition operation
+     * defined in IEEE 754.
+     *
      * @param a the first operand
      * @param b the second operand
      * @return the sum of {@code a} and {@code b}
@@ -1054,6 +1073,10 @@ public static float sum(float a, float b) {
      * Returns the greater of two {@code float} values
      * as if by calling {@link Math#max(float, float) Math.max}.
      *
+     * @apiNote
+     * This method corresponds to the maximum operation defined in
+     * IEEE 754.
+     *
      * @param a the first operand
      * @param b the second operand
      * @return the greater of {@code a} and {@code b}
@@ -1068,6 +1091,10 @@ public static float max(float a, float b) {
      * Returns the smaller of two {@code float} values
      * as if by calling {@link Math#min(float, float) Math.min}.
      *
+     * @apiNote
+     * This method corresponds to the minimum operation defined in
+     * IEEE 754.
+     *
      * @param a the first operand
      * @param b the second operand
      * @return the smaller of {@code a} and {@code b}

src/java.base/share/classes/java/lang/Math.java

@@ -398,6 +398,10 @@ public static double log10(double a) {
      * Otherwise, the result is the {@code double} value closest to
      * the true mathematical square root of the argument value.
      *
+     * @apiNote
+     * This method corresponds to the squareRoot operation defined in
+     * IEEE 754.
+     *
      * @param   a   a value.
      * @return  the positive square root of {@code a}.
      *          If the argument is NaN or less than zero, the result is NaN.
@@ -481,6 +485,9 @@ public static double IEEEremainder(double f1, double f2) {
      * that the value of {@code Math.ceil(x)} is exactly the
      * value of {@code -Math.floor(-x)}.
      *
+     * @apiNote
+     * This method corresponds to the roundToIntegralTowardPositive
+     * operation defined in IEEE 754.
      *
      * @param   a   a value.
      * @return  the smallest (closest to negative infinity)
@@ -502,6 +509,10 @@ public static double ceil(double a) {
      * positive zero or negative zero, then the result is the same as
      * the argument.</ul>
      *
+     * @apiNote
+     * This method corresponds to the roundToIntegralTowardNegative
+     * operation defined in IEEE 754.
+     *
      * @param   a   a value.
      * @return  the largest (closest to positive infinity)
      *          floating-point value that less than or equal to the argument
@@ -523,6 +534,10 @@ public static double floor(double a) {
      * <li>If the argument is NaN or an infinity or positive zero or negative
      * zero, then the result is the same as the argument.</ul>
      *
+     * @apiNote
+     * This method corresponds to the roundToIntegralTiesToEven
+     * operation defined in IEEE 754.
+     *
      * @param   a   a {@code double} value.
      * @return  the closest floating-point value to {@code a} that is
      *          equal to a mathematical integer.
@@ -2033,6 +2048,10 @@ public static long max(long a, long b) {
      * argument is positive zero and the other negative zero, the
      * result is positive zero.
      *
+     * @apiNote
+     * This method corresponds to the maximum operation defined in
+     * IEEE 754.
+     *
      * @param   a   an argument.
      * @param   b   another argument.
      * @return  the larger of {@code a} and {@code b}.
@@ -2060,6 +2079,10 @@ public static float max(float a, float b) {
      * argument is positive zero and the other negative zero, the
      * result is positive zero.
      *
+     * @apiNote
+     * This method corresponds to the maximum operation defined in
+     * IEEE 754.
+     *
      * @param   a   an argument.
      * @param   b   another argument.
      * @return  the larger of {@code a} and {@code b}.
@@ -2116,6 +2139,10 @@ public static long min(long a, long b) {
      * one argument is positive zero and the other is negative zero,
      * the result is negative zero.
      *
+     * @apiNote
+     * This method corresponds to the minimum operation defined in
+     * IEEE 754.
+     *
      * @param   a   an argument.
      * @param   b   another argument.
      * @return  the smaller of {@code a} and {@code b}.
@@ -2143,6 +2170,10 @@ public static float min(float a, float b) {
      * argument is positive zero and the other is negative zero, the
      * result is negative zero.
      *
+     * @apiNote
+     * This method corresponds to the minimum operation defined in
+     * IEEE 754.
+     *
      * @param   a   an argument.
      * @param   b   another argument.
      * @return  the smaller of {@code a} and {@code b}.
@@ -2198,7 +2229,7 @@ public static double min(double a, double b) {
      * equivalent to ({@code a * b}) however.
      *
      * @apiNote This method corresponds to the fusedMultiplyAdd
-     * operation defined in IEEE 754-2008.
+     * operation defined in IEEE 754.
      *
      * @param a a value
      * @param b a value
@@ -2312,7 +2343,7 @@ public static double fma(double a, double b, double c) {
      * equivalent to ({@code a * b}) however.
      *
      * @apiNote This method corresponds to the fusedMultiplyAdd
-     * operation defined in IEEE 754-2008.
+     * operation defined in IEEE 754.
      *
      * @param a a value
      * @param b a value
@@ -2692,6 +2723,10 @@ public static double log1p(double x) {
      * permitted to treat some NaN arguments as positive and other NaN
      * arguments as negative to allow greater performance.
      *
+     * @apiNote
+     * This method corresponds to the copySign operation defined in
+     * IEEE 754.
+     *
      * @param magnitude  the parameter providing the magnitude of the result
      * @param sign   the parameter providing the sign of the result
      * @return a value with the magnitude of {@code magnitude}
@@ -2716,6 +2751,10 @@ public static double copySign(double magnitude, double sign) {
      * permitted to treat some NaN arguments as positive and other NaN
      * arguments as negative to allow greater performance.
      *
+     * @apiNote
+     * This method corresponds to the copySign operation defined in
+     * IEEE 754.
+     *
      * @param magnitude  the parameter providing the magnitude of the result
      * @param sign   the parameter providing the sign of the result
      * @return a value with the magnitude of {@code magnitude}
@@ -2739,8 +2778,12 @@ public static float copySign(float magnitude, float sign) {
      * <li>If the argument is NaN or infinite, then the result is
      * {@link Float#MAX_EXPONENT} + 1.
      * <li>If the argument is zero or subnormal, then the result is
-     * {@link Float#MIN_EXPONENT} -1.
+     * {@link Float#MIN_EXPONENT} - 1.
      * </ul>
+     * @apiNote
+     * This method is analogous to the logB operation defined in IEEE
+     * 754, but returns a different value on subnormal arguments.
+     *
      * @param f a {@code float} value
      * @return the unbiased exponent of the argument
      * @since 1.6
@@ -2763,8 +2806,12 @@ public static int getExponent(float f) {
      * <li>If the argument is NaN or infinite, then the result is
      * {@link Double#MAX_EXPONENT} + 1.
      * <li>If the argument is zero or subnormal, then the result is
-     * {@link Double#MIN_EXPONENT} -1.
+     * {@link Double#MIN_EXPONENT} - 1.
      * </ul>
+     * @apiNote
+     * This method is analogous to the logB operation defined in IEEE
+     * 754, but returns a different value on subnormal arguments.
+     *
      * @param d a {@code double} value
      * @return the unbiased exponent of the argument
      * @since 1.6
@@ -2968,6 +3015,9 @@ public static float nextAfter(float start, double direction) {
      *
      * </ul>
      *
+     * @apiNote This method corresponds to the nextUp
+     * operation defined in IEEE 754.
+     *
      * @param d starting floating-point value
      * @return The adjacent floating-point value closer to positive
      * infinity.
@@ -3004,6 +3054,9 @@ public static double nextUp(double d) {
      *
      * </ul>
      *
+     * @apiNote This method corresponds to the nextUp
+     * operation defined in IEEE 754.
+     *
      * @param f starting floating-point value
      * @return The adjacent floating-point value closer to positive
      * infinity.
@@ -3040,6 +3093,9 @@ public static float nextUp(float f) {
      *
      * </ul>
      *
+     * @apiNote This method corresponds to the nextDown
+     * operation defined in IEEE 754.
+     *
      * @param d  starting floating-point value
      * @return The adjacent floating-point value closer to negative
      * infinity.
@@ -3077,6 +3133,9 @@ public static double nextDown(double d) {
      *
      * </ul>
      *
+     * @apiNote This method corresponds to the nextDown
+     * operation defined in IEEE 754.
+     *
      * @param f  starting floating-point value
      * @return The adjacent floating-point value closer to negative
      * infinity.
@@ -3116,6 +3175,9 @@ public static float nextDown(float f) {
      * sign is returned.
      * </ul>
      *
+     * @apiNote This method corresponds to the scaleB operation
+     * defined in IEEE 754.
+     *
      * @param d number to be scaled by a power of two.
      * @param scaleFactor power of 2 used to scale {@code d}
      * @return {@code d} &times; 2<sup>{@code scaleFactor}</sup>
@@ -3200,6 +3262,9 @@ public static double scalb(double d, int scaleFactor) {
      * sign is returned.
      * </ul>
      *
+     * @apiNote This method corresponds to the scaleB operation
+     * defined in IEEE 754.
+     *
      * @param f number to be scaled by a power of two.
      * @param scaleFactor power of 2 used to scale {@code f}
      * @return {@code f} &times; 2<sup>{@code scaleFactor}</sup>

src/java.base/share/classes/java/math/RoundingMode.java

@@ -39,6 +39,21 @@
  * considered as a numerical value, the discarded fraction could have
  * an absolute value greater than one.
  *
+ * <p>More generally, a rounding policy defines a mapping from the
+ * real numbers to a subset of representable values. In the case of
+ * {@link BigDecimal}, the representable values are a function of the
+ * {@linkplain MathContext#getPrecision() precision} being used in the
+ * computation. Assuming the mathematical result is within the
+ * exponent range of {@code BigDecimal}, the mathematical result will
+ * be exactly representable in the result precision or will fall
+ * between two adjacent representable values. In the case of falling
+ * between two representable values, the rounding policy determines
+ * which of those two bracketing values is the result. For in-range
+ * real numbers, for a given set of representable values, a rounding
+ * policy maps a continuous segment of the real number line to a
+ * single representable value where the real number numerically equal
+ * to a representable value is mapped to that value.
+ *
  * <p>Each rounding mode description includes a table listing how
  * different two-digit decimal values would round to a one digit
  * decimal value under the rounding mode in question.  The result
@@ -90,14 +105,15 @@
  * @apiNote
  * Five of the rounding modes declared in this class correspond to
  * rounding-direction attributes defined in the <cite>IEEE Standard
- * for Floating-Point Arithmetic</cite>, IEEE 754-2019. Where present,
+ * for Floating-Point Arithmetic</cite>. Where present,
  * this correspondence will be noted in the documentation of the
  * particular constant.
  *
  * @see     BigDecimal
  * @see     MathContext
  * @see <a href="https://standards.ieee.org/ieee/754/6210/">
  *      <cite>IEEE Standard for Floating-Point Arithmetic</cite></a>
+ * @jls 15.4 Floating-point Expressions
  *
  * @author  Josh Bloch
  * @author  Mike Cowlishaw
@@ -140,7 +156,13 @@ public enum RoundingMode {
          * Rounding mode to round towards zero.  Never increments the digit
          * prior to a discarded fraction (i.e., truncates).  Note that this
          * rounding mode never increases the magnitude of the calculated value.
-         * This mode corresponds to the IEEE 754-2019 rounding-direction
+         *
+         * @apiNote
+         * This rounding mode is analogous to the rounding policy used
+         * for the {@code float} and {@code double} operators
+         * remainder and conversion to an integer value (JLS {@jls
+         * 15.4}).
+         * This mode corresponds to the IEEE 754 rounding-direction
          * attribute roundTowardZero.
          *
          *<p>Example:
@@ -171,7 +193,7 @@ public enum RoundingMode {
          * result is positive, behaves as for {@code RoundingMode.UP};
          * if negative, behaves as for {@code RoundingMode.DOWN}.  Note
          * that this rounding mode never decreases the calculated value.
-         * This mode corresponds to the IEEE 754-2019 rounding-direction
+         * This mode corresponds to the IEEE 754 rounding-direction
          * attribute roundTowardPositive.
          *
          *<p>Example:
@@ -202,7 +224,7 @@ public enum RoundingMode {
          * result is positive, behave as for {@code RoundingMode.DOWN};
          * if negative, behave as for {@code RoundingMode.UP}.  Note that
          * this rounding mode never increases the calculated value.
-         * This mode corresponds to the IEEE 754-2019 rounding-direction
+         * This mode corresponds to the IEEE 754 rounding-direction
          * attribute roundTowardNegative.
          *
          *<p>Example:
@@ -235,7 +257,7 @@ public enum RoundingMode {
          * fraction is &ge; 0.5; otherwise, behaves as for
          * {@code RoundingMode.DOWN}.  Note that this is the rounding
          * mode commonly taught at school.
-         * This mode corresponds to the IEEE 754-2019 rounding-direction
+         * This mode corresponds to the IEEE 754 rounding-direction
          * attribute roundTiesToAway.
          *
          *<p>Example:
@@ -297,14 +319,16 @@ public enum RoundingMode {
          * towards the even neighbor.  Behaves as for
          * {@code RoundingMode.HALF_UP} if the digit to the left of the
          * discarded fraction is odd; behaves as for
-         * {@code RoundingMode.HALF_DOWN} if it's even.  Note that this
+         * {@code RoundingMode.HALF_DOWN} if it's even.
+         * @apiNote
+         * This
          * is the rounding mode that statistically minimizes cumulative
          * error when applied repeatedly over a sequence of calculations.
          * It is sometimes known as {@literal "Banker's rounding,"} and is
          * chiefly used in the USA.  This rounding mode is analogous to
-         * the rounding policy used for {@code float} and {@code double}
-         * arithmetic in Java.
-         * This mode corresponds to the IEEE 754-2019 rounding-direction
+         * the rounding policy used for most {@code float} and {@code double}
+         * arithmetic operators in Java (JLS {@jls 15.4}).
+         * This mode corresponds to the IEEE 754 rounding-direction
          * attribute roundTiesToEven.
          *
          *<p>Example: