RandomGenerator
interface RandomGenerator
java.util.random.RandomGenerator |
The 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 23 for float
values and 52 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 SplittableGenerator
or 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.
Summary
Nested classes | |
---|---|
abstract |
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. |
abstract |
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. 2 |
abstract |
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. 2 |
abstract |
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). |
abstract |
The |
Public methods | |
---|---|
open DoubleStream! |
doubles() Returns an effectively unlimited stream of pseudorandomly chosen |
open DoubleStream! |
Returns an effectively unlimited stream of pseudorandomly chosen |
open DoubleStream! |
Returns a stream producing the given |
open DoubleStream! |
Returns a stream producing the given |
open static RandomGenerator! |
Returns a |
open IntStream! |
ints() Returns an effectively unlimited stream of pseudorandomly chosen |
open IntStream! |
Returns an effectively unlimited stream of pseudorandomly chosen |
open IntStream! |
Returns a stream producing the given |
open IntStream! |
Returns a stream producing the given |
open Boolean |
Return true if the implementation of RandomGenerator (algorithm) has been marked for deprecation. |
open LongStream! |
longs() Returns an effectively unlimited stream of pseudorandomly chosen |
open LongStream! |
Returns an effectively unlimited stream of pseudorandomly chosen |
open LongStream! |
Returns a stream producing the given |
open LongStream! |
Returns a stream producing the given |
open Boolean |
Returns a pseudorandomly chosen |
open Unit |
Fills a user-supplied byte array with generated byte values pseudorandomly chosen uniformly from the range of values between -128 (inclusive) and 127 (inclusive). |
open Double |
Returns a pseudorandom |
open Double |
nextDouble(bound: Double) Returns a pseudorandomly chosen |
open Double |
nextDouble(origin: Double, bound: Double) Returns a pseudorandomly chosen |
open Double |
Returns a nonnegative |
open Float |
Returns a pseudorandom |
open Float |
Returns a pseudorandomly chosen |
open Float |
Returns a pseudorandomly chosen |
open Double |
Returns a |
open Double |
nextGaussian(mean: Double, stddev: Double) Returns a |
open Int |
nextInt() Returns a pseudorandomly chosen |
open Int |
Returns a pseudorandomly chosen |
open Int |
Returns a pseudorandomly chosen |
abstract Long |
nextLong() Returns a pseudorandomly chosen |
open Long |
Returns a pseudorandomly chosen |
open Long |
Returns a pseudorandomly chosen |
open static RandomGenerator! |
Returns an instance of |
Public methods
doubles
open fun doubles(): DoubleStream!
Returns an effectively unlimited stream of pseudorandomly chosen double
values.
Return | |
---|---|
DoubleStream! |
a stream of pseudorandomly chosen double values |
doubles
open fun doubles(
randomNumberOrigin: Double,
randomNumberBound: Double
): DoubleStream!
Returns an effectively unlimited stream of pseudorandomly chosen double
values, where each value is between the specified origin (inclusive) and the specified bound (exclusive).
Parameters | |
---|---|
randomNumberOrigin |
Double: the least value that can be produced |
randomNumberBound |
Double: the upper bound (exclusive) for each value produced |
Return | |
---|---|
DoubleStream! |
a stream of pseudorandomly chosen double values, each between the specified origin (inclusive) and the specified bound (exclusive) |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if randomNumberOrigin is not finite, or randomNumberBound is not finite, or randomNumberOrigin is greater than or equal to randomNumberBound |
doubles
open fun doubles(streamSize: Long): DoubleStream!
Returns a stream producing the given streamSize
number of pseudorandomly chosen double
values.
Parameters | |
---|---|
streamSize |
Long: the number of values to generate |
Return | |
---|---|
DoubleStream! |
a stream of pseudorandomly chosen double values |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if streamSize is less than zero |
doubles
open fun doubles(
streamSize: Long,
randomNumberOrigin: Double,
randomNumberBound: Double
): DoubleStream!
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).
Parameters | |
---|---|
streamSize |
Long: the number of values to generate |
randomNumberOrigin |
Double: the least value that can be produced |
randomNumberBound |
Double: the upper bound (exclusive) for each value produced |
Return | |
---|---|
DoubleStream! |
a stream of pseudorandomly chosen double values, each between the specified origin (inclusive) and the specified bound (exclusive) |
Exceptions | |
---|---|
java.lang.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 |
getDefault
open static fun getDefault(): RandomGenerator!
Returns a RandomGenerator
meeting the minimal requirement of having an algorithm whose state bits are greater than or equal 64.
Return | |
---|---|
RandomGenerator! |
a RandomGenerator |
ints
open fun ints(): IntStream!
Returns an effectively unlimited stream of pseudorandomly chosen int
values.
Return | |
---|---|
IntStream! |
a stream of pseudorandomly chosen int values |
ints
open fun ints(
randomNumberOrigin: Int,
randomNumberBound: Int
): IntStream!
Returns an effectively unlimited stream of pseudorandomly chosen int
values, where each value is between the specified origin (inclusive) and the specified bound (exclusive).
Parameters | |
---|---|
randomNumberOrigin |
Int: the least value that can be produced |
randomNumberBound |
Int: the upper bound (exclusive) for each value produced |
Return | |
---|---|
IntStream! |
a stream of pseudorandomly chosen int values, each between the specified origin (inclusive) and the specified bound (exclusive) |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if randomNumberOrigin is greater than or equal to randomNumberBound |
ints
open fun ints(streamSize: Long): IntStream!
Returns a stream producing the given streamSize
number of pseudorandomly chosen int
values.
Parameters | |
---|---|
streamSize |
Long: the number of values to generate |
Return | |
---|---|
IntStream! |
a stream of pseudorandomly chosen int values |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if streamSize is less than zero |
ints
open fun ints(
streamSize: Long,
randomNumberOrigin: Int,
randomNumberBound: Int
): IntStream!
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).
Parameters | |
---|---|
streamSize |
Long: the number of values to generate |
randomNumberOrigin |
Int: the least value that can be produced |
randomNumberBound |
Int: the upper bound (exclusive) for each value produced |
Return | |
---|---|
IntStream! |
a stream of pseudorandomly chosen int values, each between the specified origin (inclusive) and the specified bound (exclusive) |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if streamSize is less than zero, or randomNumberOrigin is greater than or equal to randomNumberBound |
isDeprecated
open fun isDeprecated(): Boolean
Return true if the implementation of RandomGenerator (algorithm) has been marked for deprecation.
Return | |
---|---|
Boolean |
true if the implementation of RandomGenerator (algorithm) has been marked for deprecation |
longs
open fun longs(): LongStream!
Returns an effectively unlimited stream of pseudorandomly chosen long
values.
Return | |
---|---|
LongStream! |
a stream of pseudorandomly chosen long values |
longs
open fun longs(
randomNumberOrigin: Long,
randomNumberBound: Long
): LongStream!
Returns an effectively unlimited stream of pseudorandomly chosen long
values, where each value is between the specified origin (inclusive) and the specified bound (exclusive).
Parameters | |
---|---|
randomNumberOrigin |
Long: the least value that can be produced |
randomNumberBound |
Long: the upper bound (exclusive) for each value produced |
Return | |
---|---|
LongStream! |
a stream of pseudorandomly chosen long values, each between the specified origin (inclusive) and the specified bound (exclusive) |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if randomNumberOrigin is greater than or equal to randomNumberBound |
longs
open fun longs(streamSize: Long): LongStream!
Returns a stream producing the given streamSize
number of pseudorandomly chosen long
values.
Parameters | |
---|---|
streamSize |
Long: the number of values to generate |
Return | |
---|---|
LongStream! |
a stream of pseudorandomly chosen long values |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if streamSize is less than zero |
longs
open fun longs(
streamSize: Long,
randomNumberOrigin: Long,
randomNumberBound: Long
): LongStream!
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).
Parameters | |
---|---|
streamSize |
Long: the number of values to generate |
randomNumberOrigin |
Long: the least value that can be produced |
randomNumberBound |
Long: the upper bound (exclusive) for each value produced |
Return | |
---|---|
LongStream! |
a stream of pseudorandomly chosen long values, each between the specified origin (inclusive) and the specified bound (exclusive) |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if streamSize is less than zero, or randomNumberOrigin is greater than or equal to randomNumberBound |
nextBoolean
open fun nextBoolean(): Boolean
Returns a pseudorandomly chosen 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.
Return | |
---|---|
Boolean |
a pseudorandomly chosen boolean value |
nextBytes
open fun nextBytes(bytes: ByteArray!): Unit
Fills a user-supplied byte array with generated byte values pseudorandomly chosen uniformly from the range of values between -128 (inclusive) and 127 (inclusive).
Parameters | |
---|---|
bytes |
ByteArray!: the byte array to fill with pseudorandom bytes |
Exceptions | |
---|---|
java.lang.NullPointerException |
if bytes is null |
nextDouble
open fun nextDouble(): Double
Returns a pseudorandom double
value between zero (inclusive) and one (exclusive).
Return | |
---|---|
Double |
a pseudorandom double value between zero (inclusive) and one (exclusive) |
nextDouble
open fun nextDouble(bound: Double): Double
Returns a pseudorandomly chosen double
value between zero (inclusive) and the specified bound (exclusive).
Parameters | |
---|---|
bound |
Double: the upper bound (exclusive) for the returned value. Must be positive and finite |
Return | |
---|---|
Double |
a pseudorandomly chosen double value between zero (inclusive) and the bound (exclusive) |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if bound is not both positive and finite |
nextDouble
open fun nextDouble(
origin: Double,
bound: Double
): Double
Returns a pseudorandomly chosen double
value between the specified origin (inclusive) and the specified bound (exclusive).
Parameters | |
---|---|
origin |
Double: the least value that can be returned |
bound |
Double: the upper bound (exclusive) for the returned value |
Return | |
---|---|
Double |
a pseudorandomly chosen double value between the origin (inclusive) and the bound (exclusive) |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if origin is not finite, or bound is not finite, or origin is greater than or equal to bound |
nextExponential
open fun nextExponential(): Double
Returns a nonnegative double
value pseudorandomly chosen from an exponential distribution whose mean is 1.
Return | |
---|---|
Double |
a nonnegative double value pseudorandomly chosen from an exponential distribution |
nextFloat
open fun nextFloat(): Float
Returns a pseudorandom float
value between zero (inclusive) and one (exclusive).
Return | |
---|---|
Float |
a pseudorandom float value between zero (inclusive) and one (exclusive) |
nextFloat
open fun nextFloat(bound: Float): Float
Returns a pseudorandomly chosen float
value between zero (inclusive) and the specified bound (exclusive).
Parameters | |
---|---|
bound |
Float: the upper bound (exclusive) for the returned value. Must be positive and finite |
Return | |
---|---|
Float |
a pseudorandomly chosen float value between zero (inclusive) and the bound (exclusive) |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if bound is not both positive and finite |
nextFloat
open fun nextFloat(
origin: Float,
bound: Float
): Float
Returns a pseudorandomly chosen float
value between the specified origin (inclusive) and the specified bound (exclusive).
Parameters | |
---|---|
origin |
Float: the least value that can be returned |
bound |
Float: the upper bound (exclusive) |
Return | |
---|---|
Float |
a pseudorandomly chosen float value between the origin (inclusive) and the bound (exclusive) |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if origin is not finite, or bound is not finite, or origin is greater than or equal to bound |
nextGaussian
open fun nextGaussian(): Double
Returns a double
value pseudorandomly chosen from a Gaussian (normal) distribution whose mean is 0 and whose standard deviation is 1.
Return | |
---|---|
Double |
a double value pseudorandomly chosen from a Gaussian distribution |
nextGaussian
open fun nextGaussian(
mean: Double,
stddev: Double
): Double
Returns a double
value pseudorandomly chosen from a Gaussian (normal) distribution with a mean and standard deviation specified by the arguments.
Parameters | |
---|---|
mean |
Double: the mean of the Gaussian distribution to be drawn from |
stddev |
Double: the standard deviation (square root of the variance) of the Gaussian distribution to be drawn from |
Return | |
---|---|
Double |
a double value pseudorandomly chosen from the specified Gaussian distribution |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if stddev is negative |
nextInt
open fun nextInt(): Int
Returns a pseudorandomly chosen int
value.
Return | |
---|---|
Int |
a pseudorandomly chosen int value |
nextInt
open fun nextInt(bound: Int): Int
Returns a pseudorandomly chosen int
value between zero (inclusive) and the specified bound (exclusive).
Parameters | |
---|---|
bound |
Int: the upper bound (exclusive) for the returned value. Must be positive. |
Return | |
---|---|
Int |
a pseudorandomly chosen int value between zero (inclusive) and the bound (exclusive) |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if bound is not positive |
nextInt
open fun nextInt(
origin: Int,
bound: Int
): Int
Returns a pseudorandomly chosen int
value between the specified origin (inclusive) and the specified bound (exclusive).
Parameters | |
---|---|
origin |
Int: the least value that can be returned |
bound |
Int: the upper bound (exclusive) for the returned value |
Return | |
---|---|
Int |
a pseudorandomly chosen int value between the origin (inclusive) and the bound (exclusive) |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if origin is greater than or equal to bound |
nextLong
abstract fun nextLong(): Long
Returns a pseudorandomly chosen long
value.
Return | |
---|---|
Long |
a pseudorandomly chosen long value |
nextLong
open fun nextLong(bound: Long): Long
Returns a pseudorandomly chosen long
value between zero (inclusive) and the specified bound (exclusive).
Parameters | |
---|---|
bound |
Long: the upper bound (exclusive) for the returned value. Must be positive. |
Return | |
---|---|
Long |
a pseudorandomly chosen long value between zero (inclusive) and the bound (exclusive) |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if bound is not positive |
nextLong
open fun nextLong(
origin: Long,
bound: Long
): Long
Returns a pseudorandomly chosen long
value between the specified origin (inclusive) and the specified bound (exclusive).
Parameters | |
---|---|
origin |
Long: the least value that can be returned |
bound |
Long: the upper bound (exclusive) for the returned value |
Return | |
---|---|
Long |
a pseudorandomly chosen long value between the origin (inclusive) and the bound (exclusive) |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if origin is greater than or equal to bound |
of
open static fun of(name: String!): RandomGenerator!
Returns an instance of RandomGenerator
that utilizes the name
algorithm.
Parameters | |
---|---|
name |
String!: Name of random number generator algorithm |
Return | |
---|---|
RandomGenerator! |
An instance of RandomGenerator |
Exceptions | |
---|---|
java.lang.NullPointerException |
if name is null |
java.lang.IllegalArgumentException |
if the named algorithm is not found |