stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8273346: Expand library mappings to IEEE 754 operations

Browse Source 
Reviewed-by: bpb
This commit is contained in:
Joe Darcy 2022-06-07 16:13:42 +00:00
parent 96641c0c42
commit 5d4ea9b954
4 changed files with 156 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
src/java.base/share/classes/java/lang/Double.java
View File

@ -739,6 +739,10 @@ public final class Double extends Number
* 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 final class Double extends Number
* 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 final class Double extends Number
* 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 final class Double extends Number
* 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 final class Double extends Number
/**
* 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 final class Double extends Number
* 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 final class Double extends Number
* 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}.

27
src/java.base/share/classes/java/lang/Float.java
View File

@ -559,6 +559,10 @@ public final class Float extends Number
* 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 final class Float extends Number
* 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 final class Float extends Number
* 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 final class Float extends Number
* 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 final class Float extends Number
/**
* 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 final class Float extends Number
* 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 final class Float extends Number
* 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}

73
src/java.base/share/classes/java/lang/Math.java
View File

@ -398,6 +398,10 @@ public final class Math {
* 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 final class Math {
* 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 final class Math {
* 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 final class Math {
* <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 final class Math {
* 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 final class Math {
* 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 final class Math {
* 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 final class Math {
* 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 final class Math {
* 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 final class Math {
* 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 final class Math {
* 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 final class Math {
* 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 final class Math {
* <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 final class Math {
* <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 final class Math {
*
* </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 final class Math {
*
* </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 final class Math {
*
* </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 final class Math {
*
* </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 final class Math {
* 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 final class Math {
* 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>

42
src/java.base/share/classes/java/math/RoundingMode.java
View File

@ -39,6 +39,21 @@ package java.math;
* 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,7 +105,7 @@ package java.math;
* @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.
*
@ -98,6 +113,7 @@ package java.math;
* @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: