From 03e83cda321c4b698c3255f00568052583c9a90f Mon Sep 17 00:00:00 2001 From: Brian Burkhalter Date: Thu, 29 Jul 2021 12:17:40 -0700 Subject: [PATCH 1/4] 8271225: Add floorDivExact() method to java.lang.[Strict]Math --- .../share/classes/java/lang/Math.java | 103 +++++++++++++++++- .../share/classes/java/lang/StrictMath.java | 89 ++++++++++++++- test/jdk/java/lang/Math/ExactArithTests.java | 62 ++++++++++- 3 files changed, 245 insertions(+), 9 deletions(-) diff --git a/src/java.base/share/classes/java/lang/Math.java b/src/java.base/share/classes/java/lang/Math.java index 4f69b67a058f1..4d8356afdb846 100644 --- 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 static long multiplyExact(long x, long y) { *

* If {@code y} is zero, an {@code ArithmeticException} is thrown * (JLS {@jls 15.17.2}). + *

+ * It should be noted that the operator "{@code %}" is a suitable remainder + * couterpart of this method as it is of the division operator "{@code /}". * * @param x the dividend * @param y the divisor @@ -1039,6 +1042,9 @@ public static int divideExact(int x, int y) { *

* If {@code y} is zero, an {@code ArithmeticException} is thrown * (JLS {@jls 15.17.2}). + *

+ * It should be noted that the operator "{@code %}" is a suitable remainder + * couterpart of this method as it is of the division operator "{@code /}". * * @param x the dividend * @param y the divisor @@ -1056,6 +1062,97 @@ public static long divideExact(long x, long y) { 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. + * If the dividend is {@linkplain Integer#MIN_VALUE Integer.MIN_VALUE} and + * the divisor is {@code -1}, then integer overflow occurs and an + * {@code ArithmeticException} is thrown. + *

+ * 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. + *

+ *

+ * It should be noted that the method {@link #floorMod(int,int)} is a + * suitable modulus couterpart of this method as it is of the + * {@link #floorDiv(int,int)} method. + * + * @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) { + int r = x / y; + if ((x & y & r) >= 0) { + // if the signs are different and modulo not zero, round down + if ((x ^ y) < 0 && (r * y != x)) { + r--; + } + return r; + } + throw new ArithmeticException("integer overflow"); + } + + /** + * Returns the largest (closest to positive infinity) + * {@code long} value that is less than or equal to the algebraic quotient. + * If the dividend is {@linkplain Long#MIN_VALUE Long.MIN_VALUE} and the + * divisor is {@code -1}, then integer overflow occurs and an + * {@code ArithmeticException} is thrown. + *

+ * 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)}. + *

+ * It should be noted that the method {@link #floorMod(long,long)} is a + * suitable modulus couterpart of this method as it is of the + * {@link #floorDiv(long,long)} method. + * + * @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) { + long r = x / y; + if ((x & y & r) >= 0) { + // if the signs are different and modulo not zero, round down + if ((x ^ y) < 0 && (r * y != x)) { + r--; + } + return r; + } + throw new ArithmeticException("long overflow"); + } + /** * Returns the argument incremented by one, throwing an exception if the * result overflows an {@code int}. @@ -1247,7 +1344,7 @@ public static long unsignedMultiplyHigh(long x, long y) { /** * 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 + * There is one special case, if the dividend is * {@linkplain Integer#MIN_VALUE Integer.MIN_VALUE} and the divisor is {@code -1}, * then integer overflow occurs and * the result is equal to {@code Integer.MIN_VALUE}. @@ -1290,7 +1387,7 @@ public static int floorDiv(int x, int 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 + * There is one special case, if the dividend is * {@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}. @@ -1319,7 +1416,7 @@ public static long floorDiv(long x, int 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 + * There is one special case, if the dividend is * {@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}. diff --git a/src/java.base/share/classes/java/lang/StrictMath.java b/src/java.base/share/classes/java/lang/StrictMath.java index 427fa7080ba5c..de69ee8811e12 100644 --- 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 static long multiplyExact(long x, long y) { *

* If {@code y} is zero, an {@code ArithmeticException} is thrown * (JLS {@jls 15.17.2}). + *

+ * It should be noted that the operator "{@code %}" is a suitable remainder + * couterpart of this method as it is of the division operator "{@code /}". * * @param x the dividend * @param y the divisor @@ -887,6 +890,9 @@ public static int divideExact(int x, int y) { *

* If {@code y} is zero, an {@code ArithmeticException} is thrown * (JLS {@jls 15.17.2}). + *

+ * It should be noted that the operator "{@code %}" is a suitable remainder + * couterpart of this method as it is of the division operator "{@code /}". * * @param x the dividend * @param y the divisor @@ -901,6 +907,83 @@ public static long divideExact(long x, long y) { 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. + * If the dividend is {@linkplain Integer#MIN_VALUE Integer.MIN_VALUE} and + * the divisor is {@code -1}, then integer overflow occurs and an + * {@code ArithmeticException} is thrown. + *

+ * 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. + *

+ *

+ * It should be noted that the method {@link #floorMod(int,int)} is a + * suitable modulus couterpart of this method as it is of the + * {@link #floorDiv(int,int)} method. + * + * @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) + * @see Math#floorDiv(int, int) + * @since 18 + */ + public static int floorDivExact(int x, int y) { + return Math.floorDivExact(x, y); + } + + /** + * Returns the largest (closest to positive infinity) + * {@code long} value that is less than or equal to the algebraic quotient. + * If the dividend is {@linkplain Long#MIN_VALUE Long.MIN_VALUE} and the + * divisor is {@code -1}, then integer overflow occurs and an + * {@code ArithmeticException} is thrown. + *

+ * 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)}. + *

+ * It should be noted that the method {@link #floorMod(long,long)} is a + * suitable modulus couterpart of this method as it is of the + * {@link #floorDiv(long,long)} method. + * + * @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) + * @see Math#floorDiv(long, long) + * @since 18 + */ + public static long floorDivExact(long x, long y) { + return Math.floorDivExact(x, y); + } + /** * Returns the argument incremented by one, * throwing an exception if the result overflows an {@code int}. @@ -1051,7 +1134,7 @@ public static long unsignedMultiplyHigh(long x, long y) { /** * 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 + * There is one special case, if the dividend is * {@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}. @@ -1075,7 +1158,7 @@ public static int floorDiv(int x, int 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 + * There is one special case, if the dividend is * {@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}. @@ -1099,7 +1182,7 @@ public static long floorDiv(long x, int 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 + * There is one special case, if the dividend is * {@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}. diff --git a/test/jdk/java/lang/Math/ExactArithTests.java b/test/jdk/java/lang/Math/ExactArithTests.java index 6a620f8c51a6b..205a9be4b93fa 100644 --- a/test/jdk/java/lang/Math/ExactArithTests.java +++ b/test/jdk/java/lang/Math/ExactArithTests.java @@ -57,7 +57,7 @@ static void fail(String message) { /** * Test Math.addExact, multiplyExact, divideExact, subtractExact, - * incrementExact, decrementExact, negateExact methods with + * floorDivExact, incrementExact, decrementExact, negateExact methods with * {@code int} arguments. */ static void testIntegerExact() { @@ -166,6 +166,34 @@ static void testIntegerExact(int x, int y) { } } + exceptionExpected = false; + try { + // Test floorDivExact + int q = 0; + try { + q = Math.floorDiv(x, y); + } catch (ArithmeticException e) { + exceptionExpected = true; + } + if (!exceptionExpected && x == Integer.MIN_VALUE && y == -1) { + exceptionExpected = true; + } + int z = Math.floorDivExact(x, y); + if (exceptionExpected) { + fail("FAIL: int Math.floorDivExact(" + x + " / " + y + ")" + + "; expected ArithmeticException not thrown"); + } + if (z != q) { + fail("FAIL: int Math.floorDivExact(" + x + " / " + y + ") = " + + z + "; expected: " + q); + } + } catch (ArithmeticException ex) { + if (!exceptionExpected) { + fail("FAIL: int Math.floorDivExact(" + x + " / " + y + ")" + + "; Unexpected exception: " + ex); + } + } + try { // Test incrementExact int inc = Math.incrementExact(x); @@ -217,8 +245,8 @@ static void testIntegerExact(int x, int y) { /** * Test Math.addExact, multiplyExact, divideExact, subtractExact, - * incrementExact, decrementExact, negateExact, toIntExact methods - * with {@code long} arguments. + * floorDivExact, incrementExact, decrementExact, negateExact, toIntExact + * methods with {@code long} arguments. */ static void testLongExact() { testLongExactTwice(0, 0); @@ -324,6 +352,34 @@ static void testLongExact(long x, long y) { } } + boolean exceptionExpected = false; + try { + // Test floorDivExact + long q = 0; + try { + q = Math.floorDiv(x, y); + } catch (ArithmeticException e) { + exceptionExpected = true; + } + if (!exceptionExpected && x == Long.MIN_VALUE && y == -1) { + exceptionExpected = true; + } + long z = Math.floorDivExact(x, y); + if (exceptionExpected) { + fail("FAIL: long Math.floorDivExact(" + x + " / " + y + ")" + + "; expected ArithmeticException not thrown"); + } + if (z != q) { + fail("FAIL: long Math.floorDivExact(" + x + " / " + y + ") = " + + z + "; expected: " + q); + } + } catch (ArithmeticException ex) { + if (!exceptionExpected) { + fail("FAIL: long Math.floorDivExact(" + x + " / " + y + ")" + + "; Unexpected exception: " + ex); + } + } + try { // Test incrementExact resultBig = xBig.add(BigInteger.ONE); From 7601fe9bce6203ddbc915fa2d8a923294d9437fd Mon Sep 17 00:00:00 2001 From: Brian Burkhalter Date: Mon, 2 Aug 2021 17:11:14 -0700 Subject: [PATCH 2/4] 8271225: Some verbiage updates --- .../share/classes/java/lang/Math.java | 20 +++++++++---------- .../share/classes/java/lang/StrictMath.java | 20 +++++++++---------- 2 files changed, 20 insertions(+), 20 deletions(-) diff --git a/src/java.base/share/classes/java/lang/Math.java b/src/java.base/share/classes/java/lang/Math.java index 4d8356afdb846..2f17138785a4f 100644 --- a/src/java.base/share/classes/java/lang/Math.java +++ b/src/java.base/share/classes/java/lang/Math.java @@ -1013,8 +1013,8 @@ public static long multiplyExact(long x, long y) { * If {@code y} is zero, an {@code ArithmeticException} is thrown * (JLS {@jls 15.17.2}). *

- * It should be noted that the operator "{@code %}" is a suitable remainder - * couterpart of this method as it is of the division operator "{@code /}". + * 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 @@ -1043,8 +1043,8 @@ public static int divideExact(int x, int y) { * If {@code y} is zero, an {@code ArithmeticException} is thrown * (JLS {@jls 15.17.2}). *

- * It should be noted that the operator "{@code %}" is a suitable remainder - * couterpart of this method as it is of the division operator "{@code /}". + * 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 @@ -1086,9 +1086,9 @@ public static long divideExact(long x, long y) { * * *

- * It should be noted that the method {@link #floorMod(int,int)} is a - * suitable modulus couterpart of this method as it is of the - * {@link #floorDiv(int,int)} method. + * The floor modulus method {@link #floorMod(int,int)} is a suitable + * counterpart both for this method and for the {@link #floorDiv(int,int)} + * method. * * @param x the dividend * @param y the divisor @@ -1127,9 +1127,9 @@ public static int floorDivExact(int x, int y) { *

* For examples, see {@link #floorDiv(int, int)}. *

- * It should be noted that the method {@link #floorMod(long,long)} is a - * suitable modulus couterpart of this method as it is of the - * {@link #floorDiv(long,long)} method. + * The floor modulus method {@link #floorMod(long,long)} is a suitable + * counterpart both for this method and for the {@link #floorDiv(long,long)} + * method. * * @param x the dividend * @param y the divisor diff --git a/src/java.base/share/classes/java/lang/StrictMath.java b/src/java.base/share/classes/java/lang/StrictMath.java index de69ee8811e12..4cae994e05a57 100644 --- a/src/java.base/share/classes/java/lang/StrictMath.java +++ b/src/java.base/share/classes/java/lang/StrictMath.java @@ -864,8 +864,8 @@ public static long multiplyExact(long x, long y) { * If {@code y} is zero, an {@code ArithmeticException} is thrown * (JLS {@jls 15.17.2}). *

- * It should be noted that the operator "{@code %}" is a suitable remainder - * couterpart of this method as it is of the division operator "{@code /}". + * 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 @@ -891,8 +891,8 @@ public static int divideExact(int x, int y) { * If {@code y} is zero, an {@code ArithmeticException} is thrown * (JLS {@jls 15.17.2}). *

- * It should be noted that the operator "{@code %}" is a suitable remainder - * couterpart of this method as it is of the division operator "{@code /}". + * 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 @@ -931,9 +931,9 @@ public static long divideExact(long x, long y) { * * *

- * It should be noted that the method {@link #floorMod(int,int)} is a - * suitable modulus couterpart of this method as it is of the - * {@link #floorDiv(int,int)} method. + * The floor modulus method {@link #floorMod(int,int)} is a suitable + * counterpart both for this method and for the {@link #floorDiv(int,int)} + * method. * * @param x the dividend * @param y the divisor @@ -965,9 +965,9 @@ public static int floorDivExact(int x, int y) { *

* For examples, see {@link #floorDiv(int, int)}. *

- * It should be noted that the method {@link #floorMod(long,long)} is a - * suitable modulus couterpart of this method as it is of the - * {@link #floorDiv(long,long)} method. + * The floor modulus method {@link #floorMod(long,long)} is a suitable + * counterpart both for this method and for the {@link #floorDiv(long,long)} + * method. * * @param x the dividend * @param y the divisor From 2b119d52211b7ffd5e4c07630adcfdf5f17973c7 Mon Sep 17 00:00:00 2001 From: Brian Burkhalter Date: Thu, 5 Aug 2021 09:58:18 -0700 Subject: [PATCH 3/4] 8271225: Revert drive-by verbiage updates --- src/java.base/share/classes/java/lang/Math.java | 6 +++--- src/java.base/share/classes/java/lang/StrictMath.java | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/src/java.base/share/classes/java/lang/Math.java b/src/java.base/share/classes/java/lang/Math.java index 2f17138785a4f..2c963ace4ef00 100644 --- a/src/java.base/share/classes/java/lang/Math.java +++ b/src/java.base/share/classes/java/lang/Math.java @@ -1344,7 +1344,7 @@ public static long unsignedMultiplyHigh(long x, long y) { /** * 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 + * 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 {@code Integer.MIN_VALUE}. @@ -1387,7 +1387,7 @@ public static int floorDiv(int x, int 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 + * 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}. @@ -1416,7 +1416,7 @@ public static long floorDiv(long x, int 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 + * 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}. diff --git a/src/java.base/share/classes/java/lang/StrictMath.java b/src/java.base/share/classes/java/lang/StrictMath.java index 4cae994e05a57..b397763c4ccd7 100644 --- a/src/java.base/share/classes/java/lang/StrictMath.java +++ b/src/java.base/share/classes/java/lang/StrictMath.java @@ -1134,7 +1134,7 @@ public static long unsignedMultiplyHigh(long x, long y) { /** * 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 + * 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}. @@ -1158,7 +1158,7 @@ public static int floorDiv(int x, int 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 + * 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}. @@ -1182,7 +1182,7 @@ public static long floorDiv(long x, int 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 + * 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}. From fac5107a97826f2ac8846b489aa3b668d381000a Mon Sep 17 00:00:00 2001 From: Brian Burkhalter Date: Thu, 5 Aug 2021 11:40:54 -0700 Subject: [PATCH 4/4] 8271225: Verbiage update after 8271599 --- .../share/classes/java/lang/Math.java | 47 ++++++----------- .../share/classes/java/lang/StrictMath.java | 51 +++++++------------ 2 files changed, 32 insertions(+), 66 deletions(-) diff --git a/src/java.base/share/classes/java/lang/Math.java b/src/java.base/share/classes/java/lang/Math.java index f104c2fb71c8d..fa9516e41988d 100644 --- a/src/java.base/share/classes/java/lang/Math.java +++ b/src/java.base/share/classes/java/lang/Math.java @@ -1065,30 +1065,17 @@ public static long divideExact(long x, long y) { /** * Returns the largest (closest to positive infinity) * {@code int} value that is less than or equal to the algebraic quotient. - * If the dividend is {@linkplain Integer#MIN_VALUE Integer.MIN_VALUE} and - * the divisor is {@code -1}, then integer overflow occurs and an - * {@code ArithmeticException} is thrown. - *

- * 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. - *

+ * 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}. *

* The floor modulus method {@link #floorMod(int,int)} is a suitable * counterpart both for this method and for the {@link #floorDiv(int,int)} * method. + *

+ * For examples, see {@link #floorDiv(int, int)}. * * @param x the dividend * @param y the divisor @@ -1115,21 +1102,17 @@ 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. - * If the dividend is {@linkplain Long#MIN_VALUE Long.MIN_VALUE} and the - * divisor is {@code -1}, then integer overflow occurs and an - * {@code ArithmeticException} is thrown. - *

- * 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)}. + * 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}. *

* The floor modulus method {@link #floorMod(long,long)} is a suitable * counterpart both for this method and for the {@link #floorDiv(long,long)} * method. + *

+ * For examples, see {@link #floorDiv(int, int)}. * * @param x the dividend * @param y the divisor @@ -1138,7 +1121,7 @@ public static int floorDivExact(int x, int y) { * @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) + * @see #floorDiv(long,long) * @since 18 */ public static long floorDivExact(long x, long y) { diff --git a/src/java.base/share/classes/java/lang/StrictMath.java b/src/java.base/share/classes/java/lang/StrictMath.java index a40818213fbf1..d93db10af05fa 100644 --- a/src/java.base/share/classes/java/lang/StrictMath.java +++ b/src/java.base/share/classes/java/lang/StrictMath.java @@ -910,30 +910,18 @@ public static long divideExact(long x, long y) { /** * Returns the largest (closest to positive infinity) * {@code int} value that is less than or equal to the algebraic quotient. - * If the dividend is {@linkplain Integer#MIN_VALUE Integer.MIN_VALUE} and - * the divisor is {@code -1}, then integer overflow occurs and an - * {@code ArithmeticException} is thrown. - *

- * 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. - *

+ * 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}. *

* The floor modulus method {@link #floorMod(int,int)} is a suitable * counterpart both for this method and for the {@link #floorDiv(int,int)} * method. + *

+ * 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 @@ -942,7 +930,6 @@ public static long divideExact(long x, long y) { * @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) * @see Math#floorDiv(int, int) * @since 18 */ @@ -953,21 +940,17 @@ 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. - * If the dividend is {@linkplain Long#MIN_VALUE Long.MIN_VALUE} and the - * divisor is {@code -1}, then integer overflow occurs and an - * {@code ArithmeticException} is thrown. - *

- * 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)}. + * 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}. *

* The floor modulus method {@link #floorMod(long,long)} is a suitable * counterpart both for this method and for the {@link #floorDiv(long,long)} * method. + *

+ * For examples, see {@link Math#floorDiv(int, int) Math.floorDiv}. * * @param x the dividend * @param y the divisor @@ -976,8 +959,8 @@ public static int floorDivExact(int x, int y) { * @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) - * @see Math#floorDiv(long, long) + * @see Math#floorDiv(int, int) + * @see Math#floorDiv(long,long) * @since 18 */ public static long floorDivExact(long x, long y) {