Hello,
Updated webrev at:
http://cr.openjdk.java.net/~darcy/8241374.1/
One of the four pieces of the update to discuss below. A few comments, I
added links from the abs methods to its sibling absExact method along
with an additional note on referring the differing absExact behavior on
a MIN_VALUE argument. I'll reflow the paragraphs and update the
copyright year before pushing. Link to the relevant JLS section included
in the absExact javadoc.
--- old/src/java.base/share/classes/java/lang/Math.java 2020-03-30
10:28:41.314472163 -0700
+++ new/src/java.base/share/classes/java/lang/Math.java 2020-03-30
10:28:40.930472163 -0700
@@ -1359,9 +1359,12 @@
* {@link Integer#MIN_VALUE}, the most negative representable
* {@code int} value, the result is that same value, which is
* negative.
+ * In contrast, the {@link Math#absExact(int)} method throws an
+ * {@code ArithmeticException} for this value.
*
* @param a the argument whose absolute value is to be determined
* @return the absolute value of the argument.
+ * @see Math#absExact(int)
*/
@HotSpotIntrinsicCandidate
public static int abs(int a) {
@@ -1369,6 +1372,32 @@
}
/**
+ * Returns the mathematical absolute value of an {@code int} value
+ * if it is exactly representable as an {@code int}, throwing
+ * {@code ArithmeticException} if the result overflows the
+ * positive {@code int} range.
+ *
+ * <p>Since the range of two's complement integers is asymmetric
+ * with one additional negative value (JLS {@jls 4.2.1}), the
+ * mathematical absolute value of {@link Integer#MIN_VALUE}
+ * overflows the positive {@code int} range, so an exception is
+ * thrown for that argument.
+ *
+ * @param a the argument whose absolute value is to be determined
+ * @return the absolute value of the argument, unless overflow occurs
+ * @throws ArithmeticException if the argument is {@link
Integer#MIN_VALUE}
+ * @see Math#abs(int)
+ * @since 15
+ */
+ public static int absExact(int a) {
+ if (a == Integer.MIN_VALUE)
+ throw new ArithmeticException(
+ "Overflow to represent absolute value of
Integer.MIN_VALUE");
+ else
+ return abs(a);
+ }
For the StrictMath methods, I include links to the Math equivalent, as
the other fooExact StrictMath methods do.
Thanks,
-Joe
On 3/30/2020 9:31 AM, Joe Darcy wrote:
Hi Brian and Chris,
I was considering adding such as JLS link myself; I'll work one in and
post a revised webrev.
Thanks,
-Joe
On 3/30/2020 9:29 AM, Brian Burkhalter wrote:
Hi Joe,
On Mar 30, 2020, at 6:31 AM, Chris Hegarty <chris.hega...@oracle.com
<mailto:chris.hega...@oracle.com>> wrote:
Full webrev for review include including tests:
http://cr.openjdk.java.net/~darcy/8241374.0/
and the companion CSR:
https://bugs.openjdk.java.net/browse/JDK-8241805
Looks good to me.
Likewise.
I do like the explanatory paragraph about the asymmetry in the range
of two's complement integer values. An alternative, or addition,
would be a link to JLS 4.2.1 - Integral Types and Values [1], which
shows the asymmetry from a language perspective.
I also like this suggestion.
Brian
-Chris.
[1]https://docs.oracle.com/javase/specs/jls/se14/html/jls-4.html#jls-4.2.1
