JDK-8270378 : divideExact is missing in java.lang.Math
  • Type: CSR
  • Component: core-libs
  • Sub-Component: java.lang
  • Priority: P4
  • Status: Closed
  • Resolution: Approved
  • Fix Versions: 18
  • Submitted: 2021-07-13
  • Updated: 2021-07-23
  • Resolved: 2021-07-23
Related Reports
CSR :  
Description
Summary
-------

Add methods `divideExact(int,int)` and `divideExact(long,long)` to `java.lang.Math` and `java.lang.StrictMath`.

Problem
-------

All of the four common arithmetic operations which apply to integral data types have an `opExact()` analog in `Math` and `StrictMath` except for division. In particular, `multiplyExact()` methods are already present.

Solution
--------

Add to `Math` and `StrictMath` the operations `divideExact(int,int)` and `divideExact(long,long)` which throw an `ArithmeticException` when their respective parameters are `{Integer.MIN_VALUE,-1}` and `{Long.MIN_VALUE,-1}`.

Specification
-------------

    --- a/src/java.base/share/classes/java/lang/Math.java
    +++ b/src/java.base/share/classes/java/lang/Math.java
    @@ -91,13 +91,8 @@ import jdk.internal.vm.annotation.IntrinsicCandidate;
      * will not overflow the range of values of the computation.
      * The best practice is to choose the primitive type and algorithm to avoid
      * overflow. In cases where the size is {@code int} or {@code long} and
    - * overflow errors need to be detected, the methods {@code addExact},
    - * {@code subtractExact}, {@code multiplyExact}, {@code toIntExact},
    - * {@code incrementExact}, {@code decrementExact} and {@code negateExact}
    - * throw an {@code ArithmeticException} when the results overflow.
    - * For the arithmetic operations divide and absolute value, overflow
    - * occurs only with a specific minimum or maximum value and
    - * should be checked against the minimum or maximum as appropriate.
    + * overflow errors need to be detected, the methods whose names end with
    + * {@code Exact} throw an {@code ArithmeticException} when the results overflow.
      *
      * <h2><a id=Ieee754RecommendedOps>IEEE 754 Recommended
      * Operations</a></h2>
    @@ -1007,6 +1002,60 @@ public final class Math {
             return r;
         }
     
    +    /**
    +     * Returns the quotient of the arguments, throwing an exception if the
    +     * result overflows an {@code int}.  Such overflow occurs in this method if
    +     * {@code x} is {@link Integer#MIN_VALUE} and {@code y} is {@code -1}.
    +     * In contrast, if {@code Integer.MIN_VALUE / -1} were evaluated directly,
    +     * the result would be {@code Integer.MIN_VALUE} and no exception would be
    +     * thrown.
    +     * <p>
    +     * If {@code y} is zero, an {@code ArithmeticException} is thrown
    +     * (JLS {@jls 15.17.2}).
    +     *
    +     * @param x the dividend
    +     * @param y the divisor
    +     * @return the quotient {@code x / y}
    +     * @throws ArithmeticException if {@code y} is zero or the quotient
    +     * overflows an int
    +     * @jls 15.17.2 Division Operator /
    +     * @since 18
    +     */
    +    public static int divideExact(int x, int y) {}
    +
    +    /**
    +     * Returns the quotient of the arguments, throwing an exception if the
    +     * result overflows a {@code long}.  Such overflow occurs in this method if
    +     * {@code x} is {@link Long#MIN_VALUE} and {@code y} is {@code -1}.
    +     * In contrast, if {@code Long.MIN_VALUE / -1} were evaluated directly,
    +     * the result would be {@code Long.MIN_VALUE} and no exception would be
    +     * thrown.
    +     * <p>
    +     * If {@code y} is zero, an {@code ArithmeticException} is thrown
    +     * (JLS {@jls 15.17.2}).
    +     *
    +     * @param x the dividend
    +     * @param y the divisor
    +     * @return the quotient {@code x / y}
    +     * @throws ArithmeticException if {@code y} is zero or the quotient
    +     * overflows a long
    +     * @jls 15.17.2 Division Operator /
    +     * @since 18
    +     */
    +    public static long divideExact(long x, long y) {}
    +
         /**
          * Returns the argument incremented by one, throwing an exception if the
          * result overflows an {@code int}.
    --- a/src/java.base/share/classes/java/lang/StrictMath.java
    +++ b/src/java.base/share/classes/java/lang/StrictMath.java
    @@ -66,13 +66,8 @@ import jdk.internal.vm.annotation.IntrinsicCandidate;
      * will not overflow the range of values of the computation.
      * The best practice is to choose the primitive type and algorithm to avoid
      * overflow. In cases where the size is {@code int} or {@code long} and
    - * overflow errors need to be detected, the methods {@code addExact},
    - * {@code subtractExact}, {@code multiplyExact}, {@code toIntExact},
    - * {@code incrementExact}, {@code decrementExact} and {@code negateExact}
    - * throw an {@code ArithmeticException} when the results overflow.
    - * For the arithmetic operations divide and absolute value, overflow
    - * occurs only with a specific minimum or maximum value and
    - * should be checked against the minimum or maximum as appropriate.
    + * overflow errors need to be detected, the methods whose names end with
    + * {@code Exact} throw an {@code ArithmeticException} when the results overflow.
      *
      * <h2><a id=Ieee754RecommendedOps>IEEE 754 Recommended
      * Operations</a></h2>
    @@ -858,6 +853,54 @@ public final class StrictMath {
             return Math.multiplyExact(x, y);
         }
     
    +    /**
    +     * Returns the quotient of the arguments, throwing an exception if the
    +     * result overflows an {@code int}.  Such overflow occurs in this method if
    +     * {@code x} is {@link Integer#MIN_VALUE} and {@code y} is {@code -1}.
    +     * In contrast, if {@code Integer.MIN_VALUE / -1} were evaluated directly,
    +     * the result would be {@code Integer.MIN_VALUE} and no exception would be
    +     * thrown.
    +     * <p>
    +     * If {@code y} is zero, an {@code ArithmeticException} is thrown
    +     * (JLS {@jls 15.17.2}).
    +     *
    +     * @param x the dividend
    +     * @param y the divisor
    +     * @return the quotient {@code x / y}
    +     * @throws ArithmeticException if {@code y} is zero or the quotient
    +     * overflows an int
    +     * @jls 15.17.2 Division Operator /
    +     * @see Math#divideExact(int,int)
    +     * @since 18
    +     */
    +    public static int divideExact(int x, int y) {}
    +
    +    /**
    +     * Returns the quotient of the arguments, throwing an exception if the
    +     * result overflows a {@code long}.  Such overflow occurs in this method if
    +     * {@code x} is {@link Long#MIN_VALUE} and {@code y} is {@code -1}.
    +     * In contrast, if {@code Long.MIN_VALUE / -1} were evaluated directly,
    +     * the result would be {@code Long.MIN_VALUE} and no exception would be
    +     * thrown.
    +     * <p>
    +     * If {@code y} is zero, an {@code ArithmeticException} is thrown
    +     * (JLS {@jls 15.17.2}).
    +     *
    +     * @param x the dividend
    +     * @param y the divisor
    +     * @return the quotient {@code x / y}
    +     * @throws ArithmeticException if {@code y} is zero or the quotient
    +     * overflows a long
    +     * @jls 15.17.2 Division Operator /
    +     * @see Math#divideExact(long,long)
    +     * @since 18
    +     */
    +    public static long divideExact(long x, long y) {}
    +
         /**
          * Returns the argument incremented by one,
          * throwing an exception if the result overflows an {@code int}.


Comments
Moving to Approved.
23-07-2021