- All Known Subinterfaces:
RandomGenerator.ArbitrarilyJumpableGenerator
,RandomGenerator.JumpableGenerator
,RandomGenerator.LeapableGenerator
,RandomGenerator.SplittableGenerator
,RandomGenerator.StreamableGenerator
- All Known Implementing Classes:
Random
,SecureRandom
,SplittableRandom
,ThreadLocalRandom
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.
- Since:
- 17
-
Nested Class Summary
Modifier and TypeInterfaceDescriptionstatic interface
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
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
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
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
TheRandomGenerator.StreamableGenerator
interface augments theRandomGenerator
interface to provide methods that return streams ofRandomGenerator
objects. -
Method Summary
Modifier and TypeMethodDescriptiondefault DoubleStream
doubles()
Returns an effectively unlimited stream of pseudorandomly chosendouble
values.default DoubleStream
doubles
(double randomNumberOrigin, double randomNumberBound) Returns an effectively unlimited stream of pseudorandomly chosendouble
values, where each value is between the specified origin (inclusive) and the specified bound (exclusive).default DoubleStream
doubles
(long streamSize) Returns a stream producing the givenstreamSize
number of pseudorandomly chosendouble
values.default DoubleStream
doubles
(long streamSize, double randomNumberOrigin, double randomNumberBound) Returns a stream producing the givenstreamSize
number of pseudorandomly chosendouble
values, where each value is between the specified origin (inclusive) and the specified bound (exclusive).default DoubleStream
equiDoubles
(double left, double right, boolean isLeftIncluded, boolean isRightIncluded) Returns an effectively unlimited stream of pseudorandomly chosendouble
values, where each value is between the specifiedleft
boundary and the specifiedright
boundary.static RandomGenerator
Returns aRandomGenerator
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 chosenint
values.default IntStream
ints
(int randomNumberOrigin, int randomNumberBound) Returns an effectively unlimited stream of pseudorandomly chosenint
values, where each value is between the specified origin (inclusive) and the specified bound (exclusive).default IntStream
ints
(long streamSize) Returns a stream producing the givenstreamSize
number of pseudorandomly chosenint
values.default IntStream
ints
(long streamSize, int randomNumberOrigin, int randomNumberBound) Returns a stream producing the givenstreamSize
number of pseudorandomly chosenint
values, where each value is between the specified origin (inclusive) and the specified bound (exclusive).default boolean
Return true if the implementation of RandomGenerator (algorithm) has been marked for deprecation.default LongStream
longs()
Returns an effectively unlimited stream of pseudorandomly chosenlong
values.default LongStream
longs
(long streamSize) Returns a stream producing the givenstreamSize
number of pseudorandomly chosenlong
values.default LongStream
longs
(long randomNumberOrigin, long randomNumberBound) Returns an effectively unlimited stream of pseudorandomly chosenlong
values, where each value is between the specified origin (inclusive) and the specified bound (exclusive).default LongStream
longs
(long streamSize, long randomNumberOrigin, long randomNumberBound) Returns a stream producing the givenstreamSize
number of pseudorandomly chosenlong
values, where each value is between the specified origin (inclusive) and the specified bound (exclusive).default boolean
Returns a pseudorandomly chosenboolean
value.default void
nextBytes
(byte[] bytes) 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
Returns a pseudorandomdouble
value between zero (inclusive) and one (exclusive).default double
nextDouble
(double bound) Returns a pseudorandomly chosendouble
value between zero (inclusive) and the specified bound (exclusive).default double
nextDouble
(double origin, double bound) Returns a pseudorandomly chosendouble
value between the specified origin (inclusive) and the specified bound (exclusive).default double
Returns a nonnegativedouble
value pseudorandomly chosen from an exponential distribution whose mean is 1.default float
Returns a pseudorandomfloat
value between zero (inclusive) and one (exclusive).default float
nextFloat
(float bound) Returns a pseudorandomly chosenfloat
value between zero (inclusive) and the specified bound (exclusive).default float
nextFloat
(float origin, float bound) Returns a pseudorandomly chosenfloat
value between the specified origin (inclusive) and the specified bound (exclusive).default double
Returns adouble
value pseudorandomly chosen from a Gaussian (normal) distribution whose mean is 0 and whose standard deviation is 1.default double
nextGaussian
(double mean, double stddev) Returns adouble
value pseudorandomly chosen from a Gaussian (normal) distribution with a mean and standard deviation specified by the arguments.default int
nextInt()
Returns a pseudorandomly chosenint
value.default int
nextInt
(int bound) Returns a pseudorandomly chosenint
value between zero (inclusive) and the specified bound (exclusive).default int
nextInt
(int origin, int bound) Returns a pseudorandomly chosenint
value between the specified origin (inclusive) and the specified bound (exclusive).long
nextLong()
Returns a pseudorandomly chosenlong
value.default long
nextLong
(long bound) Returns a pseudorandomly chosenlong
value between zero (inclusive) and the specified bound (exclusive).default long
nextLong
(long origin, long bound) Returns a pseudorandomly chosenlong
value between the specified origin (inclusive) and the specified bound (exclusive).static RandomGenerator
-
Method Details
-
of
- Parameters:
name
- Name of random number generator algorithm- Returns:
- An instance of
RandomGenerator
- Throws:
NullPointerException
- if name is nullIllegalArgumentException
- if the named algorithm is not found
-
getDefault
Returns aRandomGenerator
meeting the minimal requirement of having an algorithm whose state bits are greater than or equal 64.- Implementation Requirements:
- Since algorithms will improve over time, there is no
guarantee that this method will return the same algorithm over time.
The default implementation selects L32X64MixRandom.
- Returns:
- a
RandomGenerator
-
isDeprecated
default boolean isDeprecated()Return true if the implementation of RandomGenerator (algorithm) has been marked for deprecation.- Implementation Requirements:
- The default implementation checks for the @Deprecated annotation.
- Implementation Note:
- 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.
- Returns:
- true if the implementation of RandomGenerator (algorithm) has been marked for deprecation
-
doubles
Returns an effectively unlimited stream of pseudorandomly chosendouble
values.- Implementation Requirements:
- The default implementation produces a sequential stream
that repeatedly calls
nextDouble
(). - Implementation Note:
- It is permitted to implement this method in a manner equivalent to
doubles
(Long.MAX_VALUE
). - Returns:
- a stream of pseudorandomly chosen
double
values
-
doubles
Returns an effectively unlimited stream of pseudorandomly chosendouble
values, where each value is between the specified origin (inclusive) and the specified bound (exclusive).- Implementation Requirements:
- The default implementation produces a sequential stream that repeatedly
calls
nextDouble
(randomNumberOrigin, randomNumberBound). - Implementation Note:
- It is permitted to implement this method in a manner equivalent to
doubles
(Long.MAX_VALUE
, randomNumberOrigin, randomNumberBound). - Parameters:
randomNumberOrigin
- the least value that can be producedrandomNumberBound
- the upper bound (exclusive) for each value produced- Returns:
- a stream of pseudorandomly chosen
double
values, each between the specified origin (inclusive) and the specified bound (exclusive) - Throws:
IllegalArgumentException
- ifrandomNumberOrigin
is not finite, orrandomNumberBound
is not finite, orrandomNumberOrigin
is greater than or equal torandomNumberBound
-
doubles
Returns a stream producing the givenstreamSize
number of pseudorandomly chosendouble
values.- Implementation Requirements:
- The default implementation produces a sequential stream
that repeatedly calls
nextDouble()
. - Parameters:
streamSize
- the number of values to generate- Returns:
- a stream of pseudorandomly chosen
double
values - Throws:
IllegalArgumentException
- ifstreamSize
is less than zero
-
doubles
Returns a stream producing the givenstreamSize
number of pseudorandomly chosendouble
values, where each value is between the specified origin (inclusive) and the specified bound (exclusive).- Implementation Requirements:
- The default implementation produces a sequential stream that repeatedly
calls
nextDouble
(randomNumberOrigin, randomNumberBound). - Parameters:
streamSize
- the number of values to generaterandomNumberOrigin
- the least value that can be producedrandomNumberBound
- the upper bound (exclusive) for each value produced- Returns:
- a stream of pseudorandomly chosen
double
values, each between the specified origin (inclusive) and the specified bound (exclusive) - Throws:
IllegalArgumentException
- ifstreamSize
is less than zero, orrandomNumberOrigin
is not finite, orrandomNumberBound
is not finite, orrandomNumberOrigin
is greater than or equal torandomNumberBound
-
equiDoubles
default DoubleStream equiDoubles(double left, double right, boolean isLeftIncluded, boolean isRightIncluded) Returns an effectively unlimited stream of pseudorandomly chosendouble
values, where each value is between the specifiedleft
boundary and the specifiedright
boundary. Theleft
boundary is included as indicated byisLeftIncluded
; similarly, theright
boundary is included as indicated byisRightIncluded
.The stream potentially produces all multiples k δ (k integer) lying in the interval specified by the parameters, where δ > 0 is the smallest number for which all these multiples are exact
double
s. They are therefore all equidistant. The uniformity of the distribution of thedouble
s produced by the stream depends on the quality of the underlyingnextLong(long)
.- Implementation Requirements:
- The default implementation first determines the δ above.
It then computes both the smallest integer kl
such that kl δ lies inside
the given interval, and the smallest integer n > 0 such that
(kl + n) δ lies
outside the interval.
Finally, it returns a stream which generates the
double
s according to (kl +nextLong(
n)
) δ. The stream never produces-0.0
, although it may produce0.0
if the specified interval contains 0. - Parameters:
left
- the left boundaryright
- the right boundaryisLeftIncluded
- whether theleft
boundary is includedisRightIncluded
- whether theright
boundary is included- Returns:
- a stream of pseudorandomly chosen
double
values, each betweenleft
andright
, as specified above. - Throws:
IllegalArgumentException
- ifleft
is not finite, orright
is not finite, or if the specified interval is empty.- Since:
- 22
-
ints
Returns an effectively unlimited stream of pseudorandomly chosenint
values.- Implementation Requirements:
- The default implementation produces a sequential stream
that repeatedly calls
nextInt
(). - Implementation Note:
- It is permitted to implement this method in a manner
equivalent to
ints
(Long.MAX_VALUE
). - Returns:
- a stream of pseudorandomly chosen
int
values
-
ints
Returns an effectively unlimited stream of pseudorandomly chosenint
values, where each value is between the specified origin (inclusive) and the specified bound (exclusive).- Implementation Requirements:
- The default implementation produces a sequential stream that repeatedly
calls
nextInt
(randomNumberOrigin, randomNumberBound). - Implementation Note:
- It is permitted to implement this method in a manner equivalent to
ints
(Long.MAX_VALUE
, randomNumberOrigin, randomNumberBound). - Parameters:
randomNumberOrigin
- the least value that can be producedrandomNumberBound
- the upper bound (exclusive) for each value produced- Returns:
- a stream of pseudorandomly chosen
int
values, each between the specified origin (inclusive) and the specified bound (exclusive) - Throws:
IllegalArgumentException
- ifrandomNumberOrigin
is greater than or equal torandomNumberBound
-
ints
Returns a stream producing the givenstreamSize
number of pseudorandomly chosenint
values.- Implementation Requirements:
- The default implementation produces a sequential stream
that repeatedly calls
nextInt
(). - Parameters:
streamSize
- the number of values to generate- Returns:
- a stream of pseudorandomly chosen
int
values - Throws:
IllegalArgumentException
- ifstreamSize
is less than zero
-
ints
Returns a stream producing the givenstreamSize
number of pseudorandomly chosenint
values, where each value is between the specified origin (inclusive) and the specified bound (exclusive).- Implementation Requirements:
- The default implementation produces a sequential stream that repeatedly
calls
nextInt
(randomNumberOrigin, randomNumberBound). - Parameters:
streamSize
- the number of values to generaterandomNumberOrigin
- the least value that can be producedrandomNumberBound
- the upper bound (exclusive) for each value produced- Returns:
- a stream of pseudorandomly chosen
int
values, each between the specified origin (inclusive) and the specified bound (exclusive) - Throws:
IllegalArgumentException
- ifstreamSize
is less than zero, orrandomNumberOrigin
is greater than or equal torandomNumberBound
-
longs
Returns an effectively unlimited stream of pseudorandomly chosenlong
values.- Implementation Requirements:
- The default implementation produces a sequential stream
that repeatedly calls
nextLong
(). - Implementation Note:
- It is permitted to implement this method in a manner
equivalent to
longs
(Long.MAX_VALUE
). - Returns:
- a stream of pseudorandomly chosen
long
values
-
longs
Returns an effectively unlimited stream of pseudorandomly chosenlong
values, where each value is between the specified origin (inclusive) and the specified bound (exclusive).- Implementation Requirements:
- The default implementation produces a sequential stream that repeatedly
calls
nextLong
(randomNumberOrigin, randomNumberBound). - Implementation Note:
- It is permitted to implement this method in a manner equivalent to
longs
(Long.MAX_VALUE
, randomNumberOrigin, randomNumberBound). - Parameters:
randomNumberOrigin
- the least value that can be producedrandomNumberBound
- the upper bound (exclusive) for each value produced- Returns:
- a stream of pseudorandomly chosen
long
values, each between the specified origin (inclusive) and the specified bound (exclusive) - Throws:
IllegalArgumentException
- ifrandomNumberOrigin
is greater than or equal torandomNumberBound
-
longs
Returns a stream producing the givenstreamSize
number of pseudorandomly chosenlong
values.- Implementation Requirements:
- The default implementation produces a sequential stream
that repeatedly calls
nextLong
(). - Parameters:
streamSize
- the number of values to generate- Returns:
- a stream of pseudorandomly chosen
long
values - Throws:
IllegalArgumentException
- ifstreamSize
is less than zero
-
longs
Returns a stream producing the givenstreamSize
number of pseudorandomly chosenlong
values, where each value is between the specified origin (inclusive) and the specified bound (exclusive).- Implementation Requirements:
- The default implementation produces a sequential stream that repeatedly
calls
nextLong
(randomNumberOrigin, randomNumberBound). - Parameters:
streamSize
- the number of values to generaterandomNumberOrigin
- the least value that can be producedrandomNumberBound
- the upper bound (exclusive) for each value produced- Returns:
- a stream of pseudorandomly chosen
long
values, each between the specified origin (inclusive) and the specified bound (exclusive) - Throws:
IllegalArgumentException
- ifstreamSize
is less than zero, orrandomNumberOrigin
is greater than or equal torandomNumberBound
-
nextBoolean
default boolean nextBoolean()Returns a pseudorandomly chosenboolean
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.- Implementation Requirements:
- The default implementation produces a result based on the
sign bit of a number generated by
nextInt()
. - Returns:
- a pseudorandomly chosen
boolean
value
-
nextBytes
default void nextBytes(byte[] bytes) Fills a user-supplied byte array with generated byte values pseudorandomly chosen uniformly from the range of values between -128 (inclusive) and 127 (inclusive).- Implementation Requirements:
- The default implementation produces results from repeated calls
to
nextLong()
. - Implementation Note:
- Algorithm used to fill the byte array;
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; }
- Parameters:
bytes
- the byte array to fill with pseudorandom bytes- Throws:
NullPointerException
- if bytes is null
-
nextFloat
default float nextFloat()Returns a pseudorandomfloat
value between zero (inclusive) and one (exclusive).- Implementation Requirements:
- The default implementation uses the
Float.PRECISION
high-order bits from a call tonextInt()
. - Returns:
- a pseudorandom
float
value between zero (inclusive) and one (exclusive)
-
nextFloat
default float nextFloat(float bound) Returns a pseudorandomly chosenfloat
value between zero (inclusive) and the specified bound (exclusive).- Implementation Requirements:
- The default implementation checks that
bound
is a positive finite float. Then invokesnextFloat()
, scaling the result so that the final result lies between0.0f
(inclusive) andbound
(exclusive). - Parameters:
bound
- the upper bound (exclusive) for the returned value. Must be positive and finite- Returns:
- a pseudorandomly chosen
float
value between zero (inclusive) and the bound (exclusive) - Throws:
IllegalArgumentException
- ifbound
is not both positive and finite
-
nextFloat
default float nextFloat(float origin, float bound) Returns a pseudorandomly chosenfloat
value between the specified origin (inclusive) and the specified bound (exclusive).- Implementation Requirements:
- The default implementation verifies that the
origin
andbound
are valid then invokesnextFloat()
scaling and translating the result to fit betweenorigin
andbound
(exclusive). - Parameters:
origin
- the least value that can be returnedbound
- the upper bound (exclusive)- Returns:
- a pseudorandomly chosen
float
value between the origin (inclusive) and the bound (exclusive) - Throws:
IllegalArgumentException
- iforigin
is not finite, orbound
is not finite, ororigin
is greater than or equal tobound
-
nextDouble
default double nextDouble()Returns a pseudorandomdouble
value between zero (inclusive) and one (exclusive).- Implementation Requirements:
- The default implementation uses the
Double.PRECISION
high-order bits from a call tonextLong()
. - Returns:
- a pseudorandom
double
value between zero (inclusive) and one (exclusive)
-
nextDouble
default double nextDouble(double bound) Returns a pseudorandomly chosendouble
value between zero (inclusive) and the specified bound (exclusive).- Implementation Requirements:
- The default implementation checks that
bound
is a positive finite double. Then invokesnextDouble()
, scaling the result so that the final result lies between0.0
(inclusive) andbound
(exclusive). - Parameters:
bound
- the upper bound (exclusive) for the returned value. Must be positive and finite- Returns:
- a pseudorandomly chosen
double
value between zero (inclusive) and the bound (exclusive) - Throws:
IllegalArgumentException
- ifbound
is not both positive and finite
-
nextDouble
default double nextDouble(double origin, double bound) Returns a pseudorandomly chosendouble
value between the specified origin (inclusive) and the specified bound (exclusive).- Implementation Requirements:
- The default implementation verifies that the
origin
andbound
are valid, then invokesnextDouble()
scaling and translating the result to fit betweenorigin
andbound
( exclusive). - Parameters:
origin
- the least value that can be returnedbound
- the upper bound (exclusive) for the returned value- Returns:
- a pseudorandomly chosen
double
value between the origin (inclusive) and the bound (exclusive) - Throws:
IllegalArgumentException
- iforigin
is not finite, orbound
is not finite, ororigin
is greater than or equal tobound
-
nextInt
default int nextInt()Returns a pseudorandomly chosenint
value.- Implementation Requirements:
- The default implementation uses the 32 high-order bits from a call to
nextLong
(). - Returns:
- a pseudorandomly chosen
int
value
-
nextInt
default int nextInt(int bound) Returns a pseudorandomly chosenint
value between zero (inclusive) and the specified bound (exclusive).- Implementation Requirements:
- The default implementation checks that
bound
is a positiveint
. Then invokesnextInt()
, limiting the result to be greater than or equal zero and less thanbound
. Ifbound
is a power of two then limiting is a simple masking operation. Otherwise, the result is re-calculated by invokingnextInt()
until the result is greater than or equal zero and less thanbound
. - Parameters:
bound
- the upper bound (exclusive) for the returned value. Must be positive.- Returns:
- a pseudorandomly chosen
int
value between zero (inclusive) and the bound (exclusive) - Throws:
IllegalArgumentException
- ifbound
is not positive
-
nextInt
default int nextInt(int origin, int bound) Returns a pseudorandomly chosenint
value between the specified origin (inclusive) and the specified bound (exclusive).- Implementation Requirements:
- The default implementation checks that
origin
andbound
are positiveints
. Then invokesnextInt()
, limiting the result to be greater that or equalorigin
and less thanbound
. Ifbound
is a power of two then limiting is a simple masking operation. Otherwise, the result is re-calculated by invokingnextInt()
until the result is greater than or equalorigin
and less thanbound
. - Parameters:
origin
- the least value that can be returnedbound
- the upper bound (exclusive) for the returned value- Returns:
- a pseudorandomly chosen
int
value between the origin (inclusive) and the bound (exclusive) - Throws:
IllegalArgumentException
- iforigin
is greater than or equal tobound
-
nextLong
long nextLong()Returns a pseudorandomly chosenlong
value.- Returns:
- a pseudorandomly chosen
long
value
-
nextLong
default long nextLong(long bound) Returns a pseudorandomly chosenlong
value between zero (inclusive) and the specified bound (exclusive).- Implementation Requirements:
- The default implementation checks that
bound
is a positivelong
. Then invokesnextLong()
, limiting the result to be greater than or equal zero and less thanbound
. Ifbound
is a power of two then limiting is a simple masking operation. Otherwise, the result is re-calculated by invokingnextLong()
until the result is greater than or equal zero and less thanbound
. - Parameters:
bound
- the upper bound (exclusive) for the returned value. Must be positive.- Returns:
- a pseudorandomly chosen
long
value between zero (inclusive) and the bound (exclusive) - Throws:
IllegalArgumentException
- ifbound
is not positive
-
nextLong
default long nextLong(long origin, long bound) Returns a pseudorandomly chosenlong
value between the specified origin (inclusive) and the specified bound (exclusive).- Implementation Requirements:
- The default implementation checks that
origin
andbound
are positivelongs
. Then invokesnextLong()
, limiting the result to be greater than or equalorigin
and less thanbound
. Ifbound
is a power of two then limiting is a simple masking operation. Otherwise, the result is re-calculated by invokingnextLong()
until the result is greater than or equalorigin
and less thanbound
. - Parameters:
origin
- the least value that can be returnedbound
- the upper bound (exclusive) for the returned value- Returns:
- a pseudorandomly chosen
long
value between the origin (inclusive) and the bound (exclusive) - Throws:
IllegalArgumentException
- iforigin
is greater than or equal tobound
-
nextGaussian
default double nextGaussian()Returns adouble
value pseudorandomly chosen from a Gaussian (normal) distribution whose mean is 0 and whose standard deviation is 1.- Implementation Requirements:
- 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.
- Returns:
- a
double
value pseudorandomly chosen from a Gaussian distribution
-
nextGaussian
default double nextGaussian(double mean, double stddev) Returns adouble
value pseudorandomly chosen from a Gaussian (normal) distribution with a mean and standard deviation specified by the arguments.- Implementation Requirements:
- 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.
- Parameters:
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 from- Returns:
- a
double
value pseudorandomly chosen from the specified Gaussian distribution - Throws:
IllegalArgumentException
- ifstddev
is negative
-
nextExponential
default double nextExponential()Returns a nonnegativedouble
value pseudorandomly chosen from an exponential distribution whose mean is 1.- Implementation Requirements:
- 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.
- Returns:
- a nonnegative
double
value pseudorandomly chosen from an exponential distribution
-