--- a/jdk/src/share/classes/java/lang/Math.java Wed Nov 07 17:39:34 2012 -0800
+++ b/jdk/src/share/classes/java/lang/Math.java Wed Nov 07 20:50:09 2012 -0800
@@ -742,6 +742,7 @@
* @param y the second value
* @return the result
* @throws ArithmeticException if the result overflows an int
+ * @since 1.8
*/
public static int addExact(int x, int y) {
int r = x + y;
@@ -760,6 +761,7 @@
* @param y the second value
* @return the result
* @throws ArithmeticException if the result overflows a long
+ * @since 1.8
*/
public static long addExact(long x, long y) {
long r = x + y;
@@ -778,6 +780,7 @@
* @param y the second value to subtract from the first
* @return the result
* @throws ArithmeticException if the result overflows an int
+ * @since 1.8
*/
public static int subtractExact(int x, int y) {
int r = x - y;
@@ -797,6 +800,7 @@
* @param y the second value to subtract from the first
* @return the result
* @throws ArithmeticException if the result overflows a long
+ * @since 1.8
*/
public static long subtractExact(long x, long y) {
long r = x - y;
@@ -816,6 +820,7 @@
* @param y the second value
* @return the result
* @throws ArithmeticException if the result overflows an int
+ * @since 1.8
*/
public static int multiplyExact(int x, int y) {
long r = (long)x * (long)y;
@@ -833,6 +838,7 @@
* @param y the second value
* @return the result
* @throws ArithmeticException if the result overflows a long
+ * @since 1.8
*/
public static long multiplyExact(long x, long y) {
long r = x * y;
@@ -857,6 +863,7 @@
* @param value the long value
* @return the argument as an int
* @throws ArithmeticException if the {@code argument} overflows an int
+ * @since 1.8
*/
public static int toIntExact(long value) {
if ((int)value != value) {
@@ -866,6 +873,159 @@
}
/**
+ * Returns the largest (closest to positive infinity)
+ * {@code int} value that is less than or equal to the algebraic quotient.
+ * There is one special case, if the dividend is the
+ * {@linkplain Integer#MIN_VALUE Integer.MIN_VALUE} and the divisor is {@code -1},
+ * then integer overflow occurs and
+ * the result is equal to the {@code Integer.MIN_VALUE}.
+ * <p>
+ * 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
+ * when the exact result is negative.
+ * <ul>
+ * <li>If the signs of the arguments are the same, the results of
+ * {@code floorDiv} and the {@code /} operator are the same. <br>
+ * For example, {@code floorDiv(4, 3) == 1} and {@code (4 / 3) == 1}.</li>
+ * <li>If the signs of the arguments are different, the quotient is negative and
+ * {@code floorDiv} returns the integer less than or equal to the quotient
+ * and the {@code /} operator returns the integer closest to zero.<br>
+ * For example, {@code floorDiv(-4, 3) == -2},
+ * whereas {@code (-4 / 3) == -1}.
+ * </li>
+ * </ul>
+ * <p>
+ *
+ * @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(int, int)
+ * @see #floor(double)
+ * @since 1.8
+ */
+ public static int floorDiv(int x, int y) {
+ int r = x / y;
+ // if the signs are different and modulo not zero, round down
+ if ((x ^ y) < 0 && (r * y != x)) {
+ r--;
+ }
+ return r;
+ }
+
+ /**
+ * 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>
+ * 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
+ * when the exact result is negative.
+ * <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
+ * @see #floorMod(long, long)
+ * @see #floor(double)
+ * @since 1.8
+ */
+ public static long floorDiv(long x, long y) {
+ long r = x / y;
+ // if the signs are different and modulo not zero, round down
+ if ((x ^ y) < 0 && (r * y != x)) {
+ r--;
+ }
+ return r;
+ }
+
+ /**
+ * Returns the floor modulus of the {@code 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>
+ * The difference in values between {@code floorMod} and
+ * the {@code %} operator is due to the difference between
+ * {@code floorDiv} that returns the integer less than or equal to the quotient
+ * and the {@code /} operator that returns the integer closest to zero.
+ * <p>
+ * Examples:
+ * <ul>
+ * <li>If the signs of the arguments are the same, the results
+ * of {@code floorMod} and the {@code %} operator are the same. <br>
+ * <ul>
+ * <li>{@code floorMod(4, 3) == 1}; and {@code (4 % 3) == 1}</li>
+ * </ul>
+ * <li>If the signs of the arguments are different, the results differ from the {@code %} operator.<br>
+ * <ul>
+ * <li>{@code floorMod(+4, -3) == -2}; and {@code (+4 % -3) == +1} </li>
+ * <li>{@code floorMod(-4, +3) == +2}; and {@code (-4 % +3) == -1} </li>
+ * <li>{@code floorMod(-4, -3) == -1}; and {@code (-4 % -3) == -1 } </li>
+ * </ul>
+ * </li>
+ * </ul>
+ * <p>
+ * If the signs of arguments are unknown and a positive modulus
+ * is needed it can be computed as {@code (floorMod(x, y) + abs(y)) % abs(y)}.
+ *
+ * @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 #floorDiv(int, int)
+ * @since 1.8
+ */
+ public static int floorMod(int x, int y) {
+ int r = x - floorDiv(x, y) * y;
+ return r;
+ }
+
+ /**
+ * 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
+ * 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>
+ * 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
+ * @see #floorDiv(long, long)
+ * @since 1.8
+ */
+ public static long floorMod(long x, long y) {
+ return x - floorDiv(x, y) * y;
+ }
+
+ /**
* Returns the absolute value of an {@code int} value.
* If the argument is not negative, the argument is returned.
* If the argument is negative, the negation of the argument is returned.