JDK 11 RFR of JDK-8202563: BigInteger/BigDecimal not immune to overflow, contrary to spec

[Martin Buchholz]

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.darcy at 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).
>   *
>
>
>