RandomGenerator.ArbitrarilyJumpableGenerator
, RandomGenerator.JumpableGenerator
, RandomGenerator.LeapableGenerator
, RandomGenerator.SplittableGenerator
, RandomGenerator.StreamableGenerator
Random
, SecureRandom
, SplittableRandom
, ThreadLocalRandom
public interface RandomGenerator
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. 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.
In the case of int
, long
, and boolean
values, if there is no explicit specification of range, then the range includes all possible values of the type. In the case of float
and double
values, first a value is always chosen uniformly from the set of 2w values between 0.0 (inclusive) and 1.0 (exclusive), where w is Float.PRECISION
for float
values and Double.PRECISION
for double
values, such that adjacent values differ by 2−w (notice that this set is a subset of the set of all representable floating-point values 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.
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 r
implements RandomGenerator
, then the method call r.ints(100)
returns a stream of 100 int
values. These are not necessarily the exact same values that would have been returned if instead 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.
Every object that implements the 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 period. (Some implementations of the 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.)
As a rule, objects that implement the RandomGenerator
interface need not be thread-safe. It is recommended that multithreaded applications use either ThreadLocalRandom
or (preferably) pseudorandom number generators that implement the RandomGenerator.SplittableGenerator
or RandomGenerator.JumpableGenerator
interface.
Objects that implement RandomGenerator
are typically not cryptographically secure. Consider instead using SecureRandom
to get a cryptographically secure pseudorandom number generator for use by security-sensitive applications. Note, however, that SecureRandom
does implement the RandomGenerator
interface, so that instances of SecureRandom
may be used interchangeably with other types of pseudorandom generators in applications that do not require a secure generator.
Unless explicit stated otherwise, the use of null for any method argument will cause a NullPointerException.
Modifier and Type | Interface | Description |
---|---|---|
static interface |
RandomGenerator.ArbitrarilyJumpableGenerator |
This interface is designed to provide a common protocol for objects that generate sequences of pseudorandom values and can easily jump forward, by an arbitrary amount, to a distant point in the state cycle. |
static interface |
RandomGenerator.JumpableGenerator |
This interface is designed to provide a common protocol for objects that generate pseudorandom values and can easily jump forward, by a moderate amount (ex. 264) to a distant point in the state cycle. |
static interface |
RandomGenerator.LeapableGenerator |
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 leap forward, by a large amount (ex. 2128), to a very distant point in the state cycle. |
static interface |
RandomGenerator.SplittableGenerator |
This interface is designed to provide a common protocol for objects that generate sequences of pseudorandom values and can be split into two objects (the original one and a new one) each of which obey that same protocol (and therefore can be recursively split indefinitely). |
static interface |
RandomGenerator.StreamableGenerator |
The RandomGenerator.StreamableGenerator interface augments the RandomGenerator interface to provide methods that return streams of RandomGenerator objects. |
Modifier and Type | Method | Description |
---|---|---|
default DoubleStream |
doubles() |
Returns an effectively unlimited stream of pseudorandomly chosen double values. |
default DoubleStream |
doubles |
Returns an effectively unlimited stream of pseudorandomly chosen double values, where each value is between the specified origin (inclusive) and the specified bound (exclusive). |
default DoubleStream |
doubles |
Returns a stream producing the given streamSize number of pseudorandomly chosen double values. |
default DoubleStream |
doubles |
Returns a stream producing the given streamSize number of pseudorandomly chosen double values, where each value is between the specified origin (inclusive) and the specified bound (exclusive). |
static RandomGenerator |
getDefault() |
Returns a RandomGenerator meeting the minimal requirement of having an algorithm whose state bits are greater than or equal 64. |
default IntStream |
ints() |
Returns an effectively unlimited stream of pseudorandomly chosen int values. |
default IntStream |
ints |
Returns an effectively unlimited stream of pseudorandomly chosen int values, where each value is between the specified origin (inclusive) and the specified bound (exclusive). |
default IntStream |
ints |
Returns a stream producing the given streamSize number of pseudorandomly chosen int values. |
default IntStream |
ints |
Returns a stream producing the given streamSize number of pseudorandomly chosen int values, where each value is between the specified origin (inclusive) and the specified bound (exclusive). |
default boolean |
isDeprecated() |
Return true if the implementation of RandomGenerator (algorithm) has been marked for deprecation. |
default LongStream |
longs() |
Returns an effectively unlimited stream of pseudorandomly chosen long values. |
default LongStream |
longs |
Returns a stream producing the given streamSize number of pseudorandomly chosen long values. |
default LongStream |
longs |
Returns an effectively unlimited stream of pseudorandomly chosen long values, where each value is between the specified origin (inclusive) and the specified bound (exclusive). |
default LongStream |
longs |
Returns a stream producing the given streamSize number of pseudorandomly chosen long values, where each value is between the specified origin (inclusive) and the specified bound (exclusive). |
default boolean |
nextBoolean() |
Returns a pseudorandomly chosen boolean value. |
default void |
nextBytes |
Fills a user-supplied byte array with generated byte values pseudorandomly chosen uniformly from the range of values between -128 (inclusive) and 127 (inclusive). |
default double |
nextDouble() |
Returns a pseudorandom double value between zero (inclusive) and one (exclusive). |
default double |
nextDouble |
Returns a pseudorandomly chosen double value between zero (inclusive) and the specified bound (exclusive). |
default double |
nextDouble |
Returns a pseudorandomly chosen double value between the specified origin (inclusive) and the specified bound (exclusive). |
default double |
nextExponential() |
Returns a nonnegative double value pseudorandomly chosen from an exponential distribution whose mean is 1. |
default float |
nextFloat() |
Returns a pseudorandom float value between zero (inclusive) and one (exclusive). |
default float |
nextFloat |
Returns a pseudorandomly chosen float value between zero (inclusive) and the specified bound (exclusive). |
default float |
nextFloat |
Returns a pseudorandomly chosen float value between the specified origin (inclusive) and the specified bound (exclusive). |
default double |
nextGaussian() |
Returns a double value pseudorandomly chosen from a Gaussian (normal) distribution whose mean is 0 and whose standard deviation is 1. |
default double |
nextGaussian |
Returns a double value pseudorandomly chosen from a Gaussian (normal) distribution with a mean and standard deviation specified by the arguments. |
default int |
nextInt() |
Returns a pseudorandomly chosen int value. |
default int |
nextInt |
Returns a pseudorandomly chosen int value between zero (inclusive) and the specified bound (exclusive). |
default int |
nextInt |
Returns a pseudorandomly chosen int value between the specified origin (inclusive) and the specified bound (exclusive). |
long |
nextLong() |
Returns a pseudorandomly chosen long value. |
default long |
nextLong |
Returns a pseudorandomly chosen long value between zero (inclusive) and the specified bound (exclusive). |
default long |
nextLong |
Returns a pseudorandomly chosen long value between the specified origin (inclusive) and the specified bound (exclusive). |
static RandomGenerator |
of |
static RandomGenerator of(String name)
name
- Name of random number generator algorithm
RandomGenerator
NullPointerException
- if name is nullIllegalArgumentException
- if the named algorithm is not foundstatic RandomGenerator getDefault()
RandomGenerator
meeting the minimal requirement of having an algorithm whose state bits are greater than or equal 64.The default implementation selects L32X64MixRandom.
RandomGenerator
default boolean isDeprecated()
default DoubleStream doubles()
double
values.nextDouble
().doubles
(Long.MAX_VALUE
).double
valuesdefault DoubleStream doubles(double randomNumberOrigin, double randomNumberBound)
double
values, where each value is between the specified origin (inclusive) and the specified bound (exclusive).nextDouble
(randomNumberOrigin, randomNumberBound).doubles
(Long.MAX_VALUE
, randomNumberOrigin, randomNumberBound).randomNumberOrigin
- the least value that can be producedrandomNumberBound
- the upper bound (exclusive) for each value produceddouble
values, each between the specified origin (inclusive) and the specified bound (exclusive)IllegalArgumentException
- if randomNumberOrigin
is not finite, or randomNumberBound
is not finite, or randomNumberOrigin
is greater than or equal to randomNumberBound
default DoubleStream doubles(long streamSize)
streamSize
number of pseudorandomly chosen double
values.nextDouble()
.streamSize
- the number of values to generatedouble
valuesIllegalArgumentException
- if streamSize
is less than zerodefault DoubleStream doubles(long streamSize, double randomNumberOrigin, double randomNumberBound)
streamSize
number of pseudorandomly chosen double
values, where each value is between the specified origin (inclusive) and the specified bound (exclusive).nextDouble
(randomNumberOrigin, randomNumberBound).streamSize
- the number of values to generaterandomNumberOrigin
- the least value that can be producedrandomNumberBound
- the upper bound (exclusive) for each value produceddouble
values, each between the specified origin (inclusive) and the specified bound (exclusive)IllegalArgumentException
- if streamSize
is less than zero, or randomNumberOrigin
is not finite, or randomNumberBound
is not finite, or randomNumberOrigin
is greater than or equal to randomNumberBound
default IntStream ints()
int
values.nextInt
().ints
(Long.MAX_VALUE
).int
valuesdefault IntStream ints(int randomNumberOrigin, int randomNumberBound)
int
values, where each value is between the specified origin (inclusive) and the specified bound (exclusive).nextInt
(randomNumberOrigin, randomNumberBound).ints
(Long.MAX_VALUE
, randomNumberOrigin, randomNumberBound).randomNumberOrigin
- the least value that can be producedrandomNumberBound
- the upper bound (exclusive) for each value producedint
values, each between the specified origin (inclusive) and the specified bound (exclusive)IllegalArgumentException
- if randomNumberOrigin
is greater than or equal to randomNumberBound
default IntStream ints(long streamSize)
streamSize
number of pseudorandomly chosen int
values.nextInt
().streamSize
- the number of values to generateint
valuesIllegalArgumentException
- if streamSize
is less than zerodefault IntStream ints(long streamSize, int randomNumberOrigin, int randomNumberBound)
streamSize
number of pseudorandomly chosen int
values, where each value is between the specified origin (inclusive) and the specified bound (exclusive).nextInt
(randomNumberOrigin, randomNumberBound).streamSize
- the number of values to generaterandomNumberOrigin
- the least value that can be producedrandomNumberBound
- the upper bound (exclusive) for each value producedint
values, each between the specified origin (inclusive) and the specified bound (exclusive)IllegalArgumentException
- if streamSize
is less than zero, or randomNumberOrigin
is greater than or equal to randomNumberBound
default LongStream longs()
long
values.nextLong
().longs
(Long.MAX_VALUE
).long
valuesdefault LongStream longs(long randomNumberOrigin, long randomNumberBound)
long
values, where each value is between the specified origin (inclusive) and the specified bound (exclusive).nextLong
(randomNumberOrigin, randomNumberBound).longs
(Long.MAX_VALUE
, randomNumberOrigin, randomNumberBound).randomNumberOrigin
- the least value that can be producedrandomNumberBound
- the upper bound (exclusive) for each value producedlong
values, each between the specified origin (inclusive) and the specified bound (exclusive)IllegalArgumentException
- if randomNumberOrigin
is greater than or equal to randomNumberBound
default LongStream longs(long streamSize)
streamSize
number of pseudorandomly chosen long
values.nextLong
().streamSize
- the number of values to generatelong
valuesIllegalArgumentException
- if streamSize
is less than zerodefault LongStream longs(long streamSize, long randomNumberOrigin, long randomNumberBound)
streamSize
number of pseudorandomly chosen long
values, where each value is between the specified origin (inclusive) and the specified bound (exclusive).nextLong
(randomNumberOrigin, randomNumberBound).streamSize
- the number of values to generaterandomNumberOrigin
- the least value that can be producedrandomNumberBound
- the upper bound (exclusive) for each value producedlong
values, each between the specified origin (inclusive) and the specified bound (exclusive)IllegalArgumentException
- if streamSize
is less than zero, or randomNumberOrigin
is greater than or equal to randomNumberBound
default boolean nextBoolean()
boolean
value. 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 values whose high-order bits have better statistical quality than the low-order bits.
nextInt()
.boolean
valuedefault void nextBytes(byte[] bytes)
nextLong()
.
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;
}
bytes
- the byte array to fill with pseudorandom bytesNullPointerException
- if bytes is nulldefault float nextFloat()
float
value between zero (inclusive) and one (exclusive).Float.PRECISION
high-order bits from a call to nextInt()
.float
value between zero (inclusive) and one (exclusive)default float nextFloat(float bound)
float
value between zero (inclusive) and the specified bound (exclusive).bound
is a positive finite float. Then invokes nextFloat()
, scaling the result so that the final result lies between 0.0f
(inclusive) and bound
(exclusive).bound
- the upper bound (exclusive) for the returned value. Must be positive and finitefloat
value between zero (inclusive) and the bound (exclusive)IllegalArgumentException
- if bound
is not both positive and finitedefault float nextFloat(float origin, float bound)
float
value between the specified origin (inclusive) and the specified bound (exclusive).origin
and bound
are valid then invokes nextFloat()
scaling and translating the result to fit between origin
and bound
(exclusive).origin
- the least value that can be returnedbound
- the upper bound (exclusive)float
value between the origin (inclusive) and the bound (exclusive)IllegalArgumentException
- if origin
is not finite, or bound
is not finite, or origin
is greater than or equal to bound
default double nextDouble()
double
value between zero (inclusive) and one (exclusive).Double.PRECISION
high-order bits from a call to nextLong()
.double
value between zero (inclusive) and one (exclusive)default double nextDouble(double bound)
double
value between zero (inclusive) and the specified bound (exclusive).bound
is a positive finite double. Then invokes nextDouble()
, scaling the result so that the final result lies between 0.0
(inclusive) and bound
(exclusive).bound
- the upper bound (exclusive) for the returned value. Must be positive and finitedouble
value between zero (inclusive) and the bound (exclusive)IllegalArgumentException
- if bound
is not both positive and finitedefault double nextDouble(double origin, double bound)
double
value between the specified origin (inclusive) and the specified bound (exclusive).origin
and bound
are valid, then invokes nextDouble()
scaling and translating the result to fit between origin
and bound
( exclusive).origin
- the least value that can be returnedbound
- the upper bound (exclusive) for the returned valuedouble
value between the origin (inclusive) and the bound (exclusive)IllegalArgumentException
- if origin
is not finite, or bound
is not finite, or origin
is greater than or equal to bound
default int nextInt()
int
value.nextLong
().int
valuedefault int nextInt(int bound)
int
value between zero (inclusive) and the specified bound (exclusive).bound
is a positive int
. Then invokes nextInt()
, limiting the result to be greater than or equal zero and less than bound
. If bound
is a power of two then limiting is a simple masking operation. Otherwise, the result is re-calculated by invoking nextInt()
until the result is greater than or equal zero and less than bound
.bound
- the upper bound (exclusive) for the returned value. Must be positive.int
value between zero (inclusive) and the bound (exclusive)IllegalArgumentException
- if bound
is not positivedefault int nextInt(int origin, int bound)
int
value between the specified origin (inclusive) and the specified bound (exclusive).origin
and bound
are positive ints
. Then invokes nextInt()
, limiting the result to be greater that or equal origin
and less than bound
. If bound
is a power of two then limiting is a simple masking operation. Otherwise, the result is re-calculated by invoking nextInt()
until the result is greater than or equal origin
and less than bound
.origin
- the least value that can be returnedbound
- the upper bound (exclusive) for the returned valueint
value between the origin (inclusive) and the bound (exclusive)IllegalArgumentException
- if origin
is greater than or equal to bound
long nextLong()
long
value.long
valuedefault long nextLong(long bound)
long
value between zero (inclusive) and the specified bound (exclusive).bound
is a positive long
. Then invokes nextLong()
, limiting the result to be greater than or equal zero and less than bound
. If bound
is a power of two then limiting is a simple masking operation. Otherwise, the result is re-calculated by invoking nextLong()
until the result is greater than or equal zero and less than bound
.bound
- the upper bound (exclusive) for the returned value. Must be positive.long
value between zero (inclusive) and the bound (exclusive)IllegalArgumentException
- if bound
is not positivedefault long nextLong(long origin, long bound)
long
value between the specified origin (inclusive) and the specified bound (exclusive).origin
and bound
are positive longs
. Then invokes nextLong()
, limiting the result to be greater than or equal origin
and less than bound
. If bound
is a power of two then limiting is a simple masking operation. Otherwise, the result is re-calculated by invoking nextLong()
until the result is greater than or equal origin
and less than bound
.origin
- the least value that can be returnedbound
- the upper bound (exclusive) for the returned valuelong
value between the origin (inclusive) and the bound (exclusive)IllegalArgumentException
- if origin
is greater than or equal to bound
default double nextGaussian()
double
value pseudorandomly chosen from a Gaussian (normal) distribution whose mean is 0 and whose standard deviation is 1.double
value pseudorandomly chosen from a Gaussian distributiondefault double nextGaussian(double mean, double stddev)
double
value pseudorandomly chosen from a Gaussian (normal) distribution with a mean and standard deviation specified by the arguments.mean
- the mean of the Gaussian distribution to be drawn fromstddev
- the standard deviation (square root of the variance) of the Gaussian distribution to be drawn fromdouble
value pseudorandomly chosen from the specified Gaussian distributionIllegalArgumentException
- if stddev
is negativedefault double nextExponential()
double
value pseudorandomly chosen from an exponential distribution whose mean is 1.double
value pseudorandomly chosen from an exponential distribution
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/random/RandomGenerator.html