--- a/src/java.base/share/classes/java/util/random/RandomGenerator.java Thu Aug 29 11:33:26 2019 -0300
+++ b/src/java.base/share/classes/java/util/random/RandomGenerator.java Thu Nov 14 08:54:56 2019 -0400
@@ -34,8 +34,8 @@
/**
* The {@link RandomGenerator} interface is designed to provide a common protocol for objects that
- * generate random or (more typically) pseudorandom sequences of numbers (or Boolean values). Such a
- * sequence may be obtained by either repeatedly invoking a method that returns a single
+ * generate random or (more typically) pseudorandom sequences of numbers (or Boolean values).
+ * Such a sequence may be obtained by either repeatedly invoking a method that returns a single
* (pseudo)randomly chosen value, or by invoking a method that returns a stream of (pseudo)randomly
* chosen values.
* <p>
@@ -59,12 +59,14 @@
* guaranteed is that each value in the stream is chosen in a similar (pseudo)random manner from the
* same range.
* <p>
- * Every object that implements the {@link RandomGenerator} interface is assumed to contain a finite
- * amount of state. Using such an object to generate a pseudorandomly chosen value alters its
- * state. The number of distinct possible states of such an object is called its
- * <i>period</i>. (Some implementations of the {@link RandomGenerator} interface
- * may be truly random rather than pseudorandom, for example relying on the statistical behavior of
- * a physical object to derive chosen values. Such implementations do not have a fixed period.)
+ * Every object that implements the {@link RandomNumberGenerator} interface by using a
+ * pseudorandom algorithm is assumed to contain a finite amount of state. Using such an object to
+ * generate a pseudorandomly chosen value alters its state by computing a new state as a function
+ * of the current state, without reference to any information other than the current state.
+ * The number of distinct possible states of such an object is called its <i>period</i>.
+ * (Some implementations of the {@link RandomNumberGenerator} interface may be truly random
+ * rather than pseudorandom, for example relying on the statistical behavior of a physical
+ * object to derive chosen values. Such implementations do not have a fixed period.)
* <p>
* As a rule, objects that implement the {@link RandomGenerator} interface need not be thread-safe.
* It is recommended that multithreaded applications use either {@link ThreadLocalRandom} or
@@ -74,10 +76,10 @@
* To implement this interface, a class only needs to provide concrete definitions for the methods
* {@code nextLong()} and {@code period()}. Default implementations are provided for all other
* methods (but it may be desirable to override some of them, especially {@code nextInt()} if the
- * underlying algorithm is {@code int}-based). Moerover, it may be preferable instead to implement
- * another interface such as {@link JumpableGenerator} or {@link LeapableGenerator}, or to extend an
- * abstract class such as {@link AbstractSplittableGenerator} or {@link
- * AbstractArbitrarilyJumpableGenerator}.
+ * underlying algorithm is {@code int}-based). Moreover, it may be preferable instead to implement
+ * a more specialized interface such as {@link JumpableGenerator} or {@link LeapableGenerator},
+ * or to extend an abstract implementation-support class such as {@link AbstractSplittableGenerator}
+ * or {@link AbstractArbitrarilyJumpableGenerator}.
* <p>
* Objects that implement {@link RandomGenerator} are typically not cryptographically secure.
* Consider instead using {@link java.security.SecureRandom} to get a cryptographically secure
@@ -91,7 +93,7 @@
public interface RandomGenerator {
/**
- * Supported randpm number Algorithms.
+ * Supported random number Algorithms.
*/
public enum Algorithm {
/**
@@ -99,34 +101,46 @@
*/
L32X64MixRandom("L32X64MixRandom"),
/**
- * L64X1024MixRandom algorithm
- */
- L64X1024MixRandom("L64X1024MixRandom"),
- /**
- * L64X1024Random algorithm
- */
- L64X1024Random("L64X1024Random"),
- /**
* L64X128MixRandom algorithm
*/
L64X128MixRandom("L64X128MixRandom"),
/**
- * L64X128Random algorithm
+ * L64X128StarStarRandom algorithm
*/
- L64X128Random("L64X128Random"),
+ L64X128StarStarRandom("L64X128StarStarRandom"),
+ /**
+ * L64X128PlusPlusRandom algorithm
+ */
+ L64X128PlusPlusRandom("L64X128PlusPlusRandom"),
/**
* L64X256MixRandom algorithm
*/
L64X256MixRandom("L64X256MixRandom"),
/**
- * L64X256Random algorithm
+ * L64X1024MixRandom algorithm
+ */
+ L64X1024MixRandom("L64X1024MixRandom"),
+ /**
+ * L128X128MixRandom algorithm
*/
- L64X256Random("L64X256Random"),
+ L128X128MixRandom("L128X128MixRandom"),
+ /**
+ * L128X128StarStarRandom algorithm
+ */
+ L128X128StarStarRandom("L128X128StarStarRandom"),
+ /**
+ * L128X128PlusPlusRandom algorithm
+ */
+ L128X128PlusPlusRandom("L128X128PlusPlusRandom"),
/**
* L128X256MixRandom algorithm
*/
L128X256MixRandom("L128X256MixRandom"),
/**
+ * L128X1024MixRandom algorithm
+ */
+ L128X1024MixRandom("L128X1024MixRandom"),
+ /**
* MRG32k3a algorithm
*/
MRG32k3a("MRG32k3a"),
@@ -141,9 +155,9 @@
@Deprecated
SecureRandom("SecureRandom"),
/**
- * Xoroshiro128Plus algorithm
+ * Xoroshiro128PlusPlus algorithm
*/
- Xoroshiro128Plus("Xoroshiro128Plus"),
+ Xoroshiro128PlusPlus("Xoroshiro128PlusPlus"),
/**
* Xoroshiro128StarStar algorithm
*/
@@ -245,7 +259,7 @@
* equivalent to {@code doubles(Long.MAX_VALUE)}.
*
* @implNote The default implementation produces a sequential stream
- * that repeatedly calls {@code nextDouble()}.
+ * that repeatedly calls {@code nextDouble()}.
*/
default DoubleStream doubles() {
return DoubleStream.generate(this::nextDouble).sequential();
@@ -262,11 +276,11 @@
* @return a stream of pseudorandomly chosen {@code double} values, each between
* the specified origin (inclusive) and the specified bound (exclusive)
*
- * @throws IllegalArgumentException if {@code randomNumberOrigin}
+ * @throws IllegalArgumentException if {@code randomNumberOrigin} is not finite,
+ * or {@code randomNumberBound} is not finite, or {@code randomNumberOrigin}
* is greater than or equal to {@code randomNumberBound}
*
- * @implNote It is permitted to implement this method in a manner
- * equivalent to
+ * @implNote It is permitted to implement this method in a manner equivalent to
* {@code doubles(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound)}.
* @implNote The default implementation produces a sequential stream that repeatedly
* calls {@code nextDouble(randomNumberOrigin, randomNumberBound)}.
@@ -307,15 +321,16 @@
* @return a stream of pseudorandomly chosen {@code double} values, each between
* the specified origin (inclusive) and the specified bound (exclusive)
*
- * @throws IllegalArgumentException if {@code streamSize} is
- * less than zero, or {@code randomNumberOrigin}
+ * @throws IllegalArgumentException if {@code streamSize} is less than zero,
+ * or {@code randomNumberOrigin} is not finite,
+ * or {@code randomNumberBound} is not finite, or {@code randomNumberOrigin}
* is greater than or equal to {@code randomNumberBound}
*
- * @implNote The default implementation produces a sequential stream
- * that repeatedly calls {@code nextDouble(randomNumberOrigin, randomNumberBound)}.
+ * @implNote The default implementation produces a sequential stream that repeatedly
+ * calls {@code nextDouble(randomNumberOrigin, randomNumberBound)}.
*/
default DoubleStream doubles(long streamSize, double randomNumberOrigin,
- double randomNumberBound) {
+ double randomNumberBound) {
RandomSupport.checkStreamSize(streamSize);
RandomSupport.checkRange(randomNumberOrigin, randomNumberBound);
return doubles(randomNumberOrigin, randomNumberBound).limit(streamSize);
@@ -328,9 +343,9 @@
* @return a stream of pseudorandomly chosen {@code int} values
*
* @implNote It is permitted to implement this method in a manner
- * equivalent to {@code ints(Long.MAX_VALUE)}.
+ * equivalent to {@code ints(Long.MAX_VALUE)}.
* @implNote The default implementation produces a sequential stream
- * that repeatedly calls {@code nextInt()}.
+ * that repeatedly calls {@code nextInt()}.
*/
default IntStream ints() {
return IntStream.generate(this::nextInt).sequential();
@@ -399,7 +414,7 @@
* calls {@code nextInt(randomNumberOrigin, randomNumberBound)}.
*/
default IntStream ints(long streamSize, int randomNumberOrigin,
- int randomNumberBound) {
+ int randomNumberBound) {
RandomSupport.checkStreamSize(streamSize);
RandomSupport.checkRange(randomNumberOrigin, randomNumberBound);
return ints(randomNumberOrigin, randomNumberBound).limit(streamSize);
@@ -434,8 +449,8 @@
* @throws IllegalArgumentException if {@code randomNumberOrigin}
* is greater than or equal to {@code randomNumberBound}
*
- * @implNote It is permitted to implement this method in a manner
- * equivalent to {@code longs(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound)}.
+ * @implNote It is permitted to implement this method in a manner equivalent to
+ * {@code longs(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound)}.
* @implNote The default implementation produces a sequential stream that repeatedly
* calls {@code nextLong(randomNumberOrigin, randomNumberBound)}.
*/
@@ -483,7 +498,7 @@
* calls {@code nextLong(randomNumberOrigin, randomNumberBound)}.
*/
default LongStream longs(long streamSize, long randomNumberOrigin,
- long randomNumberBound) {
+ long randomNumberBound) {
RandomSupport.checkStreamSize(streamSize);
RandomSupport.checkRange(randomNumberOrigin, randomNumberBound);
return longs(randomNumberOrigin, randomNumberBound).limit(streamSize);
@@ -492,9 +507,9 @@
/**
* Returns a pseudorandomly chosen {@code boolean} value.
* <p>
- * The default implementation tests the high-order bit (sign bit) of a value produced by {@code
- * nextInt()}, on the grounds that some algorithms for pseudorandom number generation produce
- * values whose high-order bits have better statistical quality than the low-order bits.
+ * The default implementation tests the high-order bit (sign bit) of a value produced by
+ * {@code nextInt()}, on the grounds that some algorithms for pseudorandom number generation
+ * produce values whose high-order bits have better statistical quality than the low-order bits.
*
* @return a pseudorandomly chosen {@code boolean} value
*/
@@ -524,11 +539,11 @@
* zero (inclusive) and the bound (exclusive)
*
* @throws IllegalArgumentException if {@code bound} is not
- * positive and finite
+ * both positive and finite
*
* @implNote The default implementation simply calls
- * {@code RandomSupport.checkBound(bound)} and then
- * {@code RandomSupport.boundedNextFloat(this, bound)}.
+ * {@code RandomSupport.checkBound(bound)} and then
+ * {@code RandomSupport.boundedNextFloat(this, bound)}.
*/
default float nextFloat(float bound) {
RandomSupport.checkBound(bound);
@@ -545,13 +560,13 @@
* @return a pseudorandomly chosen {@code float} value between the
* origin (inclusive) and the bound (exclusive)
*
- * @throws IllegalArgumentException unless {@code origin} is finite,
- * {@code bound} is finite, and {@code origin} is less than
- * {@code bound}
+ * @throws IllegalArgumentException if {@code origin} is not finite,
+ * or {@code bound} is not finite, or {@code origin}
+ * is greater than or equal to {@code bound}
*
* @implNote The default implementation simply calls
* {@code RandomSupport.checkRange(origin, bound)} and then
- * {@code RandomSupport.boundedNextFloat(this, origin, bound)}.
+ * {@code RandomSupport.boundedNextFloat(this, origin, bound)}.
*/
default float nextFloat(float origin, float bound) {
RandomSupport.checkRange(origin, bound);
@@ -580,7 +595,7 @@
* zero (inclusive) and the bound (exclusive)
*
* @throws IllegalArgumentException if {@code bound} is not
- * positive and finite
+ * both positive and finite
*
* @implNote The default implementation simply calls
* {@code RandomSupport.checkBound(bound)} and then
@@ -601,9 +616,9 @@
* @return a pseudorandomly chosen {@code double} value between the
* origin (inclusive) and the bound (exclusive)
*
- * @throws IllegalArgumentException unless {@code origin} is finite,
- * {@code bound} is finite, and {@code origin} is less than
- * {@code bound}
+ * @throws IllegalArgumentException if {@code origin} is not finite,
+ * or {@code bound} is not finite, or {@code origin}
+ * is greater than or equal to {@code bound}
*
* @implNote The default implementation simply calls
* {@code RandomSupport.checkRange(origin, bound)} and then