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

[Joe Darcy]

Hi Tagir,

On 3/30/2020 9:00 PM, Tagir Valeev wrote:
> Hello!
>
> Speaking about implementation, how about this?
>
> return (a < 0) ? negateExact(a) : a;
>
> This would require only one branch for positive numbers and also will
> utilize already intrinsified negateExact. The cost is a less verbose
> message ("integer overflow" or "long overflow"). However, when one
> sees the exception from absExact, its meaning becomes completely clear
> after reading the spec.

Given that the spec may not always be handy, I prefer the more precise 
exception message given in the current, more verbose, implementation.

Thanks for the suggestion,

-Joe

>
> With best regards,
> Tagir Valeev.
>
> On Tue, Mar 31, 2020 at 12:54 AM Joe Darcy <joe.darcy at oracle.com> wrote:
>> 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