JDK 9 RFR of JDK-8164524: Correct inconsistencies in floating-point abs spec
joe darcy
joe.darcy at oracle.com
Sat Aug 20 18:55:12 UTC 2016
Hello,
Please review the doc-only patch below to address
JDK-8164524: Correct inconsistencies in floating-point abs spec
In brief, Martin noted in JDK-8164199 that a close reading of the
specification of the Math and StrictMath floating-point abs methods
reveals some inconsistencies in the text of the specification versus the
operational semantics of the sample code in term of NaN handling.
To resolve this, the sample code is slightly modified and demoted to
informative rather than normative text.
The core of the edit is changing
Float.intBitsToFloat(0x7fffffff & Float.floatToIntBits(a))
to
Float.intBitsToFloat(0x7fffffff & Float.floatToRawIntBits(a))
that is the "raw" floating-point => integral conversion rather than the
"cooked" one which has tighter behavioral requirements around different
NaN values, analogous changes for the double cases.
(I don't think the request to mandate particular NaN behavior in
JDK-8164199 is warranted; see the comments in that bug for a longer
discussion.)
Thanks,
-Joe
Since the float and double abs methods appears both in java.lang.Math
and java.lang.StrictMath, the same edits are made multiple times.
diff -r 9287101b5f49 src/java.base/share/classes/java/lang/Math.java
--- a/src/java.base/share/classes/java/lang/Math.java Tue Aug 09
07:50:26 2016 -0700
+++ b/src/java.base/share/classes/java/lang/Math.java Sat Aug 20
11:47:22 2016 -0700
@@ -1370,8 +1370,12 @@
* result is positive zero.
* <li>If the argument is infinite, the result is positive infinity.
* <li>If the argument is NaN, the result is NaN.</ul>
- * In other words, the result is the same as the value of the
expression:
- * <p>{@code Float.intBitsToFloat(0x7fffffff &
Float.floatToIntBits(a))}
+ *
+ * @apiNote As implied by the above, one valid implementation of
+ * this method is given by the expression below which computes a
+ * {@code float} with the same exponent and significand as the
+ * argument but with a guaranteed positive sign bit: <br>
+ * {@code Float.intBitsToFloat(0x7fffffff &
Float.floatToRawIntBits(a))}
*
* @param a the argument whose absolute value is to be determined
* @return the absolute value of the argument.
@@ -1389,8 +1393,12 @@
* is positive zero.
* <li>If the argument is infinite, the result is positive infinity.
* <li>If the argument is NaN, the result is NaN.</ul>
- * In other words, the result is the same as the value of the
expression:
- * <p>{@code
Double.longBitsToDouble((Double.doubleToLongBits(a)<<1)>>>1)}
+ *
+ * @apiNote As implied by the above, one valid implementation of
+ * this method is given by the expression below which computes a
+ * {@code double} with the same exponent and significand as the
+ * argument but with a guaranteed positive sign bit: <br>
+ * {@code
Double.longBitsToDouble((Double.doubleToRawLongBits(a)<<1)>>>1)}
*
* @param a the argument whose absolute value is to be determined
* @return the absolute value of the argument.
diff -r 9287101b5f49 src/java.base/share/classes/java/lang/StrictMath.java
--- a/src/java.base/share/classes/java/lang/StrictMath.java Tue Aug
09 07:50:26 2016 -0700
+++ b/src/java.base/share/classes/java/lang/StrictMath.java Sat Aug
20 11:47:22 2016 -0700
@@ -1070,8 +1070,12 @@
* result is positive zero.
* <li>If the argument is infinite, the result is positive infinity.
* <li>If the argument is NaN, the result is NaN.</ul>
- * In other words, the result is the same as the value of the
expression:
- * <p>{@code Float.intBitsToFloat(0x7fffffff &
Float.floatToIntBits(a))}
+ *
+ * @apiNote As implied by the above, one valid implementation of
+ * this method is given by the expression below which computes a
+ * {@code float} with the same exponent and significand as the
+ * argument but with a guaranteed positive sign bit: <br>
+ * {@code Float.intBitsToFloat(0x7fffffff &
Float.floatToRawIntBits(a))}
*
* @param a the argument whose absolute value is to be determined
* @return the absolute value of the argument.
@@ -1089,8 +1093,12 @@
* is positive zero.
* <li>If the argument is infinite, the result is positive infinity.
* <li>If the argument is NaN, the result is NaN.</ul>
- * In other words, the result is the same as the value of the
expression:
- * <p>{@code
Double.longBitsToDouble((Double.doubleToLongBits(a)<<1)>>>1)}
+ *
+ * @apiNote As implied by the above, one valid implementation of
+ * this method is given by the expression below which computes a
+ * {@code double} with the same exponent and significand as the
+ * argument but with a guaranteed positive sign bit: <br>
+ * {@code
Double.longBitsToDouble((Double.doubleToRawLongBits(a)<<1)>>>1)}
*
* @param a the argument whose absolute value is to be determined
* @return the absolute value of the argument.
More information about the core-libs-dev
mailing list