Details
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 builtin remainder operator "{@code %}" is a suitable counterpart
+ * both for this method and for the builtin 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 builtin remainder operator "{@code %}" is a suitable counterpart
+ * both for this method and for the builtin 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 builtin remainder operator "{@code %}" is a suitable counterpart
+ * both for this method and for the builtin 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 builtin remainder operator "{@code %}" is a suitable counterpart
+ * both for this method and for the builtin 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
 csr of

JDK8271225 Add floorDivExact() method to java.lang.[Strict]Math
 Resolved