JDK 17 java.base.jmod - Base Module
JDK 17 java.base.jmod is the JMOD file for JDK 17 Base module.
JDK 17 Base module compiled class files are stored in \fyicenter\jdk-17.0.5\jmods\java.base.jmod.
JDK 17 Base module compiled class files are also linked and stored in the \fyicenter\jdk-17.0.5\lib\modules JImage file.
JDK 17 Base module source code files are stored in \fyicenter\jdk-17.0.5\lib\src.zip\java.base.
You can click and view the content of each source code file in the list below.
✍: FYIcenter
⏎ java/util/random/RandomGenerator.java
/*
* Copyright (c) 2021, Oracle and/or its affiliates. All rights reserved.
* ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*/
package java.util.random;
import java.math.BigInteger;
import java.security.SecureRandom;
import java.util.Objects;
import java.util.concurrent.ThreadLocalRandom;
import jdk.internal.util.random.RandomSupport;
import jdk.internal.util.random.RandomSupport.*;
import java.util.stream.DoubleStream;
import java.util.stream.IntStream;
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 sequence may be obtained by
* either repeatedly invoking a method that returns a single pseudorandomly
* chosen value, or by invoking a method that returns a stream of
* pseudorandomly 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 approximation to independence and
* uniformity.
*
* <p> In the case of {@code int}, {@code long}, and {@code boolean} values, if
* there is no explicit specification of range, then the range includes all
* possible values of the type. In the case of {@code float} and {@code double}
* values, first a value is always chosen uniformly from the set of
* 2<sup><i>w</i></sup> values between 0.0 (inclusive) and 1.0 (exclusive),
* where <i>w</i> is 23 for {@code float} values and 52 for {@code double}
* values, such that adjacent values differ by 2<sup>−<i>w</i></sup>
* (notice that this set is a <i>subset</i> of the set of
* <i>all representable floating-point values</i> between 0.0 (inclusive) and 1.0 (exclusive));
* then if an explicit range was specified, then the chosen number is
* computationally scaled and translated so as to appear to have been chosen
* approximately uniformly from that explicit range.
*
* <p> Each method that returns a stream produces a stream of values each of
* which is chosen in the same manner as for a method that returns a single
* pseudorandomly chosen value. For example, if {@code r} implements
* {@link RandomGenerator}, then the method call {@code r.ints(100)} returns a
* 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 pseudorandom manner from the same range.
*
* <p> Every object that implements the {@link RandomGenerator} 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 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.)
*
* <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> Objects that implement {@link RandomGenerator} are typically not
* cryptographically secure. Consider instead using {@link SecureRandom} to get
* a cryptographically secure pseudorandom number generator for use by
* security-sensitive applications. Note, however, that {@link SecureRandom}
* does implement the {@link RandomGenerator} interface, so that instances of
* {@link SecureRandom} may be used interchangeably with other types of
* pseudorandom generators in applications that do not require a secure
* generator.
*
* <p>Unless explicit stated otherwise, the use of null for any method argument
* will cause a NullPointerException.
*
* @since 17
*
*/
public interface RandomGenerator {
/**
* Returns an instance of {@link RandomGenerator} that utilizes the
* {@code name} <a href="package-summary.html#algorithms">algorithm</a>.
*
* @param name Name of random number generator
* <a href="package-summary.html#algorithms">algorithm</a>
*
* @return An instance of {@link RandomGenerator}
*
* @throws NullPointerException if name is null
* @throws IllegalArgumentException if the named algorithm is not found
*/
static RandomGenerator of(String name) {
Objects.requireNonNull(name);
return RandomGeneratorFactory.of(name, RandomGenerator.class);
}
/**
* Returns a {@link RandomGenerator} meeting the minimal requirement
* of having an <a href="package-summary.html#algorithms">algorithm</a>
* whose state bits are greater than or equal 64.
*
* @implSpec Since algorithms will improve over time, there is no
* guarantee that this method will return the same algorithm over time.
* <p> The default implementation selects L32X64MixRandom.
*
* @return a {@link RandomGenerator}
*/
static RandomGenerator getDefault() {
return of("L32X64MixRandom");
}
/**
* Return true if the implementation of RandomGenerator (algorithm) has been
* marked for deprecation.
*
* @implNote Random number generator algorithms evolve over time; new
* algorithms will be introduced and old algorithms will
* lose standing. If an older algorithm is deemed unsuitable
* for continued use, it will be marked as deprecated to indicate
* that it may be removed at some point in the future.
*
* @return true if the implementation of RandomGenerator (algorithm) has been
* marked for deprecation
*
* @implSpec The default implementation checks for the @Deprecated annotation.
*/
default boolean isDeprecated() {
return this.getClass().isAnnotationPresent(Deprecated.class);
}
/**
* Returns an effectively unlimited stream of pseudorandomly chosen
* {@code double} values.
*
* @return a stream of pseudorandomly chosen {@code double} values
*
* @implNote It is permitted to implement this method in a manner equivalent to
* {@link RandomGenerator#doubles(long) doubles}
* ({@link Long#MAX_VALUE Long.MAX_VALUE}).
*
* @implSpec The default implementation produces a sequential stream
* that repeatedly calls {@link RandomGenerator#nextDouble nextDouble}().
*/
default DoubleStream doubles() {
return DoubleStream.generate(this::nextDouble).sequential();
}
/**
* Returns an effectively unlimited stream of pseudorandomly chosen
* {@code double} values, where each value is between the specified origin
* (inclusive) and the specified bound (exclusive).
*
* @param randomNumberOrigin the least value that can be produced
* @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} 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
* {@link RandomGenerator#doubles(long, double, double) doubles}
* ({@link Long#MAX_VALUE Long.MAX_VALUE}, randomNumberOrigin, randomNumberBound).
*
* @implSpec The default implementation produces a sequential stream that repeatedly
* calls {@link RandomGenerator#nextDouble(double, double) nextDouble}(randomNumberOrigin, randomNumberBound).
*/
default DoubleStream doubles(double randomNumberOrigin, double randomNumberBound) {
RandomSupport.checkRange(randomNumberOrigin, randomNumberBound);
return DoubleStream.generate(() -> nextDouble(randomNumberOrigin, randomNumberBound)).sequential();
}
/**
* Returns a stream producing the given {@code streamSize} number of
* pseudorandomly chosen {@code double} values.
*
* @param streamSize the number of values to generate
*
* @return a stream of pseudorandomly chosen {@code double} values
*
* @throws IllegalArgumentException if {@code streamSize} is
* less than zero
*
* @implSpec The default implementation produces a sequential stream
* that repeatedly calls {@link RandomGenerator#nextDouble nextDouble()}.
*/
default DoubleStream doubles(long streamSize) {
RandomSupport.checkStreamSize(streamSize);
return doubles().limit(streamSize);
}
/**
* Returns a stream producing the given {@code streamSize} number of
* pseudorandomly chosen {@code double} values, where each value is
* between the specified origin (inclusive) and the specified bound
* (exclusive).
*
* @param streamSize the number of values to generate
* @param randomNumberOrigin the least value that can be produced
* @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 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}
*
* @implSpec The default implementation produces a sequential stream that repeatedly
* calls {@link RandomGenerator#nextDouble(double, double) nextDouble}(randomNumberOrigin, randomNumberBound).
*/
default DoubleStream doubles(long streamSize, double randomNumberOrigin,
double randomNumberBound) {
RandomSupport.checkStreamSize(streamSize);
RandomSupport.checkRange(randomNumberOrigin, randomNumberBound);
return doubles(randomNumberOrigin, randomNumberBound).limit(streamSize);
}
/**
* Returns an effectively unlimited stream of pseudorandomly chosen
* {@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 {@link RandomGenerator#ints(long) ints}
* ({@link Long#MAX_VALUE Long.MAX_VALUE}).
*
* @implSpec The default implementation produces a sequential stream
* that repeatedly calls {@link RandomGenerator#nextInt() nextInt}().
*/
default IntStream ints() {
return IntStream.generate(this::nextInt).sequential();
}
/**
* Returns an effectively unlimited stream of pseudorandomly chosen
* {@code int} values, where each value is between the specified origin
* (inclusive) and the specified bound (exclusive).
*
* @param randomNumberOrigin the least value that can be produced
* @param randomNumberBound the upper bound (exclusive) for each value produced
*
* @return a stream of pseudorandomly chosen {@code int} values, each between
* 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 equivalent to
* {@link RandomGenerator#ints(long, int, int) ints}
* ({@link Long#MAX_VALUE Long.MAX_VALUE}, randomNumberOrigin, randomNumberBound).
*
* @implSpec The default implementation produces a sequential stream that repeatedly
* calls {@link RandomGenerator#nextInt(int, int) nextInt}(randomNumberOrigin, randomNumberBound).
*/
default IntStream ints(int randomNumberOrigin, int randomNumberBound) {
RandomSupport.checkRange(randomNumberOrigin, randomNumberBound);
return IntStream.generate(() -> nextInt(randomNumberOrigin, randomNumberBound)).sequential();
}
/**
* Returns a stream producing the given {@code streamSize} number of
* pseudorandomly chosen {@code int} values.
*
* @param streamSize the number of values to generate
*
* @return a stream of pseudorandomly chosen {@code int} values
*
* @throws IllegalArgumentException if {@code streamSize} is
* less than zero
*
* @implSpec The default implementation produces a sequential stream
* that repeatedly calls {@link RandomGenerator#nextInt() nextInt}().
*/
default IntStream ints(long streamSize) {
RandomSupport.checkStreamSize(streamSize);
return ints().limit(streamSize);
}
/**
* Returns a stream producing the given {@code streamSize} number of
* pseudorandomly chosen {@code int} values, where each value is between
* the specified origin (inclusive) and the specified bound (exclusive).
*
* @param streamSize the number of values to generate
* @param randomNumberOrigin the least value that can be produced
* @param randomNumberBound the upper bound (exclusive) for each value produced
*
* @return a stream of pseudorandomly chosen {@code int} values, each between
* the specified origin (inclusive) and the specified bound (exclusive)
*
* @throws IllegalArgumentException if {@code streamSize} is
* less than zero, or {@code randomNumberOrigin}
* is greater than or equal to {@code randomNumberBound}
*
* @implSpec The default implementation produces a sequential stream that repeatedly
* calls {@link RandomGenerator#nextInt(int, int) nextInt}(randomNumberOrigin, randomNumberBound).
*/
default IntStream ints(long streamSize, int randomNumberOrigin,
int randomNumberBound) {
RandomSupport.checkStreamSize(streamSize);
RandomSupport.checkRange(randomNumberOrigin, randomNumberBound);
return ints(randomNumberOrigin, randomNumberBound).limit(streamSize);
}
/**
* Returns an effectively unlimited stream of pseudorandomly chosen
* {@code long} values.
*
* @return a stream of pseudorandomly chosen {@code long} values
*
* @implNote It is permitted to implement this method in a manner
* equivalent to {@link RandomGenerator#longs(long) longs}
* ({@link Long#MAX_VALUE Long.MAX_VALUE}).
*
* @implSpec The default implementation produces a sequential stream
* that repeatedly calls {@link RandomGenerator#nextLong() nextLong}().
*/
default LongStream longs() {
return LongStream.generate(this::nextLong).sequential();
}
/**
* Returns an effectively unlimited stream of pseudorandomly chosen
* {@code long} values, where each value is between the specified origin
* (inclusive) and the specified bound (exclusive).
*
* @param randomNumberOrigin the least value that can be produced
* @param randomNumberBound the upper bound (exclusive) for each value produced
*
* @return a stream of pseudorandomly chosen {@code long} values, each between
* 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 equivalent to
* {@link RandomGenerator#longs(long, long, long) longs}
* ({@link Long#MAX_VALUE Long.MAX_VALUE}, randomNumberOrigin, randomNumberBound).
*
* @implSpec The default implementation produces a sequential stream that repeatedly
* calls {@link RandomGenerator#nextLong(long, long) nextLong}(randomNumberOrigin, randomNumberBound).
*/
default LongStream longs(long randomNumberOrigin, long randomNumberBound) {
RandomSupport.checkRange(randomNumberOrigin, randomNumberBound);
return LongStream.generate(() -> nextLong(randomNumberOrigin, randomNumberBound)).sequential();
}
/**
* Returns a stream producing the given {@code streamSize} number of
* pseudorandomly chosen {@code long} values.
*
* @param streamSize the number of values to generate
*
* @return a stream of pseudorandomly chosen {@code long} values
*
* @throws IllegalArgumentException if {@code streamSize} is
* less than zero
*
* @implSpec The default implementation produces a sequential stream
* that repeatedly calls {@link RandomGenerator#nextLong() nextLong}().
*/
default LongStream longs(long streamSize) {
RandomSupport.checkStreamSize(streamSize);
return longs().limit(streamSize);
}
/**
* Returns a stream producing the given {@code streamSize} number of
* pseudorandomly chosen {@code long} values, where each value is between
* the specified origin (inclusive) and the specified bound (exclusive).
*
* @param streamSize the number of values to generate
* @param randomNumberOrigin the least value that can be produced
* @param randomNumberBound the upper bound (exclusive) for each value produced
*
* @return a stream of pseudorandomly chosen {@code long} values, each between
* the specified origin (inclusive) and the specified bound (exclusive)
*
* @throws IllegalArgumentException if {@code streamSize} is
* less than zero, or {@code randomNumberOrigin}
* is greater than or equal to {@code randomNumberBound}
*
* @implSpec The default implementation produces a sequential stream that repeatedly
* calls {@link RandomGenerator#nextLong(long, long) nextLong}(randomNumberOrigin, randomNumberBound).
*/
default LongStream longs(long streamSize, long randomNumberOrigin,
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 {@link RandomGenerator#nextInt() 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
*
* @implSpec The default implementation produces a result based on the
* sign bit of a number generated by {@link nextInt()}.
*/
default boolean nextBoolean() {
return nextInt() < 0;
}
/**
* Fills a user-supplied byte array with generated byte values
* pseudorandomly chosen uniformly from the range of values between -128
* (inclusive) and 127 (inclusive).
*
* @implNote Algorithm used to fill the byte array;
* <pre>{@code
* void nextBytes(byte[] bytes) {
* int i = 0;
* int len = bytes.length;
* for (int words = len >> 3; words--> 0; ) {
* long rnd = nextLong();
* for (int n = 8; n--> 0; rnd >>>= Byte.SIZE)
* bytes[i++] = (byte)rnd;
* }
* if (i < len)
* for (long rnd = nextLong(); i < len; rnd >>>= Byte.SIZE)
* bytes[i++] = (byte)rnd;
* }}</pre>
*
* @param bytes the byte array to fill with pseudorandom bytes
* @throws NullPointerException if bytes is null
*
* @implSpec The default implementation produces results from repeated calls
* to {@link nextLong()}.
*/
default void nextBytes(byte[] bytes) {
int i = 0;
int len = bytes.length;
for (int words = len >> 3; words--> 0; ) {
long rnd = nextLong();
for (int n = 8; n--> 0; rnd >>>= Byte.SIZE)
bytes[i++] = (byte)rnd;
}
if (i < len)
for (long rnd = nextLong(); i < len; rnd >>>= Byte.SIZE)
bytes[i++] = (byte)rnd;
}
/**
* Returns a pseudorandom {@code float} value between zero (inclusive) and
* one (exclusive).
*
* @return a pseudorandom {@code float} value between zero (inclusive) and one (exclusive)
*
* @implSpec The default implementation uses the 24 high-order bits from a call to
* {@link RandomGenerator#nextInt() nextInt}().
*/
default float nextFloat() {
return (nextInt() >>> 8) * 0x1.0p-24f;
}
/**
* Returns a pseudorandomly chosen {@code float} value between zero
* (inclusive) and the specified bound (exclusive).
*
* @param bound the upper bound (exclusive) for the returned value.
* Must be positive and finite
*
* @return a pseudorandomly chosen {@code float} value between
* zero (inclusive) and the bound (exclusive)
*
* @throws IllegalArgumentException if {@code bound} is not
* both positive and finite
*
* @implSpec The default implementation checks that {@code bound} is a
* positive finite float. Then invokes {@code nextFloat()}, scaling
* the result so that the final result lies between {@code 0.0f} (inclusive)
* and {@code bound} (exclusive).
*/
default float nextFloat(float bound) {
RandomSupport.checkBound(bound);
return RandomSupport.boundedNextFloat(this, bound);
}
/**
* Returns a pseudorandomly chosen {@code float} value between the
* specified origin (inclusive) and the specified bound (exclusive).
*
* @param origin the least value that can be returned
* @param bound the upper bound (exclusive)
*
* @return a pseudorandomly chosen {@code float} value between the
* origin (inclusive) and the bound (exclusive)
*
* @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}
*
* @implSpec The default implementation checks that {@code origin} and
* {@code bound} are positive finite floats. Then invokes
* {@code nextFloat()}, scaling and translating the result so that the final
* result lies between {@code origin} (inclusive) and {@code bound}
* (exclusive).
*/
default float nextFloat(float origin, float bound) {
RandomSupport.checkRange(origin, bound);
return RandomSupport.boundedNextFloat(this, origin, bound);
}
/**
* Returns a pseudorandom {@code double} value between zero (inclusive) and
* one (exclusive).
*
* @return a pseudorandom {@code double} value between zero (inclusive)
* and one (exclusive)
*
* @implSpec The default implementation uses the 53 high-order bits from a call to
* {@link RandomGenerator#nextLong nextLong}().
*/
default double nextDouble() {
return (nextLong() >>> 11) * 0x1.0p-53;
}
/**
* Returns a pseudorandomly chosen {@code double} value between zero
* (inclusive) and the specified bound (exclusive).
*
* @param bound the upper bound (exclusive) for the returned value.
* Must be positive and finite
*
* @return a pseudorandomly chosen {@code double} value between
* zero (inclusive) and the bound (exclusive)
*
* @throws IllegalArgumentException if {@code bound} is not
* both positive and finite
*
* @implSpec The default implementation checks that {@code bound} is a
* positive finite double. Then invokes {@code nextDouble()}, scaling
* the result so that the final result lies between {@code 0.0} (inclusive)
* and {@code bound} (exclusive).
*/
default double nextDouble(double bound) {
RandomSupport.checkBound(bound);
return RandomSupport.boundedNextDouble(this, bound);
}
/**
* Returns a pseudorandomly chosen {@code double} value between the
* specified origin (inclusive) and the specified bound (exclusive).
*
* @param origin the least value that can be returned
* @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 if {@code origin} is not finite,
* or {@code bound} is not finite, or {@code origin}
* is greater than or equal to {@code bound}
*
* @implSpec The default implementation checks that {@code origin} and
* {@code bound} are positive finite doubles. Then calls
* {@code nextDouble()}, scaling and translating the result so that the final
* result lies between {@code origin} (inclusive) and {@code bound}
* (exclusive).
*/
default double nextDouble(double origin, double bound) {
RandomSupport.checkRange(origin, bound);
return RandomSupport.boundedNextDouble(this, origin, bound);
}
/**
* Returns a pseudorandomly chosen {@code int} value.
*
* @return a pseudorandomly chosen {@code int} value
*
* @implSpec The default implementation uses the 32 high-order bits from a call to
* {@link RandomGenerator#nextLong nextLong}().
*/
default int nextInt() {
return (int)(nextLong() >>> 32);
}
/**
* Returns a pseudorandomly chosen {@code int} value between zero
* (inclusive) and the specified bound (exclusive).
*
* @param bound the upper bound (exclusive) for the returned value.
* Must be positive.
*
* @return a pseudorandomly chosen {@code int} value between
* zero (inclusive) and the bound (exclusive)
*
* @throws IllegalArgumentException if {@code bound} is not positive
*
* @implSpec The default implementation checks that {@code bound} is a
* positive {@code int}. Then invokes {@code nextInt()}, limiting the result
* to be greater than or equal zero and less than {@code bound}. If {@code bound}
* is a power of two then limiting is a simple masking operation. Otherwise,
* the result is re-calculated by invoking {@code nextInt()} until the
* result is greater than or equal zero and less than {@code bound}.
*/
default int nextInt(int bound) {
RandomSupport.checkBound(bound);
return RandomSupport.boundedNextInt(this, bound);
}
/**
* Returns a pseudorandomly chosen {@code int} value between the specified
* origin (inclusive) and the specified bound (exclusive).
*
* @param origin the least value that can be returned
* @param bound the upper bound (exclusive) for the returned value
*
* @return a pseudorandomly chosen {@code int} value between the
* origin (inclusive) and the bound (exclusive)
*
* @throws IllegalArgumentException if {@code origin} is greater than
* or equal to {@code bound}
*
* @implSpec The default implementation checks that {@code origin} and
* {@code bound} are positive {@code ints}. Then invokes {@code nextInt()},
* limiting the result to be greater that or equal {@code origin} and less
* than {@code bound}. If {@code bound} is a power of two then limiting is a
* simple masking operation. Otherwise, the result is re-calculated by
* invoking {@code nextInt()} until the result is greater than or equal
* {@code origin} and less than {@code bound}.
*/
default int nextInt(int origin, int bound) {
RandomSupport.checkRange(origin, bound);
return RandomSupport.boundedNextInt(this, origin, bound);
}
/**
* Returns a pseudorandomly chosen {@code long} value.
*
* @return a pseudorandomly chosen {@code long} value
*/
long nextLong();
/**
* Returns a pseudorandomly chosen {@code long} value between zero
* (inclusive) and the specified bound (exclusive).
*
* @param bound the upper bound (exclusive) for the returned value.
* Must be positive.
*
* @return a pseudorandomly chosen {@code long} value between
* zero (inclusive) and the bound (exclusive)
*
* @throws IllegalArgumentException if {@code bound} is not positive
*
* @implSpec The default implementation checks that {@code bound} is a
* positive {@code long}. Then invokes {@code nextLong()}, limiting the
* result to be greater than or equal zero and less than {@code bound}. If
* {@code bound} is a power of two then limiting is a simple masking
* operation. Otherwise, the result is re-calculated by invoking
* {@code nextLong()} until the result is greater than or equal zero and
* less than {@code bound}.
*/
default long nextLong(long bound) {
RandomSupport.checkBound(bound);
return RandomSupport.boundedNextLong(this, bound);
}
/**
* Returns a pseudorandomly chosen {@code long} value between the
* specified origin (inclusive) and the specified bound (exclusive).
*
* @param origin the least value that can be returned
* @param bound the upper bound (exclusive) for the returned value
*
* @return a pseudorandomly chosen {@code long} value between the
* origin (inclusive) and the bound (exclusive)
*
* @throws IllegalArgumentException if {@code origin} is greater than
* or equal to {@code bound}
*
* @implSpec The default implementation checks that {@code origin} and
* {@code bound} are positive {@code longs}. Then invokes {@code nextLong()},
* limiting the result to be greater than or equal {@code origin} and less
* than {@code bound}. If {@code bound} is a power of two then limiting is a
* simple masking operation. Otherwise, the result is re-calculated by
* invoking {@code nextLong()} until the result is greater than or equal
* {@code origin} and less than {@code bound}.
*/
default long nextLong(long origin, long bound) {
RandomSupport.checkRange(origin, bound);
return RandomSupport.boundedNextLong(this, origin, bound);
}
/**
* Returns a {@code double} value pseudorandomly chosen from a Gaussian
* (normal) distribution whose mean is 0 and whose standard deviation is 1.
*
* @return a {@code double} value pseudorandomly chosen from a
* Gaussian distribution
*
* @implSpec The default implementation uses McFarland's fast modified
* ziggurat algorithm (largely table-driven, with rare cases handled by
* computation and rejection sampling). Walker's alias method for sampling
* a discrete distribution also plays a role.
*/
default double nextGaussian() {
// See Knuth, TAOCP, Vol. 2, 3rd edition, Section 3.4.1 Algorithm C.
return RandomSupport.computeNextGaussian(this);
}
/**
* Returns a {@code double} value pseudorandomly chosen from a Gaussian
* (normal) distribution with a mean and standard deviation specified by the
* arguments.
*
* @param mean the mean of the Gaussian distribution to be drawn from
* @param stddev the standard deviation (square root of the variance)
* of the Gaussian distribution to be drawn from
*
* @return a {@code double} value pseudorandomly chosen from the
* specified Gaussian distribution
*
* @throws IllegalArgumentException if {@code stddev} is negative
*
* @implSpec The default implementation uses McFarland's fast modified
* ziggurat algorithm (largely table-driven, with rare cases handled by
* computation and rejection sampling). Walker's alias method for sampling
* a discrete distribution also plays a role.
*/
default double nextGaussian(double mean, double stddev) {
if (stddev < 0.0) throw new IllegalArgumentException("standard deviation must be non-negative");
return mean + stddev * RandomSupport.computeNextGaussian(this);
}
/**
* Returns a nonnegative {@code double} value pseudorandomly chosen from
* an exponential distribution whose mean is 1.
*
* @return a nonnegative {@code double} value pseudorandomly chosen from an
* exponential distribution
*
* @implSpec The default implementation uses McFarland's fast modified
* ziggurat algorithm (largely table-driven, with rare cases handled by
* computation and rejection sampling). Walker's alias method for sampling
* a discrete distribution also plays a role.
*/
default double nextExponential() {
return RandomSupport.computeNextExponential(this);
}
/**
* The {@link StreamableGenerator} interface augments the
* {@link RandomGenerator} interface to provide methods that return streams
* of {@link RandomGenerator} objects. Ideally, such a stream of objects
* would have the property that the behavior of each object is statistically
* independent of all the others. In practice, one may have to settle for
* some approximation to this property.
*
* <p> A generator that implements interface {@link SplittableGenerator} may
* choose to use its {@link SplittableGenerator#splits splits}() method to
* implement the {@link StreamableGenerator#rngs rngs}() method required by this
* interface.
*
* <p> A generator that implements interface {@link JumpableGenerator} may
* choose to use its {@link JumpableGenerator#jumps() jumps}() method to implement the
* {@link StreamableGenerator#rngs() rngs}() method required by this interface.
*
* <p> A generator that implements interface {@link LeapableGenerator} may
* choose to use its {@link LeapableGenerator#leaps() leaps}() method to
* implement the {@link StreamableGenerator#rngs() rngs}() method required by this
* interface.
*
* <p> Objects that implement {@link StreamableGenerator} are typically not
* cryptographically secure. Consider instead using {@link SecureRandom} to
* get a cryptographically secure pseudo-random number generator for use by
* security-sensitive applications.
*/
interface StreamableGenerator extends RandomGenerator {
/**
* Returns an instance of {@link StreamableGenerator} that utilizes the
* {@code name} <a href="package-summary.html#algorithms">algorithm</a>.
*
* @param name Name of random number generator
* <a href="package-summary.html#algorithms">algorithm</a>
*
* @return An instance of {@link StreamableGenerator}
*
* @throws NullPointerException if name is null
* @throws IllegalArgumentException if the named algorithm is not found
*/
static StreamableGenerator of(String name) {
Objects.requireNonNull(name);
return RandomGeneratorFactory.of(name, StreamableGenerator.class);
}
/**
* Returns an effectively unlimited stream of objects, each of which
* implements the {@link RandomGenerator} interface. Ideally the
* generators in the stream will appear to be statistically independent.
* The new generators are of the same
* <a href="package-summary.html#algorithms">algorithm</a> as this generator.
*
* @return a stream of objects that implement the {@link RandomGenerator} interface
*
* @implNote It is permitted to implement this method in a manner
* equivalent to {@link StreamableGenerator#rngs(long) rngs}
* ({@link Long#MAX_VALUE Long.MAX_VALUE}).
*/
Stream<RandomGenerator> rngs();
/**
* Returns an effectively unlimited stream of objects, each of which
* implements the {@link RandomGenerator} interface. Ideally the
* generators in the stream will appear to be statistically independent.
* The new generators are of the same
* <a href="package-summary.html#algorithms">algorithm</a> as this generator.
*
* @param streamSize the number of generators to generate
*
* @return a stream of objects that implement the {@link RandomGenerator} interface
*
* @throws IllegalArgumentException if {@code streamSize} is
* less than zero
*
* @implSpec The default implementation calls {@link StreamableGenerator#rngs() rngs}() and
* then limits its length to {@code streamSize}.
*/
default Stream<RandomGenerator> rngs(long streamSize) {
RandomSupport.checkStreamSize(streamSize);
return rngs().limit(streamSize);
}
}
/**
* This interface is designed to provide a common protocol for objects that
* generate sequences of pseudorandom values and can be <i>split</i> into
* two objects (the original one and a new one) each of which obey that same
* protocol (and therefore can be recursively split indefinitely).
*
* <p> Ideally, all {@link SplittableGenerator} objects produced by
* recursive splitting from a single original {@link SplittableGenerator}
* object are statistically independent of one another and individually
* uniform. Therefore we would expect the set of values collectively
* generated by a set of such objects to have the same statistical
* properties as if the same quantity of values were generated by a single
* thread using a single {@link SplittableGenerator} object. In practice,
* one must settle for some approximation to independence and uniformity.
*
* <p> Methods are provided to perform a single splitting operation and also
* to produce a stream of generators split off from the original (by either
* iterative or recursive splitting, or a combination).
*
* <p> Objects that implement {@link SplittableGenerator} are typically not
* cryptographically secure. Consider instead using {@link SecureRandom} to
* get a cryptographically secure pseudo-random number generator for use by
* security-sensitive applications.
*/
interface SplittableGenerator extends StreamableGenerator {
/**
* Returns an instance of {@link SplittableGenerator} that utilizes the
* {@code name} <a href="package-summary.html#algorithms">algorithm</a>.
*
* @param name Name of random number generator
* <a href="package-summary.html#algorithms">algorithm</a>
*
* @return An instance of {@link SplittableGenerator}
*
* @throws NullPointerException if name is null
* @throws IllegalArgumentException if the named algorithm is not found
*/
static SplittableGenerator of(String name) {
Objects.requireNonNull(name);
return RandomGeneratorFactory.of(name, SplittableGenerator.class);
}
/**
* Returns a new pseudorandom number generator, split off from this one,
* that implements the {@link RandomGenerator} and
* {@link SplittableGenerator} interfaces.
*
* <p> This pseudorandom number generator may be used as a source of
* pseudorandom bits used to initialize the state of the new one.
*
* @return a new object that implements the {@link RandomGenerator} and
* {@link SplittableGenerator} interfaces
*/
SplittableGenerator split();
/**
* Returns a new pseudorandom number generator, split off from this one,
* that implements the {@link RandomGenerator} and
* {@link SplittableGenerator} interfaces.
*
* @param source a {@link SplittableGenerator} instance to be used instead
* of this one as a source of pseudorandom bits used to
* initialize the state of the new ones.
*
* @return an object that implements the {@link RandomGenerator} and
* {@link SplittableGenerator} interfaces
*
* @throws NullPointerException if source is null
*/
SplittableGenerator split(SplittableGenerator source);
/**
* Returns an effectively unlimited stream of new pseudorandom number
* generators, each of which implements the {@link SplittableGenerator}
* interface.
*
* <p> This pseudorandom number generator may be used as a source of
* pseudorandom bits used to initialize the state the new ones.
*
* @implNote It is permitted to implement this method in a manner
* equivalent to {@link SplittableGenerator#splits(long) splits}
* ({@link Long#MAX_VALUE Long.MAX_VALUE}).
*
* @return a stream of {@link SplittableGenerator} objects
*
* @implSpec The default implementation invokes
* {@link SplittableGenerator#splits(SplittableGenerator) splits(this)}.
*/
default Stream<SplittableGenerator> splits() {
return this.splits(this);
}
/**
* Returns a stream producing the given {@code streamSize} number of new
* pseudorandom number generators, each of which implements the
* {@link SplittableGenerator} interface.
*
* <p> This pseudorandom number generator may be used as a source of
* pseudorandom bits used to initialize the state the new ones.
*
* @param streamSize the number of values to generate
*
* @return a stream of {@link SplittableGenerator} objects
*
* @throws IllegalArgumentException if {@code streamSize} is
* less than zero
*/
Stream<SplittableGenerator> splits(long streamSize);
/**
* Returns an effectively unlimited stream of new pseudorandom number
* generators, each of which implements the {@link SplittableGenerator}
* interface.
*
* @param source a {@link SplittableGenerator} instance to be used instead
* of this one as a source of pseudorandom bits used to
* initialize the state of the new ones.
*
* @return a stream of {@link SplittableGenerator} objects
*
* @implNote It is permitted to implement this method in a manner
* equivalent to {@link SplittableGenerator#splits(long, SplittableGenerator) splits}
* ({@link Long#MAX_VALUE Long.MAX_VALUE}, source).
*
* @throws NullPointerException if source is null
*/
Stream<SplittableGenerator> splits(SplittableGenerator source);
/**
* Returns a stream producing the given {@code streamSize} number of new
* pseudorandom number generators, each of which implements the
* {@link SplittableGenerator} interface.
*
* @param streamSize the number of values to generate
* @param source a {@link SplittableGenerator} instance to be used instead
* of this one as a source of pseudorandom bits used to
* initialize the state of the new ones.
*
* @return a stream of {@link SplittableGenerator} objects
*
* @throws IllegalArgumentException if {@code streamSize} is
* less than zero
* @throws NullPointerException if source is null
*/
Stream<SplittableGenerator> splits(long streamSize, SplittableGenerator source);
/**
* Returns an effectively unlimited stream of new pseudorandom number
* generators, each of which implements the {@link RandomGenerator}
* interface. Ideally the generators in the stream will appear to be
* statistically independent.
*
* @return a stream of objects that implement the {@link RandomGenerator} interface
*
* @implSpec The default implementation calls {@link SplittableGenerator#splits() splits}().
*/
default Stream<RandomGenerator> rngs() {
return this.splits().map(x -> x);
}
/**
* Returns a stream producing the given {@code streamSize} number of new
* pseudorandom number generators, each of which implements the
* {@link RandomGenerator} interface. Ideally the generators in the
* stream will appear to be statistically independent.
*
* @param streamSize the number of generators to generate
*
* @return a stream of objects that implement the {@link RandomGenerator} interface
*
* @throws IllegalArgumentException if {@code streamSize} is
* less than zero
*
* @implSpec The default implementation calls {@link SplittableGenerator#splits(long) splits}(streamSize).
*/
default Stream<RandomGenerator> rngs(long streamSize) {
return this.splits(streamSize).map(x -> x);
}
}
/**
* This interface is designed to provide a common protocol for objects that
* generate pseudorandom values and can easily <i>jump</i> forward, by a
* moderate amount (ex. 2<sup>64</sup>) to a distant point in the state cycle.
*
* <p> Ideally, all {@link JumpableGenerator} objects produced by iterative
* jumping from a single original {@link JumpableGenerator} object are
* statistically independent of one another and individually uniform. In
* practice, one must settle for some approximation to independence and
* uniformity. In particular, a specific implementation may assume that each
* generator in a stream produced by the
* {@link JumpableGenerator#jump jump()} method is used to produce a number
* of values no larger than either 2<sup>64</sup> or the square root of its
* period. Implementors are advised to use algorithms whose period is at
* least 2<sup>127</sup>.
*
* <p> Methods are provided to perform a single jump operation and also to
* produce a stream of generators produced from the original by iterative
* copying and jumping of internal state. A typical strategy for a
* multithreaded application is to create a single {@link JumpableGenerator}
* object, calls its {@link JumpableGenerator#jump jump}() method exactly
* once, and then parcel out generators from the resulting stream, one to
* each thread. It is generally not a good idea to call
* {@link JumpableGenerator#jump jump}() on a generator that was itself
* produced by the {@link JumpableGenerator#jump jump}() method, because the
* result may be a generator identical to another generator already produce
* by that call to the {@link JumpableGenerator#jump jump}() method. For
* this reason, the return type of the {@link JumpableGenerator#jumps jumps}()
* method is {@link Stream<RandomGenerator>} rather than
* {@link Stream<JumpableGenerator>}, even though the actual generator
* objects in that stream likely do also implement the
* {@link JumpableGenerator} interface.
*
* <p> Objects that implement {@link JumpableGenerator} are typically not
* cryptographically secure. Consider instead using {@link SecureRandom} to
* get a cryptographically secure pseudo-random number generator for use by
* security-sensitive applications.
*/
interface JumpableGenerator extends StreamableGenerator {
/**
* Returns an instance of {@link JumpableGenerator} that utilizes the
* {@code name} <a href="package-summary.html#algorithms">algorithm</a>.
*
* @param name Name of random number generator
* <a href="package-summary.html#algorithms">algorithm</a>
*
* @return An instance of {@link JumpableGenerator}
*
* @throws NullPointerException if name is null
* @throws IllegalArgumentException if the named algorithm is not found
*/
static JumpableGenerator of(String name) {
Objects.requireNonNull(name);
return RandomGeneratorFactory.of(name, JumpableGenerator.class);
}
/**
* Returns a new generator whose internal state is an exact copy of this
* generator (therefore their future behavior should be identical if
* subjected to the same series of operations).
*
* @return a new object that is a copy of this generator
*/
JumpableGenerator copy();
/**
* Alter the state of this pseudorandom number generator so as to jump
* forward a large, fixed distance (typically 2<sup>64</sup> or more)
* within its state cycle.
*/
void jump();
/**
* Returns the distance by which the
* {@link JumpableGenerator#jump jump}() method will jump forward within
* the state cycle of this generator object.
*
* @return the default jump distance (as a {@code double} value)
*/
double jumpDistance();
/**
* Returns an effectively unlimited stream of new pseudorandom number
* generators, each of which implements the {@link RandomGenerator}
* interface.
*
* @return a stream of objects that implement the {@link RandomGenerator} interface
*
* @implNote It is permitted to implement this method in a manner equivalent to
* {@link JumpableGenerator#jumps(long) jumps}
* ({@link Long#MAX_VALUE Long.MAX_VALUE}).
*
* @implSpec The default implementation produces a sequential stream that repeatedly
* calls {@link JumpableGenerator#copy copy}() and {@link JumpableGenerator#jump jump}()
* on this generator, and the copies become the generators produced by the stream.
*/
default Stream<RandomGenerator> jumps() {
return Stream.generate(this::copyAndJump).sequential();
}
/**
* Returns a stream producing the given {@code streamSize} number of new
* pseudorandom number generators, each of which implements the
* {@link RandomGenerator} interface.
*
* @param streamSize the number of generators to generate
*
* @return a stream of objects that implement the {@link RandomGenerator} interface
*
* @throws IllegalArgumentException if {@code streamSize} is less than zero
*
* @implSpec The default implementation produces a sequential stream that repeatedly
* calls {@link JumpableGenerator#copy copy}() and {@link JumpableGenerator#jump jump}()
* on this generator, and the copies become the generators produced by the stream.
*/
default Stream<RandomGenerator> jumps(long streamSize) {
return jumps().limit(streamSize);
}
/**
* Returns an effectively unlimited stream of new pseudorandom number
* generators, each of which implements the {@link RandomGenerator}
* interface. Ideally the generators in the stream will appear to be
* statistically independent.
*
* @return a stream of objects that implement the {@link RandomGenerator} interface
*
* @implSpec The default implementation calls {@link JumpableGenerator#jump jump}().
*/
default Stream<RandomGenerator> rngs() {
return this.jumps();
}
/**
* Returns a stream producing the given {@code streamSize} number of new
* pseudorandom number generators, each of which implements the
* {@link RandomGenerator} interface. Ideally the generators in the
* stream will appear to be statistically independent.
*
* @param streamSize the number of generators to generate
*
* @return a stream of objects that implement the {@link RandomGenerator} interface
*
* @throws IllegalArgumentException if {@code streamSize} is less than zero
*
* @implSpec The default implementation calls {@link JumpableGenerator#jumps(long) jumps}(streamSize).
*/
default Stream<RandomGenerator> rngs(long streamSize) {
return this.jumps(streamSize);
}
/**
* Copy this generator, jump this generator forward, then return the
* copy.
*
* @return a copy of this generator object before the jump occurred
*
* @implSpec The default implementation copies this, jumps and then
* returns the copy.
*/
default RandomGenerator copyAndJump() {
RandomGenerator result = copy();
jump();
return result;
}
}
/**
* This interface is designed to provide a common protocol for objects that
* generate sequences of pseudorandom values and can easily not only jump
* but also <i>leap</i> forward, by a large amount (ex. 2<sup>128</sup>), to
* a very distant point in the state cycle.
*
* Typically one will construct a series of {@link LeapableGenerator}
* objects by iterative leaping from a single original
* {@link LeapableGenerator} object, and then for each such object produce a
* subseries of objects by iterative jumping. There is little conceptual
* difference between leaping and jumping, but typically a leap will be a
* very long jump in the state cycle (perhaps distance 2<sup>128</sup> or
* so).
*
* <p> Ideally, all {@link LeapableGenerator} objects produced by iterative
* leaping and jumping from a single original {@link LeapableGenerator}
* object are statistically independent of one another and individually
* uniform. In practice, one must settle for some approximation to
* independence and uniformity. In particular, a specific implementation may
* assume that each generator in a stream produced by the {@code leaps}
* method is used to produce (by jumping) a number of objects no larger than
* 2<sup>64</sup>. Implementors are advised to use algorithms whose period
* is at least 2<sup>191</sup>.
*
* <p> Methods are provided to perform a single leap operation and also to
* produce a stream of generators produced from the original by iterative
* copying and leaping of internal state. The generators produced must
* implement the {@link JumpableGenerator} interface but need not also
* implement the {@link LeapableGenerator} interface. A typical strategy for
* a multithreaded application is to create a single
* {@link LeapableGenerator} object, calls its {@code leaps} method exactly
* once, and then parcel out generators from the resulting stream, one to
* each thread. Then the {@link JumpableGenerator#jump() jump}() method of
* each such generator be called to produce a substream of generator
* objects.
*
* <p> Objects that implement {@link LeapableGenerator} are typically not
* cryptographically secure. Consider instead using {@link SecureRandom} to
* get a cryptographically secure pseudo-random number generator for use by
* security-sensitive applications.
*/
interface LeapableGenerator extends JumpableGenerator {
/**
* Returns an instance of {@link LeapableGenerator} that utilizes the
* {@code name} <a href="package-summary.html#algorithms">algorithm</a>.
*
* @param name Name of random number generator
* <a href="package-summary.html#algorithms">algorithm</a>
*
* @return An instance of {@link LeapableGenerator}
*
* @throws NullPointerException if name is null
* @throws IllegalArgumentException if the named algorithm is not found
*/
static LeapableGenerator of(String name) {
Objects.requireNonNull(name);
return RandomGeneratorFactory.of(name, LeapableGenerator.class);
}
/**
* Returns a new generator whose internal state is an exact copy of this
* generator (therefore their future behavior should be identical if
* subjected to the same series of operations).
*
* @return a new object that is a copy of this generator
*/
LeapableGenerator copy();
/**
* Alter the state of this pseudorandom number generator so as to leap
* forward a large, fixed distance (typically 2<sup>96</sup> or more)
* within its state cycle.
*/
void leap();
/**
* Returns the distance by which the
* {@link LeapableGenerator#leap() leap}() method will leap forward within
* the state cycle of this generator object.
*
* @return the default leap distance (as a {@code double} value)
*/
double leapDistance();
/**
* Returns an effectively unlimited stream of new pseudorandom number
* generators, each of which implements the {@link JumpableGenerator}
* interface.
*
* @return a stream of objects that implement the {@link JumpableGenerator} interface
*
* @implNote It is permitted to implement this method in a manner equivalent to
* {@link LeapableGenerator#leaps(long) leaps}
* ({@link Long#MAX_VALUE Long.MAX_VALUE}).
*
* @implSpec The default implementation produces a sequential stream that repeatedly
* calls {@link LeapableGenerator#copy() copy}() and {@link LeapableGenerator#leap() leap}()
* on this generator, and the copies become the generators produced by the stream.
*/
default Stream<JumpableGenerator> leaps() {
return Stream.generate(this::copyAndLeap).sequential();
}
/**
* Returns a stream producing the given {@code streamSize} number of new
* pseudorandom number generators, each of which implements the
* {@link JumpableGenerator} interface.
*
* @param streamSize the number of generators to generate
*
* @return a stream of objects that implement the {@link JumpableGenerator} interface
*
* @throws IllegalArgumentException if {@code streamSize} is less than zero
*
* @implSpec The default implementation produces a sequential stream that repeatedly
* calls {@link LeapableGenerator#copy() copy}() and {@link LeapableGenerator#leap() leap}()
* on this generator, and the copies become the generators produced by the stream.
*/
default Stream<JumpableGenerator> leaps(long streamSize) {
return leaps().limit(streamSize);
}
/**
* Copy this generator, leap this generator forward, then return the
* copy.
*
* @return a copy of this generator object before the leap occurred
*
* @implSpec The default implementation copies this, leaps and then
* returns the copy.
*/
default JumpableGenerator copyAndLeap() {
JumpableGenerator result = copy();
leap();
return result;
}
}
/**
* This interface is designed to provide a common protocol for objects that
* generate sequences of pseudorandom values and can easily <i>jump</i>
* forward, by an arbitrary amount, to a distant point in the state cycle.
*
* <p> Ideally, all {@link ArbitrarilyJumpableGenerator} objects produced by
* iterative jumping from a single original
* {@link ArbitrarilyJumpableGenerator} object are statistically independent
* of one another and individually uniform, provided that they do not
* traverse overlapping portions of the state cycle. In practice, one must
* settle for some approximation to independence and uniformity. In
* particular, a specific implementation may assume that each generator in a
* stream produced by the {@link JumpableGenerator#jump() jump}() method is
* used to produce a number of values no larger than the jump distance
* specified. Implementors are advised to use algorithms whose period is at
* least 2<sup>127</sup>.
*
* <p> For many applications, it suffices to jump forward by a power of two
* or some small multiple of a power of two, but this power of two may not
* be representable as a {@code long} value. To avoid the use of
* {@link BigInteger} values as jump distances, {@code double} values are
* used instead.
*
* <p> Methods are provided to perform a single jump operation and also to
* produce a stream of generators produced from the original by iterative
* copying and jumping of internal state. A typical strategy for a
* multithreaded application is to create a single
* {@link ArbitrarilyJumpableGenerator} object, call its
* {@link JumpableGenerator#jump() jump}() method exactly once, and then
* parcel out generators from the resulting stream, one to each thread.
* However, each generator produced also has type
* {@link ArbitrarilyJumpableGenerator}; with care, different jump distances
* can be used to traverse the entire state cycle in various ways.
*
* <p> Objects that implement {@link ArbitrarilyJumpableGenerator} are
* typically not cryptographically secure. Consider instead using
* {@link SecureRandom} to get a cryptographically secure pseudo-random
* number generator for use by security-sensitive applications.
*/
interface ArbitrarilyJumpableGenerator extends LeapableGenerator {
/**
* Returns an instance of {@link ArbitrarilyJumpableGenerator} that
* utilizes the {@code name} <a href="package-summary.html#algorithms">algorithm</a>.
*
* @param name Name of random number generator
* <a href="package-summary.html#algorithms">algorithm</a>
*
* @return An instance of {@link ArbitrarilyJumpableGenerator}
*
* @throws NullPointerException if name is null
* @throws IllegalArgumentException if the named algorithm is not found
*/
static ArbitrarilyJumpableGenerator of(String name) {
Objects.requireNonNull(name);
return RandomGeneratorFactory.of(name, ArbitrarilyJumpableGenerator.class);
}
/**
* Returns a new generator whose internal state is an exact copy of this
* generator (therefore their future behavior should be identical if
* subjected to the same series of operations).
*
* @return a new object that is a copy of this generator
*/
ArbitrarilyJumpableGenerator copy();
/**
* Alter the state of this pseudorandom number generator so as to jump
* forward a distance equal to 2<sup>{@code logDistance}</sup> within
* its state cycle.
*
* @param logDistance the base-2 logarithm of the distance to jump forward within the state
* cycle
*
* @throws IllegalArgumentException if {@code logDistance} is
* 2<sup>{@code logDistance}</sup> is
* greater than the period of this generator
*/
void jumpPowerOfTwo(int logDistance);
/**
* Alter the state of this pseudorandom number generator so as to jump
* forward a specified distance within its state cycle.
*
* @param distance the distance to jump forward within the state cycle
*
* @throws IllegalArgumentException if {@code distance} is not greater than
* or equal to 0.0, or is greater than the
* period of this generator
*/
void jump(double distance);
/**
* Alter the state of this pseudorandom number generator so as to jump
* forward a large, fixed distance (typically 2<sup>64</sup> or more)
* within its state cycle. The distance used is that returned by method
* {@link ArbitrarilyJumpableGenerator#jumpDistance() jumpDistance}().
*
* @implSpec The default implementation invokes jump(jumpDistance()).
*/
default void jump() { jump(jumpDistance()); }
/**
* Returns an effectively unlimited stream of new pseudorandom number
* generators, each of which implements the
* {@link ArbitrarilyJumpableGenerator} interface, produced by jumping
* copies of this generator by different integer multiples of the
* specified jump distance.
*
* @param distance a distance to jump forward within the state cycle
*
* @return a stream of objects that implement the {@link RandomGenerator} interface
*
* @throws IllegalArgumentException if {@code distance} is not greater than
* or equal to 0.0, or is greater than the
* period of this generator
*
* @implSpec The default implementation is equivalent to
* {@link ArbitrarilyJumpableGenerator#jumps(long) jumps}
* ({@link Long#MAX_VALUE Long.MAX_VALUE}).
*/
default Stream<ArbitrarilyJumpableGenerator> jumps(double distance) {
return Stream.generate(() -> copyAndJump(distance)).sequential();
}
/**
* Returns a stream producing the given {@code streamSize} number of new
* pseudorandom number generators, each of which implements the
* {@link ArbitrarilyJumpableGenerator} interface, produced by jumping
* copies of this generator by different integer multiples of the
* specified jump distance.
*
* @param streamSize the number of generators to generate
* @param distance a distance to jump forward within the state cycle
*
* @return a stream of objects that implement the {@link RandomGenerator} interface
*
* @throws IllegalArgumentException if {@code streamSize} is less than zero or if
* {@code distance} is not greater than
* or equal to 0.0, or is greater than the
* period of this generator
*
* @implSpec The default implementation is equivalent to
* jumps(distance).limit(streamSize).
*/
default Stream<ArbitrarilyJumpableGenerator> jumps(long streamSize, double distance) {
return jumps(distance).limit(streamSize);
}
/**
* Alter the state of this pseudorandom number generator so as to jump
* forward a very large, fixed distance (typically 2<sup>128</sup> or
* more) within its state cycle. The distance used is that returned by
* method
* {@link ArbitrarilyJumpableGenerator#leapDistance() leapDistance}().
*/
default void leap() { jump(leapDistance()); }
/**
* Copy this generator, jump this generator forward, then return the
* copy.
*
* @param distance a distance to jump forward within the state cycle
*
* @return a copy of this generator object before the jump occurred
*
* @throws IllegalArgumentException if {@code distance} is not greater than
* or equal to 0.0, or is greater than the
* period of this generator
*
* @implSpec The default implementation copies this, jumps(distance) and then
* returns the copy.
*/
default ArbitrarilyJumpableGenerator copyAndJump(double distance) {
ArbitrarilyJumpableGenerator result = copy();
jump(distance);
return result;
}
}
}
⏎ java/util/random/RandomGenerator.java
Or download all of them as a single archive file:
File name: java.base-17.0.5-src.zip File size: 8883851 bytes Release date: 2022-09-13 Download
2023-09-26, ≈928🔥, 1💬
Related Topics: