jdk-sandbox: comparison src/java.base/share/classes/java/util/random/RandomGenerator.java

equal deleted inserted replaced

-:7e791393cc4d
+:1b314be4feb2
 import java.util.stream.LongStream;
 import java.util.stream.Stream;
 /**
 * 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
+* generate random or (more typically) pseudorandom sequences of numbers (or Boolean values).
-* sequence may be obtained by either repeatedly invoking a method that returns a single
+* 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>
 * Ideally, given an implicitly or explicitly specified range of values, each value would be chosen
 * independently and uniformly from that range. In practice, one may have to settle for some
 * stream of 100 {@code int} values.  These are not necessarily the exact same values that would
 * have been returned if instead {@code r.nextInt()} had been called 100 times; all that is
 * 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
+* Every object that implements the {@link RandomNumberGenerator} interface by using a
-* amount of state.  Using such an object to generate a pseudorandomly chosen value alters its
+* pseudorandom algorithm is assumed to contain a finite amount of state.  Using such an object to
-* state.  The number of distinct possible states of such an object is called its
+* generate a pseudorandomly chosen value alters its state by computing a new state as a function
-* <i>period</i>.  (Some implementations of the {@link RandomGenerator} interface
+* of the current state, without reference to any information other than the current state.
-* may be truly random rather than pseudorandom, for example relying on the statistical behavior of
+* The number of distinct possible states of such an object is called its <i>period</i>.
-* a physical object to derive chosen values.  Such implementations do not have a fixed period.)
+* (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
 * (preferably) pseudorandom number generators that implement the {@link SplittableGenerator} or
 * {@link JumpableGenerator} interface.
 * <p>
 * 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
+* underlying algorithm is {@code int}-based). Moreover, it may be preferable instead to implement
-* another interface such as {@link JumpableGenerator} or {@link LeapableGenerator}, or to extend an
+* a more specialized interface such as {@link JumpableGenerator} or {@link LeapableGenerator},
-* abstract class such as {@link AbstractSplittableGenerator} or {@link
+* or to extend an abstract implementation-support class such as {@link AbstractSplittableGenerator}
-* AbstractArbitrarilyJumpableGenerator}.
+* 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
 * pseudorandom number generator for use by security-sensitive applications.  Note, however, that
 * {@code java.security.SecureRandom} does implement the {@link RandomGenerator} interface, so that
 * @since 14
 */
 public interface RandomGenerator {
 /**
-* Supported randpm number Algorithms.
+* Supported random number Algorithms.
 */
 public enum Algorithm {
 /**
 * L32X64MixRandom algorithm
 */
 L32X64MixRandom("L32X64MixRandom"),
 /**
+* L64X128MixRandom algorithm
+*/
+L64X128MixRandom("L64X128MixRandom"),
+/**
+* L64X128StarStarRandom algorithm
+*/
+L64X128StarStarRandom("L64X128StarStarRandom"),
+/**
+* L64X128PlusPlusRandom algorithm
+*/
+L64X128PlusPlusRandom("L64X128PlusPlusRandom"),
+/**
+* L64X256MixRandom algorithm
+*/
+L64X256MixRandom("L64X256MixRandom"),
+/**
 * L64X1024MixRandom algorithm
 */
 L64X1024MixRandom("L64X1024MixRandom"),
 /**
-* L64X1024Random algorithm
+* L128X128MixRandom algorithm
 */
-L64X1024Random("L64X1024Random"),
+L128X128MixRandom("L128X128MixRandom"),
 /**
-* L64X128MixRandom algorithm
+* L128X128StarStarRandom algorithm
 */
-L64X128MixRandom("L64X128MixRandom"),
+L128X128StarStarRandom("L128X128StarStarRandom"),
 /**
-* L64X128Random algorithm
+* L128X128PlusPlusRandom algorithm
 */
-L64X128Random("L64X128Random"),
+L128X128PlusPlusRandom("L128X128PlusPlusRandom"),
-/**
-* L64X256MixRandom algorithm
-*/
-L64X256MixRandom("L64X256MixRandom"),
-/**
-* L64X256Random algorithm
-*/
-L64X256Random("L64X256Random"),
 /**
 * L128X256MixRandom algorithm
 */
 L128X256MixRandom("L128X256MixRandom"),
+/**
+* L128X1024MixRandom algorithm
+*/
+L128X1024MixRandom("L128X1024MixRandom"),
 /**
 * MRG32k3a algorithm
 */
 MRG32k3a("MRG32k3a"),
 /**
 * Legacy SecureRandom algorithm
 */
 @Deprecated
 SecureRandom("SecureRandom"),
 /**
-* Xoroshiro128Plus algorithm
+* Xoroshiro128PlusPlus algorithm
 */
-Xoroshiro128Plus("Xoroshiro128Plus"),
+Xoroshiro128PlusPlus("Xoroshiro128PlusPlus"),
 /**
 * Xoroshiro128StarStar algorithm
 */
 Xoroshiro128StarStar("Xoroshiro128StarStar"),
 /**
 *
 * @implNote It is permitted to implement this method in a manner
 * 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();
 }
 * @param randomNumberBound the upper bound (exclusive) for each value produced
 *
 * @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
+* @implNote It is permitted to implement this method in a manner equivalent to
-*           equivalent to
 *           {@code doubles(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound)}.
 * @implNote The default implementation produces a sequential stream that repeatedly
 *           calls {@code nextDouble(randomNumberOrigin, randomNumberBound)}.
 */
 default DoubleStream doubles(double randomNumberOrigin, double randomNumberBound) {
 * @param randomNumberBound the upper bound (exclusive) for each value produced
 *
 * @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
+* @throws IllegalArgumentException if {@code streamSize} is less than zero,
-*         less than zero, or {@code randomNumberOrigin}
+*         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
+* @implNote The default implementation produces a sequential stream that repeatedly
-* that repeatedly calls {@code nextDouble(randomNumberOrigin, randomNumberBound)}.
+*           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);
 }
 * {@code int} values.
 *
 * @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();
 }
 *
 * @implNote The default implementation produces a sequential stream that repeatedly
 *           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);
 }
 *         the specified origin (inclusive) and the specified bound (exclusive)
 *
 * @throws IllegalArgumentException if {@code randomNumberOrigin}
 *         is greater than or equal to {@code randomNumberBound}
 *
