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

[Tagir Valeev]

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.

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
> >>