Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
8271599: Javadoc of floorDiv() and floorMod() families is inaccurate … 
…in some places

Reviewed-by: darcy, bpb
  • Loading branch information
@rgiulietti
rgiulietti authored and Brian Burkhalter committed Aug 4, 2021
1 parent 452f7d7 commit 9f1edaf
Show file tree
Hide file tree
Showing 2 changed files with 43 additions and 44 deletions.
57 changes: 27 additions & 30 deletions src/java.base/share/classes/java/lang/Math.java
View file
Expand Up @@ -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}.
Expand All @@ -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.
* <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>
* <li>If the signs of the arguments are different, {@code floorDiv}
* 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.
* They differ if and only if the quotient is not an integer.<br>
* For example, {@code floorDiv(-4, 3) == -2},
* whereas {@code (-4 / 3) == -1}.
* </li>
Expand All @@ -1290,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}.
Expand All @@ -1299,7 +1301,7 @@ public static int floorDiv(int x, int 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 result is not an integer and is negative.
* <p>
* For examples, see {@link #floorDiv(int, int)}.
*
Expand All @@ -1319,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}.
Expand All @@ -1328,7 +1330,7 @@ public static long floorDiv(long x, int 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 result is not an integer and is negative.
* <p>
* For examples, see {@link #floorDiv(int, int)}.
*
Expand All @@ -1353,40 +1355,35 @@ public static long floorDiv(long x, long y) {
/**
* 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
* 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)}.
*
* <p>
* The relationship between {@code floorDiv} and {@code floorMod} is such that:
* <ul>
* <li>{@code floorDiv(x, y) * y + floorMod(x, y) == x}
* <li>{@code floorDiv(x, y) * y + floorMod(x, y) == x}</li>
* </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.
* 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)}.
* <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>
* <li>Regardless of the signs of the arguments, {@code floorMod}(x, y)
* is zero exactly when {@code x % y} is zero as well.</li>
* <li>If neither of {@code floorMod}(x, y) or {@code x % y} is zero,
* their results differ exactly when the signs of the arguments differ.<br>
* <ul>
* <li>{@code floorMod(+4, +3) == +1}; &nbsp; and {@code (+4 % +3) == +1}</li>
* <li>{@code floorMod(-4, -3) == -1}; &nbsp; 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}; &nbsp; and {@code (+4 % -3) == +1}</li>
* <li>{@code floorMod(-4, +3) == +2}; &nbsp; 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
Expand All @@ -1407,14 +1404,14 @@ public static int floorMod(int x, int y) {
/**
* Returns the floor modulus of the {@code long} and {@code int} arguments.
* <p>
* 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)}.
*
* <p>
* The relationship between {@code floorDiv} and {@code floorMod} is such that:
* <ul>
* <li>{@code floorDiv(x, y) * y + floorMod(x, y) == x}
* <li>{@code floorDiv(x, y) * y + floorMod(x, y) == x}</li>
* </ul>
* <p>
* For examples, see {@link #floorMod(int, int)}.
Expand All @@ -1434,14 +1431,14 @@ public static int floorMod(long x, int 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
* 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)}.
*
* <p>
* The relationship between {@code floorDiv} and {@code floorMod} is such that:
* <ul>
* <li>{@code floorDiv(x, y) * y + floorMod(x, y) == x}
* <li>{@code floorDiv(x, y) * y + floorMod(x, y) == x}</li>
* </ul>
* <p>
* For examples, see {@link #floorMod(int, int)}.
Expand Down
30 changes: 16 additions & 14 deletions src/java.base/share/classes/java/lang/StrictMath.java
View file
Expand Up @@ -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
* {@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}.
* <p>
* See {@link Math#floorDiv(int, int) Math.floorDiv} for examples and
* a comparison to the integer division {@code /} operator.
Expand All @@ -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}.
Expand All @@ -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
* {@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}.
* <p>
* See {@link Math#floorDiv(int, int) Math.floorDiv} for examples and
* a comparison to the integer division {@code /} operator.
Expand All @@ -1123,13 +1123,14 @@ public static long floorDiv(long x, long y) {
/**
* 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
* 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)}.
*
* <p>
* The relationship between {@code floorDiv} and {@code floorMod} is such that:
* <ul>
* <li>{@code floorDiv(x, y) * y + floorMod(x, y) == x}
* <li>{@code floorDiv(x, y) * y + floorMod(x, y) == x}</li>
* </ul>
* <p>
* See {@link Math#floorMod(int, int) Math.floorMod} for examples and
Expand All @@ -1150,14 +1151,14 @@ public static int floorMod(int x, int y) {
/**
* Returns the floor modulus of the {@code long} and {@code int} arguments.
* <p>
* 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)}.
*
* <p>
* The relationship between {@code floorDiv} and {@code floorMod} is such that:
* <ul>
* <li>{@code floorDiv(x, y) * y + floorMod(x, y) == x}
* <li>{@code floorDiv(x, y) * y + floorMod(x, y) == x}</li>
* </ul>
* <p>
* See {@link Math#floorMod(int, int) Math.floorMod} for examples and
Expand All @@ -1178,13 +1179,14 @@ public static int floorMod(long x, int 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
* 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)}.
*
* <p>
* The relationship between {@code floorDiv} and {@code floorMod} is such that:
* <ul>
* <li>{@code floorDiv(x, y) * y + floorMod(x, y) == x}
* <li>{@code floorDiv(x, y) * y + floorMod(x, y) == x}</li>
* </ul>
* <p>
* See {@link Math#floorMod(int, int) Math.floorMod} for examples and
Expand Down

1 comment on commit 9f1edaf

@openjdk-notifier
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review

Issues

Please sign in to comment.