Added in API level 35

RandomGenerator

interface RandomGenerator

java.util.random.RandomGenerator

Known Direct Subclasses Random, RandomGenerator.StreamableGenerator, SplittableRandom Random An instance of this class is used to generate a stream of pseudorandom numbers; its period is only 248. RandomGenerator.StreamableGenerator The StreamableGenerator interface augments the RandomGenerator interface to provide methods that return streams of RandomGenerator objects. SplittableRandom A generator of uniform pseudorandom values (with period 264) applicable for use in (among other contexts) isolated parallel computations that may generate subtasks.

Known Indirect Subclasses RandomGenerator.ArbitrarilyJumpableGenerator, RandomGenerator.JumpableGenerator, RandomGenerator.LeapableGenerator, RandomGenerator.SplittableGenerator, SecureRandom, SplittableRandom, ThreadLocalRandom 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. 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. 2 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. 2 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). SecureRandom This class provides a cryptographically strong random number generator (RNG). SplittableRandom A generator of uniform pseudorandom values (with period 264) applicable for use in (among other contexts) isolated parallel computations that may generate subtasks. ThreadLocalRandom A random number generator (with period 264) isolated to the current thread.

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	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.
abstract	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. 2
abstract	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. 2
abstract	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).
abstract	StreamableGenerator The StreamableGenerator interface augments the RandomGenerator interface to provide methods that return streams of RandomGenerator objects.

Public methods
open DoubleStream!	doubles() Returns an effectively unlimited stream of pseudorandomly chosen double values.
open DoubleStream!	doubles(randomNumberOrigin: Double, randomNumberBound: Double) Returns an effectively unlimited stream of pseudorandomly chosen double values, where each value is between the specified origin (inclusive) and the specified bound (exclusive).
open DoubleStream!	doubles(streamSize: Long) Returns a stream producing the given streamSize number of pseudorandomly chosen double values.
open DoubleStream!	doubles(streamSize: Long, randomNumberOrigin: Double, randomNumberBound: Double) 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).
open static RandomGenerator!	getDefault() Returns a RandomGenerator meeting the minimal requirement of having an algorithm whose state bits are greater than or equal 64.
open IntStream!	ints() Returns an effectively unlimited stream of pseudorandomly chosen int values.
open IntStream!	ints(randomNumberOrigin: Int, randomNumberBound: Int) Returns an effectively unlimited stream of pseudorandomly chosen int values, where each value is between the specified origin (inclusive) and the specified bound (exclusive).
open IntStream!	ints(streamSize: Long) Returns a stream producing the given streamSize number of pseudorandomly chosen int values.
open IntStream!	ints(streamSize: Long, randomNumberOrigin: Int, randomNumberBound: Int) 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).
open Boolean	isDeprecated() Return true if the implementation of RandomGenerator (algorithm) has been marked for deprecation.
open LongStream!	longs() Returns an effectively unlimited stream of pseudorandomly chosen long values.
open LongStream!	longs(streamSize: Long) Returns a stream producing the given streamSize number of pseudorandomly chosen long values.
open LongStream!	longs(randomNumberOrigin: Long, randomNumberBound: Long) Returns an effectively unlimited stream of pseudorandomly chosen long values, where each value is between the specified origin (inclusive) and the specified bound (exclusive).
open LongStream!	longs(streamSize: Long, randomNumberOrigin: Long, randomNumberBound: Long) 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).
open Boolean	nextBoolean() Returns a pseudorandomly chosen boolean value.
open Unit	nextBytes(bytes: ByteArray!) 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	nextDouble() Returns a pseudorandom double value between zero (inclusive) and one (exclusive).
open Double	nextDouble(bound: Double) Returns a pseudorandomly chosen double value between zero (inclusive) and the specified bound (exclusive).
open Double	nextDouble(origin: Double, bound: Double) Returns a pseudorandomly chosen double value between the specified origin (inclusive) and the specified bound (exclusive).
open Double	nextExponential() Returns a nonnegative double value pseudorandomly chosen from an exponential distribution whose mean is 1.
open Float	nextFloat() Returns a pseudorandom float value between zero (inclusive) and one (exclusive).
open Float	nextFloat(bound: Float) Returns a pseudorandomly chosen float value between zero (inclusive) and the specified bound (exclusive).
open Float	nextFloat(origin: Float, bound: Float) Returns a pseudorandomly chosen float value between the specified origin (inclusive) and the specified bound (exclusive).
open Double	nextGaussian() Returns a double value pseudorandomly chosen from a Gaussian (normal) distribution whose mean is 0 and whose standard deviation is 1.
open Double	nextGaussian(mean: Double, stddev: Double) Returns a double value pseudorandomly chosen from a Gaussian (normal) distribution with a mean and standard deviation specified by the arguments.
open Int	nextInt() Returns a pseudorandomly chosen int value.
open Int	nextInt(bound: Int) Returns a pseudorandomly chosen int value between zero (inclusive) and the specified bound (exclusive).
open Int	nextInt(origin: Int, bound: Int) Returns a pseudorandomly chosen int value between the specified origin (inclusive) and the specified bound (exclusive).
abstract Long	nextLong() Returns a pseudorandomly chosen long value.
open Long	nextLong(bound: Long) Returns a pseudorandomly chosen long value between zero (inclusive) and the specified bound (exclusive).
open Long	nextLong(origin: Long, bound: Long) Returns a pseudorandomly chosen long value between the specified origin (inclusive) and the specified bound (exclusive).
open static RandomGenerator!	of(name: String!) Returns an instance of RandomGenerator that utilizes the name algorithm.

Public methods

doubles

Added in API level 35

open fun doubles(): DoubleStream!

Returns an effectively unlimited stream of pseudorandomly chosen double values.

Return
DoubleStream!	a stream of pseudorandomly chosen double values

doubles

Added in API level 35

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

Added in API level 35

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

Added in API level 35

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

Added in API level 35

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

Added in API level 35

open fun ints(): IntStream!

Returns an effectively unlimited stream of pseudorandomly chosen int values.

Return
IntStream!	a stream of pseudorandomly chosen int values

ints

Added in API level 35

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

Added in API level 35

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

Added in API level 35

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

Added in API level 35

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

Added in API level 35

open fun longs(): LongStream!

Returns an effectively unlimited stream of pseudorandomly chosen long values.

Return
LongStream!	a stream of pseudorandomly chosen long values

longs

Added in API level 35

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

Added in API level 35

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

Added in API level 35

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

Added in API level 35

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

Added in API level 35

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

Added in API level 35

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

Added in API level 35

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

Added in API level 35

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

Added in API level 35

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

Added in API level 35

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

Added in API level 35

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

Added in API level 35

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

Added in API level 35

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

Added in API level 35

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

Added in API level 35

open fun nextInt(): Int

Returns a pseudorandomly chosen int value.

Return
Int	a pseudorandomly chosen int value

nextInt

Added in API level 35

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

Added in API level 35

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

Added in API level 35

abstract fun nextLong(): Long

Returns a pseudorandomly chosen long value.

Return
Long	a pseudorandomly chosen long value

nextLong

Added in API level 35

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

Added in API level 35

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

Added in API level 35

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