From 423af129a152d16f2b3a3677524c5976e90dcabd Mon Sep 17 00:00:00 2001 From: Raffaello Giulietti Date: Tue, 3 Aug 2021 00:25:50 +0200 Subject: [PATCH 1/4] 8271599: Javadoc of floorDiv() and floorMod() families is inaccurate in some places --- .../share/classes/java/lang/Math.java | 51 +++++++++---------- 1 file changed, 24 insertions(+), 27 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..2967b31c5f084 100644 --- a/src/java.base/share/classes/java/lang/Math.java +++ b/src/java.base/share/classes/java/lang/Math.java @@ -1247,7 +1247,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 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}. @@ -1256,14 +1256,16 @@ public static long unsignedMultiplyHigh(long x, long y) { * (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. + * when the exact quotient is not an integer and is negative. * *

- * 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. + * The difference in values between {@code floorMod} and the {@code %} operator + * is due to the difference between {@code floorDiv} and the {@code /} + * operator, as detailed in {@linkplain #floorDiv(int, int)}. *

* Examples: *

*

- * 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 @@ -1407,8 +1404,8 @@ public static int floorMod(int x, int y) { /** * Returns the floor modulus of the {@code long} and {@code int} arguments. *

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

@@ -1434,8 +1431,8 @@ public static int floorMod(long x, int y) { /** * Returns the floor modulus of the {@code long} arguments. *

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

From cab4c54c10580838b6b644aa9a7e8ceb5ff29571 Mon Sep 17 00:00:00 2001 From: Raffaello Giulietti Date: Wed, 4 Aug 2021 00:20:40 +0200 Subject: [PATCH 2/4] 8271599: Javadoc of floorDiv() and floorMod() families is inaccurate in some places --- .../share/classes/java/lang/Math.java | 6 ++-- .../share/classes/java/lang/StrictMath.java | 34 ++++++++++--------- 2 files changed, 21 insertions(+), 19 deletions(-) diff --git a/src/java.base/share/classes/java/lang/Math.java b/src/java.base/share/classes/java/lang/Math.java index 2967b31c5f084..862aa26fd77fc 100644 --- a/src/java.base/share/classes/java/lang/Math.java +++ b/src/java.base/share/classes/java/lang/Math.java @@ -1362,7 +1362,7 @@ public static long floorDiv(long x, long y) { *

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

*

* The difference in values between {@code floorMod} and the {@code %} operator @@ -1411,7 +1411,7 @@ public static int floorMod(int x, int y) { *

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

*

* For examples, see {@link #floorMod(int, int)}. @@ -1438,7 +1438,7 @@ public static int floorMod(long x, int y) { *

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

*

* For examples, see {@link #floorMod(int, int)}. diff --git a/src/java.base/share/classes/java/lang/StrictMath.java b/src/java.base/share/classes/java/lang/StrictMath.java index 427fa7080ba5c..d1d9d1c57e8a0 100644 --- a/src/java.base/share/classes/java/lang/StrictMath.java +++ b/src/java.base/share/classes/java/lang/StrictMath.java @@ -1051,10 +1051,10 @@ 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 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}. + * the result is equal to {@code Integer.MIN_VALUE}. *

* See {@link Math#floorDiv(int, int) Math.floorDiv} for examples and * a comparison to the integer division {@code /} operator. @@ -1075,7 +1075,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 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}. @@ -1099,10 +1099,10 @@ 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 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}. *

* See {@link Math#floorDiv(int, int) Math.floorDiv} for examples and * a comparison to the integer division {@code /} operator. @@ -1123,13 +1123,14 @@ public static long floorDiv(long x, long y) { /** * Returns the floor modulus of the {@code int} arguments. *

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

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

*

* See {@link Math#floorMod(int, int) Math.floorMod} for examples and @@ -1148,16 +1149,16 @@ public static int floorMod(int x, int y) { } /** - * Returns the floor modulus of the {@code long} and {@code int} arguments. + * Returns the floor modulus of the {@code int} arguments. *

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

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

*

* See {@link Math#floorMod(int, int) Math.floorMod} for examples and @@ -1176,15 +1177,16 @@ public static int floorMod(long x, int y) { } /** - * Returns the floor modulus of the {@code long} arguments. + * Returns the floor modulus of the {@code int} arguments. *

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

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

*

* See {@link Math#floorMod(int, int) Math.floorMod} for examples and From dc81446fb921c5389186eebc31381496810ad927 Mon Sep 17 00:00:00 2001 From: Raffaello Giulietti Date: Wed, 4 Aug 2021 00:29:01 +0200 Subject: [PATCH 3/4] 8271599: Javadoc of floorDiv() and floorMod() families is inaccurate in some places --- src/java.base/share/classes/java/lang/StrictMath.java | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/java.base/share/classes/java/lang/StrictMath.java b/src/java.base/share/classes/java/lang/StrictMath.java index d1d9d1c57e8a0..2ce70f78ce083 100644 --- a/src/java.base/share/classes/java/lang/StrictMath.java +++ b/src/java.base/share/classes/java/lang/StrictMath.java @@ -1149,7 +1149,7 @@ public static int floorMod(int x, int y) { } /** - * Returns the floor modulus of the {@code int} arguments. + * Returns the floor modulus of the {@code long} and {@code int} arguments. *

* The floor modulus is {@code r = x - (floorDiv(x, y) * y)}, * has the same sign as the divisor {@code y} or is zero, and @@ -1177,7 +1177,7 @@ public static int floorMod(long x, int y) { } /** - * Returns the floor modulus of the {@code int} arguments. + * Returns the floor modulus of the {@code long} arguments. *

* The floor modulus is {@code r = x - (floorDiv(x, y) * y)}, * has the same sign as the divisor {@code y} or is zero, and From 21e4f370ced11eeb41ef19999dcbead656664b99 Mon Sep 17 00:00:00 2001 From: Raffaello Giulietti Date: Wed, 4 Aug 2021 00:40:11 +0200 Subject: [PATCH 4/4] 8271599: Javadoc of floorDiv() and floorMod() families is inaccurate in some places --- src/java.base/share/classes/java/lang/Math.java | 8 ++++---- src/java.base/share/classes/java/lang/StrictMath.java | 6 +++--- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/src/java.base/share/classes/java/lang/Math.java b/src/java.base/share/classes/java/lang/Math.java index 862aa26fd77fc..4540aceea49ee 100644 --- a/src/java.base/share/classes/java/lang/Math.java +++ b/src/java.base/share/classes/java/lang/Math.java @@ -1247,7 +1247,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}. @@ -1265,7 +1265,7 @@ public static long unsignedMultiplyHigh(long x, long y) { * returns the largest integer less than or equal to the quotient * while the {@code /} operator returns the smallest integer greater * than or equal to the quotient. - * There's a difference if and only if the quotient is not an integer.
+ * They differ if and only if the quotient is not an integer.
* For example, {@code floorDiv(-4, 3) == -2}, * whereas {@code (-4 / 3) == -1}. * @@ -1292,7 +1292,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}. @@ -1321,7 +1321,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 2ce70f78ce083..062e3fd3709d1 100644 --- a/src/java.base/share/classes/java/lang/StrictMath.java +++ b/src/java.base/share/classes/java/lang/StrictMath.java @@ -1051,7 +1051,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}. @@ -1075,7 +1075,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 +1099,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}.