-* @implNote It is permitted to implement this method in a manner
+* @implNote It is permitted to implement this method in a manner equivalent to
-*           equivalent to {@code longs(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound)}.
+*           {@code longs(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound)}.
 * @implNote The default implementation produces a sequential stream that repeatedly
 *           calls {@code nextLong(randomNumberOrigin, randomNumberBound)}.
 */
 default LongStream longs(long randomNumberOrigin, long randomNumberBound) {
 RandomSupport.checkRange(randomNumberOrigin, randomNumberBound);
 *
 * @implNote The default implementation produces a sequential stream that repeatedly
 *            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);
 }
 /**
 * Returns a pseudorandomly chosen {@code boolean} value.
 * <p>
-* The default implementation tests the high-order bit (sign bit) of a value produced by {@code
+* The default implementation tests the high-order bit (sign bit) of a value produced by
-* nextInt()}, on the grounds that some algorithms for pseudorandom number generation produce
+* {@code nextInt()}, on the grounds that some algorithms for pseudorandom number generation
-* values whose high-order bits have better statistical quality than the low-order bits.
+* produce values whose high-order bits have better statistical quality than the low-order bits.
 *
 * @return a pseudorandomly chosen {@code boolean} value
 */
 default boolean nextBoolean() {
 return nextInt() < 0;
 *
 * @return a pseudorandomly chosen {@code float} value between
 *         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.checkBound(bound)} and then
-*     {@code RandomSupport.boundedNextFloat(this, bound)}.
+*           {@code RandomSupport.boundedNextFloat(this, bound)}.
 */
 default float nextFloat(float bound) {
 RandomSupport.checkBound(bound);
 return RandomSupport.boundedNextFloat(this, bound);
 }
 * @param bound the upper bound (exclusive)
 *
 * @return a pseudorandomly chosen {@code float} value between the
 *         origin (inclusive) and the bound (exclusive)
 *
-* @throws IllegalArgumentException unless {@code origin} is finite,
+* @throws IllegalArgumentException if {@code origin} is not finite,
-*         {@code bound} is finite, and {@code origin} is less than
+*         or {@code bound} is not finite, or {@code origin}
-*         {@code bound}
+*         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);
 return RandomSupport.boundedNextFloat(this, origin, bound);
 }
 *
 * @return a pseudorandomly chosen {@code double} value between
 *         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.boundedNextDouble(this, bound)}.
 */
 * @param bound the upper bound (exclusive) for the returned value
 *
 * @return a pseudorandomly chosen {@code double} value between the
 *         origin (inclusive) and the bound (exclusive)
 *
-* @throws IllegalArgumentException unless {@code origin} is finite,
+* @throws IllegalArgumentException if {@code origin} is not finite,
-*         {@code bound} is finite, and {@code origin} is less than
+*         or {@code bound} is not finite, or {@code origin}
-*         {@code bound}
+*         is greater than or equal to {@code bound}
 *
 * @implNote The default implementation simply calls
 *           {@code RandomSupport.checkRange(origin, bound)} and then
 *           {@code RandomSupport.boundedNextDouble(this, origin, bound)}.
 */

branch	JDK-8193209-branch
changeset 59080	1b314be4feb2
parent 57940	7e791393cc4d