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.
On Mon, May 7, 2018 at 9:47 PM, joe darcy <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/
> CSR: 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).
> *
>
>
>
