On 5/7/2018 10:45 PM, Martin Buchholz wrote:
Thanks for doing this - wordsmithing is hard.
Maybe
The unsigned
* right shift operator ({@code >>>}) is omitted, as this operation
only makes sense with a fixed word size.
How about
The unsigned right shift operator ({@code >>>}) is omitted since this
operation only makes sense for a fixed sized word and not for a
representation conceptually having an infinite number of leading virtual
sign bits.
-Joe
On Mon, May 7, 2018 at 9:47 PM, joe darcy <joe.da...@oracle.com
<mailto:joe.da...@oracle.com>> wrote:
Hello,
Over in BigInteger, 2^Integer.MAX_VALUE just isn't as effectively
infinite as it used to be. Please review the spec changes and CSR
below to clarify that the range of BigInteger is "arbitrarily
large" but not "infinite":
JDK-8202563: BigInteger/BigDecimal not immune to overflow,
contrary to spec
webrev: http://cr.openjdk.java.net/~darcy/8202563.0/
<http://cr.openjdk.java.net/%7Edarcy/8202563.0/>
CSR: https://bugs.openjdk.java.net/browse/JDK-8202761
<https://bugs.openjdk.java.net/browse/JDK-8202761>
Patch below.
Thanks,
-Joe
--- old/src/java.base/share/classes/java/math/BigInteger.java
2018-05-07 21:39:33.679361845 -0700
+++ new/src/java.base/share/classes/java/math/BigInteger.java
2018-05-07 21:39:33.139361869 -0700
@@ -52,18 +52,15 @@
* and a few other miscellaneous operations.
*
* <p>Semantics of arithmetic operations exactly mimic those of
Java's integer
- * arithmetic operators, as defined in <i>The Java Language
Specification</i>.
+ * arithmetic operators, as defined in <i>The Java™
Language Specification</i>.
* For example, division by zero throws an {@code
ArithmeticException}, and
* division of a negative by a positive yields a negative (or
zero) remainder.
- * All of the details in the Spec concerning overflow are ignored, as
- * BigIntegers are made as large as necessary to accommodate the
results of an
- * operation.
*
* <p>Semantics of shift operations extend those of Java's shift
operators
* to allow for negative shift distances. A right-shift with a
negative
* shift distance results in a left shift, and vice-versa. The
unsigned
* right shift operator ({@code >>>}) is omitted, as this
operation makes
- * little sense in combination with the "infinite word size"
abstraction
+ * little sense in combination with the arbitrarily large abstraction
* provided by this class.
*
* <p>Semantics of bitwise logical operations exactly mimic those
of Java's
@@ -84,8 +81,8 @@
* extended so that it contains the designated bit. None of the
single-bit
* operations can produce a BigInteger with a different sign from the
* BigInteger being operated on, as they affect only a single
bit, and the
- * "infinite word size" abstraction provided by this class
ensures that there
- * are infinitely many "virtual sign bits" preceding each BigInteger.
+ * arbitrarily large abstraction provided by this class ensures
that conceptually
+ * there are infinitely many "virtual sign bits" preceding each
BigInteger.
*
* <p>For the sake of brevity and clarity, pseudo-code is used
throughout the
* descriptions of BigInteger methods. The pseudo-code expression
@@ -105,13 +102,18 @@
* +2<sup>{@code Integer.MAX_VALUE}</sup> (exclusive)
* and may support values outside of that range.
*
+ * An {@code ArithmeticException} is thrown when a BigInteger
+ * constructor or method would generate a value outside of the
+ * supported range.
+ *
* The range of probable prime values is limited and may be less than
* the full supported positive range of {@code BigInteger}.
* The range must be at least 1 to 2<sup>500000000</sup>.
*
* @implNote
- * BigInteger constructors and operations throw {@code
ArithmeticException} when
- * the result is out of the supported range of
+ * In the reference implementation, BigInteger constructors and
+ * operations throw {@code ArithmeticException} when the result
is out
+ * of the supported range of
* -2<sup>{@code Integer.MAX_VALUE}</sup> (exclusive) to
* +2<sup>{@code Integer.MAX_VALUE}</sup> (exclusive).
*
