JDK 15 RF(pre)R of JDK-8241374: add Math.absExact

[Joe Darcy]

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.hegarty at oracle.com 
>>> <mailto:chris.hegarty at 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
>>