- All Superinterfaces:
RandomGenerator,RandomGenerator.StreamableGenerator
- All Known Implementing Classes:
SplittableRandom
- Enclosing interface:
RandomGenerator
public static interface RandomGenerator.SplittableGenerator
extends RandomGenerator.StreamableGenerator
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).
Ideally, all RandomGenerator.SplittableGenerator objects produced by
recursive splitting from a single original RandomGenerator.SplittableGenerator
object are statistically independent of one another and individually
uniform. Therefore we would expect the set of values collectively
generated by a set of such objects to have the same statistical
properties as if the same quantity of values were generated by a single
thread using a single RandomGenerator.SplittableGenerator object. In practice,
one must settle for some approximation to independence and uniformity.
Methods are provided to perform a single splitting operation and also to produce a stream of generators split off from the original (by either iterative or recursive splitting, or a combination).
Objects that implement RandomGenerator.SplittableGenerator are typically not
cryptographically secure. Consider instead using SecureRandom to
get a cryptographically secure pseudo-random number generator for use by
security-sensitive applications.
-
Nested Class Summary
Nested classes/interfaces declared in interface java.util.random.RandomGenerator
RandomGenerator.ArbitrarilyJumpableGenerator, RandomGenerator.JumpableGenerator, RandomGenerator.LeapableGenerator, RandomGenerator.SplittableGenerator, RandomGenerator.StreamableGenerator -
Method Summary
Modifier and TypeMethodDescriptiondefault Stream<RandomGenerator> rngs()Returns an effectively unlimited stream of new pseudorandom number generators, each of which implements theRandomGeneratorinterface.default Stream<RandomGenerator> rngs(long streamSize) Returns a stream producing the givenstreamSizenumber of new pseudorandom number generators, each of which implements theRandomGeneratorinterface.split()Returns a new pseudorandom number generator, split off from this one, that implements theRandomGeneratorandRandomGenerator.SplittableGeneratorinterfaces.Returns a new pseudorandom number generator, split off from this one, that implements theRandomGeneratorandRandomGenerator.SplittableGeneratorinterfaces.splits()Returns an effectively unlimited stream of new pseudorandom number generators, each of which implements theRandomGenerator.SplittableGeneratorinterface.splits(long streamSize) Returns a stream producing the givenstreamSizenumber of new pseudorandom number generators, each of which implements theRandomGenerator.SplittableGeneratorinterface.splits(long streamSize, RandomGenerator.SplittableGenerator source) Returns a stream producing the givenstreamSizenumber of new pseudorandom number generators, each of which implements theRandomGenerator.SplittableGeneratorinterface.Returns an effectively unlimited stream of new pseudorandom number generators, each of which implements theRandomGenerator.SplittableGeneratorinterface.Methods declared in interface java.util.random.RandomGenerator
doubles, doubles, doubles, doubles, ints, ints, ints, ints, isDeprecated, longs, longs, longs, longs, nextBoolean, nextBytes, nextDouble, nextDouble, nextDouble, nextExponential, nextFloat, nextFloat, nextFloat, nextGaussian, nextGaussian, nextInt, nextInt, nextInt, nextLong, nextLong, nextLong
-
Method Details
-
of
- Parameters:
name- Name of random number generator algorithm- Returns:
- An instance of
RandomGenerator.SplittableGenerator - Throws:
NullPointerException- if name is nullIllegalArgumentException- if the named algorithm is not found
-
split
Returns a new pseudorandom number generator, split off from this one, that implements theRandomGeneratorandRandomGenerator.SplittableGeneratorinterfaces.This pseudorandom number generator may be used as a source of pseudorandom bits used to initialize the state of the new one.
- Returns:
- a new object that implements the
RandomGeneratorandRandomGenerator.SplittableGeneratorinterfaces
-
split
Returns a new pseudorandom number generator, split off from this one, that implements theRandomGeneratorandRandomGenerator.SplittableGeneratorinterfaces.- Parameters:
source- aRandomGenerator.SplittableGeneratorinstance to be used instead of this one as a source of pseudorandom bits used to initialize the state of the new ones.- Returns:
- an object that implements the
RandomGeneratorandRandomGenerator.SplittableGeneratorinterfaces - Throws:
NullPointerException- if source is null
-
splits
Returns an effectively unlimited stream of new pseudorandom number generators, each of which implements theRandomGenerator.SplittableGeneratorinterface.This pseudorandom number generator may be used as a source of pseudorandom bits used to initialize the state the new ones.
- Implementation Requirements:
- The default implementation invokes
splits(this). - Implementation Note:
- It is permitted to implement this method in a manner
equivalent to
splits(Long.MAX_VALUE). - Returns:
- a stream of
RandomGenerator.SplittableGeneratorobjects
-
splits
Returns a stream producing the givenstreamSizenumber of new pseudorandom number generators, each of which implements theRandomGenerator.SplittableGeneratorinterface.This pseudorandom number generator may be used as a source of pseudorandom bits used to initialize the state the new ones.
- Parameters:
streamSize- the number of values to generate- Returns:
- a stream of
RandomGenerator.SplittableGeneratorobjects - Throws:
IllegalArgumentException- ifstreamSizeis less than zero
-
splits
Returns an effectively unlimited stream of new pseudorandom number generators, each of which implements theRandomGenerator.SplittableGeneratorinterface.- Implementation Note:
- It is permitted to implement this method in a manner
equivalent to
splits(Long.MAX_VALUE, source). - Parameters:
source- aRandomGenerator.SplittableGeneratorinstance to be used instead of this one as a source of pseudorandom bits used to initialize the state of the new ones.- Returns:
- a stream of
RandomGenerator.SplittableGeneratorobjects - Throws:
NullPointerException- if source is null
-
splits
Stream<RandomGenerator.SplittableGenerator> splits(long streamSize, RandomGenerator.SplittableGenerator source) Returns a stream producing the givenstreamSizenumber of new pseudorandom number generators, each of which implements theRandomGenerator.SplittableGeneratorinterface.- Parameters:
streamSize- the number of values to generatesource- aRandomGenerator.SplittableGeneratorinstance to be used instead of this one as a source of pseudorandom bits used to initialize the state of the new ones.- Returns:
- a stream of
RandomGenerator.SplittableGeneratorobjects - Throws:
IllegalArgumentException- ifstreamSizeis less than zeroNullPointerException- if source is null
-
rngs
Returns an effectively unlimited stream of new pseudorandom number generators, each of which implements theRandomGeneratorinterface. Ideally the generators in the stream will appear to be statistically independent.- Specified by:
rngsin interfaceRandomGenerator.StreamableGenerator- Implementation Requirements:
- The default implementation calls
splits(). - Returns:
- a stream of objects that implement the
RandomGeneratorinterface
-
rngs
Returns a stream producing the givenstreamSizenumber of new pseudorandom number generators, each of which implements theRandomGeneratorinterface. Ideally the generators in the stream will appear to be statistically independent.- Specified by:
rngsin interfaceRandomGenerator.StreamableGenerator- Implementation Requirements:
- The default implementation calls
splits(streamSize). - Parameters:
streamSize- the number of generators to generate- Returns:
- a stream of objects that implement the
RandomGeneratorinterface - Throws:
IllegalArgumentException- ifstreamSizeis less than zero
-