Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8270378

divideExact is missing in java.lang.Math

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P4
    • Resolution: Approved
    • Fix Version/s: 18
    • Component/s: core-libs
    • Labels:
      None
    • Subcomponent:
    • Compatibility Kind:
      behavioral
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      Adding methods to a final class should incur no risk.
    • Interface Kind:
      Java API
    • Scope:
      SE

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

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              bpb Brian Burkhalter
              Reporter:
              webbuggrp Webbug Group
              Reviewed By:
              Stuart Marks
              Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: