8164524: Correct inconsistencies in floating-point abs spec
Reviewed-by: martin, bpb
--- a/jdk/src/java.base/share/classes/java/lang/Math.java Mon Aug 22 15:27:50 2016 -0700
+++ b/jdk/src/java.base/share/classes/java/lang/Math.java Mon Aug 22 17:22:09 2016 -0700
@@ -1370,8 +1370,13 @@
* 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 zero sign bit indicating a
+ * positive value:<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 +1394,13 @@
* 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 zero sign bit indicating a
+ * positive value:<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.
--- a/jdk/src/java.base/share/classes/java/lang/StrictMath.java Mon Aug 22 15:27:50 2016 -0700
+++ b/jdk/src/java.base/share/classes/java/lang/StrictMath.java Mon Aug 22 17:22:09 2016 -0700
@@ -1070,8 +1070,13 @@
* 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 zero sign bit indicating a
+ * positive value: <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 +1094,13 @@
* 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 zero sign bit indicating a
+ * positive value: <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.