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