JDK 9 RFR of JDK-8164524: Correct inconsistencies in floating-point abs spec

Sat, 20 Aug 2016 11:56:54 -0700 

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.

Reply via email to