archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-28 07:14:30 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

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
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>