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

Add floorDivExact() method to java.lang.[Strict]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:
      Minimal risk as these are new methods in final classes.
    • Interface Kind:
      Java API
    • Scope:
      SE

      Description

      Summary

      Add methods floorDivExact(int,int) and floorDivExact(long,long) to java.lang.Math and java.lang.StrictMath which throw an ArithmeticException when the dividend is MIN_VALUE and the divisor is -1. These methods behave with respect to the methods floorDiv() as the methods divideExact() behave with respect to the division operator /.

      Problem

      The methods divideExact() exist to catch numerical overflow of the division operator / but there are no such analogs for the floorDiv() methods.

      Solution

      Add floorDivExact() methods which behave exactly as the respective floorDiv() methods except when the dividend is MIN_VALUE and the divisor -1 in which case throw an ArithmeticException.

      Specification

      --- a/src/java.base/share/classes/java/lang/Math.java
      +++ b/src/java.base/share/classes/java/lang/Math.java
      @@ -1012,6 +1012,9 @@ public final class Math {
            * <p>
            * If {@code y} is zero, an {@code ArithmeticException} is thrown
            * (JLS {@jls 15.17.2}).
      +     * <p>
      +     * The built-in remainder operator "{@code %}" is a suitable counterpart
      +     * both for this method and for the built-in division operator "{@code /}".
            *
            * @param x the dividend
            * @param y the divisor
      
      @@ -1039,6 +1042,9 @@ public final class Math {
            * <p>
            * If {@code y} is zero, an {@code ArithmeticException} is thrown
            * (JLS {@jls 15.17.2}).
      +     * <p>
      +     * The built-in remainder operator "{@code %}" is a suitable counterpart
      +     * both for this method and for the built-in division operator "{@code /}".
            *
            * @param x the dividend
            * @param y the divisor
      
      @@ -1056,6 +1062,80 @@ public final class Math {
               throw new ArithmeticException("long overflow");
           }
      
      +    /**
      +     * Returns the largest (closest to positive infinity)
      +     * {@code int} value that is less than or equal to the algebraic quotient.
      +     * This method is identical to {@link #floorDiv(int,int)} except that it
      +     * throws an {@code ArithmeticException} when the dividend is
      +     * {@linkplain Integer#MIN_VALUE Integer.MIN_VALUE} and the divisor is
      +     * {@code -1} instead of ignoring the integer overflow and returning
      +     * {@code Integer.MIN_VALUE}.
      +     * <p>
      +     * The floor modulus method {@link #floorMod(int,int)} is a suitable
      +     * counterpart both for this method and for the {@link #floorDiv(int,int)}
      +     * method.
      +     * <p>
      +     * For examples, see {@link #floorDiv(int, int)}.
      +     *
      +     * @param x the dividend
      +     * @param y the divisor
      +     * @return the largest (closest to positive infinity)
      +     * {@code int} value that is less than or equal to the algebraic quotient.
      +     * @throws ArithmeticException if the divisor {@code y} is zero, or the
      +     * dividend {@code x} is {@code Integer.MIN_VALUE} and the divisor {@code y}
      +     * is {@code -1}.
      +     * @see #floorDiv(int, int)
      +     * @since 18
      +     */
      +    public static int floorDivExact(int x, int y) {
      +
      +    /**
      +     * Returns the largest (closest to positive infinity)
      +     * {@code long} value that is less than or equal to the algebraic quotient.
      +     * This method is identical to {@link #floorDiv(long,long)} except that it
      +     * throws an {@code ArithmeticException} when the dividend is
      +     * {@linkplain Long#MIN_VALUE Long.MIN_VALUE} and the divisor is
      +     * {@code -1} instead of ignoring the integer overflow and returning
      +     * {@code Long.MIN_VALUE}.
      +     * <p>
      +     * The floor modulus method {@link #floorMod(long,long)} is a suitable
      +     * counterpart both for this method and for the {@link #floorDiv(long,long)}
      +     * method.
      +     * <p>
      +     * For examples, see {@link #floorDiv(int, int)}.
      +     *
      +     * @param x the dividend
      +     * @param y the divisor
      +     * @return the largest (closest to positive infinity)
      +     * {@code long} value that is less than or equal to the algebraic quotient.
      +     * @throws ArithmeticException if the divisor {@code y} is zero, or the
      +     * dividend {@code x} is {@code Long.MIN_VALUE} and the divisor {@code y}
      +     * is {@code -1}.
      +     * @see #floorDiv(long,long)
      +     * @since 18
      +     */
      +    public static long floorDivExact(long x, long y) {
      
      --- a/src/java.base/share/classes/java/lang/StrictMath.java
      +++ b/src/java.base/share/classes/java/lang/StrictMath.java
      @@ -863,6 +863,9 @@ public final class StrictMath {
            * <p>
            * If {@code y} is zero, an {@code ArithmeticException} is thrown
            * (JLS {@jls 15.17.2}).
      +     * <p>
      +     * The built-in remainder operator "{@code %}" is a suitable counterpart
      +     * both for this method and for the built-in division operator "{@code /}".
            *
            * @param x the dividend
            * @param y the divisor
      
      @@ -887,6 +890,9 @@ public final class StrictMath {
            * <p>
            * If {@code y} is zero, an {@code ArithmeticException} is thrown
            * (JLS {@jls 15.17.2}).
      +     * <p>
      +     * The built-in remainder operator "{@code %}" is a suitable counterpart
      +     * both for this method and for the built-in division operator "{@code /}".
            *
            * @param x the dividend
            * @param y the divisor
      
      @@ -901,6 +907,66 @@ public final class StrictMath {
               return Math.divideExact(x, y);
           }
      
      +    /**
      +     * Returns the largest (closest to positive infinity)
      +     * {@code int} value that is less than or equal to the algebraic quotient.
      +     * This method is identical to {@link #floorDiv(int,int)} except that it
      +     * throws an {@code ArithmeticException} when the dividend is
      +     * {@linkplain Integer#MIN_VALUE Integer.MIN_VALUE} and the divisor is
      +     * {@code -1} instead of ignoring the integer overflow and returning
      +     * {@code Integer.MIN_VALUE}.
      +     * <p>
      +     * The floor modulus method {@link #floorMod(int,int)} is a suitable
      +     * counterpart both for this method and for the {@link #floorDiv(int,int)}
      +     * method.
      +     * <p>
      +     * See {@link Math#floorDiv(int, int) Math.floorDiv} for examples and
      +     * a comparison to the integer division {@code /} operator.
      +     *
      +     * @param x the dividend
      +     * @param y the divisor
      +     * @return the largest (closest to positive infinity)
      +     * {@code int} value that is less than or equal to the algebraic quotient.
      +     * @throws ArithmeticException if the divisor {@code y} is zero, or the
      +     * dividend {@code x} is {@code Integer.MIN_VALUE} and the divisor {@code y}
      +     * is {@code -1}.
      +     * @see Math#floorDiv(int, int)
      +     * @since 18
      +     */
      +    public static int floorDivExact(int x, int y) {
      +
      +    /**
      +     * Returns the largest (closest to positive infinity)
      +     * {@code long} value that is less than or equal to the algebraic quotient.
      +     * This method is identical to {@link #floorDiv(long,long)} except that it
      +     * throws an {@code ArithmeticException} when the dividend is
      +     * {@linkplain Long#MIN_VALUE Long.MIN_VALUE} and the divisor is
      +     * {@code -1} instead of ignoring the integer overflow and returning
      +     * {@code Long.MIN_VALUE}.
      +     * <p>
      +     * The floor modulus method {@link #floorMod(long,long)} is a suitable
      +     * counterpart both for this method and for the {@link #floorDiv(long,long)}
      +     * method.
      +     * <p>
      +     * For examples, see {@link Math#floorDiv(int, int) Math.floorDiv}.
      +     *
      +     * @param x the dividend
      +     * @param y the divisor
      +     * @return the largest (closest to positive infinity)
      +     * {@code long} value that is less than or equal to the algebraic quotient.
      +     * @throws ArithmeticException if the divisor {@code y} is zero, or the
      +     * dividend {@code x} is {@code Long.MIN_VALUE} and the divisor {@code y}
      +     * is {@code -1}.
      +     * @see Math#floorDiv(int, int)
      +     * @see Math#floorDiv(long,long)
      +     * @since 18
      +     */
      +    public static long floorDivExact(long x, long y) {

        Attachments

          Issue Links

            Activity

              People

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

                Dates

                Created:
                Updated:
                Resolved: