* Normal integer division operates under the round to zero rounding mode * (truncation). This operation instead acts under the round toward * negative infinity (floor) rounding mode. - * The floor rounding mode gives different results than truncation + * The floor rounding mode gives different results from truncation * when the exact result is negative. *

*
• If the signs of the arguments are the same, the results of @@ -1107,12 +1121,41 @@ * There is one special case, if the dividend is the * {@linkplain Long#MIN_VALUE Long.MIN_VALUE} and the divisor is {@code -1}, * then integer overflow occurs and - * the result is equal to the {@code Long.MIN_VALUE}. + * the result is equal to {@code Long.MIN_VALUE}. *

* Normal integer division operates under the round to zero rounding mode * (truncation). This operation instead acts under the round toward * negative infinity (floor) rounding mode. - * The floor rounding mode gives different results than truncation + * The floor rounding mode gives different results from truncation + * when the exact result is negative. + *

+ * 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 + * @see #floorMod(long, int) + * @see #floor(double) + * @since 1.9 + */ + public static long floorDiv(long x, int y) { + return floorDiv(x, (long)y); + } + + /** + * Returns the largest (closest to positive infinity) + * {@code long} value that is less than or equal to the algebraic quotient. + * There is one special case, if the dividend is the + * {@linkplain Long#MIN_VALUE Long.MIN_VALUE} and the divisor is {@code -1}, + * then integer overflow occurs and + * the result is equal to {@code Long.MIN_VALUE}. + *

+ * Normal integer division operates under the round to zero rounding mode + * (truncation). This operation instead acts under the round toward + * negative infinity (floor) rounding mode. + * The floor rounding mode gives different results from truncation * when the exact result is negative. *

* For examples, see {@link #floorDiv(int, int)}. @@ -1180,8 +1223,39 @@ * @since 1.8 */ public static int floorMod(int x, int y) { - int r = x - floorDiv(x, y) * y; - return r; + return x - floorDiv(x, y) * y; + } + + /** + * Returns the floor modulus of the {@code long} and {@int} arguments. + *

+ * The floor modulus is {@code x - (floorDiv(x, y) * y)}, + * has the same sign as the divisor {@code y}, and + * is in the range of {@code -abs(y) < r < +abs(y)}. + * + *

+ * The relationship between {@code floorDiv} and {@code floorMod} is such that: + *

+ *
• {@code floorDiv(x, y) * y + floorMod(x, y) == x} + *
+ *

+ * For examples, see {@link #floorMod(int, int)}. + * + * @param x the dividend + * @param y the divisor + * @return the floor modulus {@code x - (floorDiv(x, y) * y)} + * @throws ArithmeticException if the divisor {@code y} is zero or the + * result would overflow an {@code int} + * @see #floorDiv(long, int) + * @since 1.9 + */ + public static int floorMod(long x, int y) { + long r = x - floorDiv(x, y) * y; + int result = (int)r; + if (result != r) { + throw new ArithmeticException("integer overlow"); + } + return result; } /** diff --git a/src/java.base/share/classes/java/lang/StrictMath.java b/src/java.base/share/classes/java/lang/StrictMath.java --- a/src/java.base/share/classes/java/lang/StrictMath.java +++ b/src/java.base/share/classes/java/lang/StrictMath.java @@ -70,7 +70,7 @@ * {@code subtractExact}, {@code multiplyExact}, and {@code toIntExact} * throw an {@code ArithmeticException} when the results overflow. * For other arithmetic operations such as divide, absolute value, - * increment, decrement, and negation overflow occurs only with + * increment by one, decrement by one, and negation overflow occurs only with * a specific minimum or maximum value and should be checked against * the minimum or maximum as appropriate. * @@ -801,6 +801,21 @@ } /** + * Returns the product of the arguments, throwing an exception if the result + * overflows a {@code long}. + * + * @param x the first value + * @param y the second value + * @return the result + * @throws ArithmeticException if the result overflows a long + * @see Math#multiplyExact(long,int) + * @since 1.9 + */ + public static long multiplyExact(long x, int y) { + return Math.multiplyExact(x, y); + } + + /** * Returns the product of the arguments, * throwing an exception if the result overflows a {@code long}. * @@ -859,6 +874,30 @@ * There is one special case, if the dividend is the * {@linkplain Long#MIN_VALUE Long.MIN_VALUE} and the divisor is {@code -1}, * then integer overflow occurs and + * the result is equal to {@code Long.MIN_VALUE}. + *

+ * 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 + * @see Math#floorDiv(long, int) + * @see Math#floor(double) + * @since 1.9 + */ + public static long floorDiv(long x, int y) { + return Math.floorDiv(x, y); + } + + /** + * Returns the largest (closest to positive infinity) + * {@code long} value that is less than or equal to the algebraic quotient. + * There is one special case, if the dividend is the + * {@linkplain Long#MIN_VALUE Long.MIN_VALUE} and the divisor is {@code -1}, + * then integer overflow occurs and * the result is equal to the {@code Long.MIN_VALUE}. *

* See {@link Math#floorDiv(int, int) Math.floorDiv} for examples and @@ -903,6 +942,35 @@ public static int floorMod(int x, int y) { return Math.floorMod(x , y); } + + /** + * Returns the floor modulus of the {@code long} and {@int} arguments. + *

+ * The floor modulus is {@code x - (floorDiv(x, y) * y)}, + * has the same sign as the divisor {@code y}, and + * is in the range of {@code -abs(y) < r < +abs(y)}. + * + *

+ * The relationship between {@code floorDiv} and {@code floorMod} is such that: + *

+ *
• {@code floorDiv(x, y) * y + floorMod(x, y) == x} + *
+ *

+ * See {@link Math#floorMod(int, int) Math.floorMod} for examples and + * a comparison to the {@code %} operator. + * + * @param x the dividend + * @param y the divisor + * @return the floor modulus {@code x - (floorDiv(x, y) * y)} + * @throws ArithmeticException if the divisor {@code y} is zero + * @see Math#floorMod(long, int) + * @see StrictMath#floorDiv(long, int) + * @since 1.9 + */ + public static int floorMod(long x, int y) { + return Math.floorMod(x , y); + } + /** * Returns the floor modulus of the {@code long} arguments. *