src/java.base/share/classes/java/lang/StrictMath.java

Print this page
rev 12809 : 8023217: Additional floorDiv/floorMod/multiplyExact methods for java.lang.Math
Summary: Add new methods with long, int signatures.
Reviewed-by: XXX

*** 68,78 **** * 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}, 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 * a specific minimum or maximum value and should be checked against * the minimum or maximum as appropriate. * * @author unascribed * @author Joseph D. Darcy --- 68,78 ---- * 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}, and {@code toIntExact} * throw an {@code ArithmeticException} when the results overflow. * For other arithmetic operations such as divide, absolute value, ! * 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. * * @author unascribed * @author Joseph D. Darcy
*** 799,808 **** --- 799,823 ---- public static int multiplyExact(int x, int y) { return Math.multiplyExact(x, y); } /** + * 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}. * * @param x the first value * @param y the second value
*** 857,866 **** --- 872,905 ---- * 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}. + * <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 + * @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}. * <p> * See {@link Math#floorDiv(int, int) Math.floorDiv} for examples and * a comparison to the integer division {@code /} operator. *
*** 901,910 **** --- 940,978 ---- * @since 1.8 */ public static int floorMod(int x, int y) { return Math.floorMod(x , y); } + + /** + * Returns the floor modulus of the {@code long} and {@int} arguments. + * <p> + * 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)}. + * + * <p> + * The relationship between {@code floorDiv} and {@code floorMod} is such that: + * <ul> + * <li>{@code floorDiv(x, y) * y + floorMod(x, y) == x} + * </ul> + * <p> + * 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. * <p> * The floor modulus is {@code x - (floorDiv(x, y) * y)}, * has the same sign as the divisor {@code y}, and