Module java.base
Package java.util.random

# Interface RandomGenerator.SplittableGenerator

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 Type
Method
Description
`static RandomGenerator.SplittableGenerator`
`of(String name)`
Returns an instance of `RandomGenerator.SplittableGenerator` that utilizes the `name` algorithm.
`default Stream<RandomGenerator>`
`rngs()`
Returns an effectively unlimited stream of new pseudorandom number generators, each of which implements the `RandomGenerator` interface.
`default Stream<RandomGenerator>`
`rngs(long streamSize)`
Returns a stream producing the given `streamSize` number of new pseudorandom number generators, each of which implements the `RandomGenerator` interface.
`RandomGenerator.SplittableGenerator`
`split()`
Returns a new pseudorandom number generator, split off from this one, that implements the `RandomGenerator` and `RandomGenerator.SplittableGenerator` interfaces.
`RandomGenerator.SplittableGenerator`
`split(RandomGenerator.SplittableGenerator source)`
Returns a new pseudorandom number generator, split off from this one, that implements the `RandomGenerator` and `RandomGenerator.SplittableGenerator` interfaces.
`default Stream<RandomGenerator.SplittableGenerator>`
`splits()`
Returns an effectively unlimited stream of new pseudorandom number generators, each of which implements the `RandomGenerator.SplittableGenerator` interface.
`Stream<RandomGenerator.SplittableGenerator>`
`splits(long streamSize)`
Returns a stream producing the given `streamSize` number of new pseudorandom number generators, each of which implements the `RandomGenerator.SplittableGenerator` interface.
`Stream<RandomGenerator.SplittableGenerator>`
`splits(long streamSize, RandomGenerator.SplittableGenerator source)`
Returns a stream producing the given `streamSize` number of new pseudorandom number generators, each of which implements the `RandomGenerator.SplittableGenerator` interface.
`Stream<RandomGenerator.SplittableGenerator>`
`splits(RandomGenerator.SplittableGenerator source)`
Returns an effectively unlimited stream of new pseudorandom number generators, each of which implements the `RandomGenerator.SplittableGenerator` interface.

### 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

static RandomGenerator.SplittableGenerator of(String name)
Returns an instance of `RandomGenerator.SplittableGenerator` that utilizes the `name` algorithm.

Parameters:
  `name` - Name of random number generator algorithm
Returns:
  An instance of `RandomGenerator.SplittableGenerator`
Throws:
  `NullPointerException` - if name is null
  `IllegalArgumentException` - if the named algorithm is not found

### split

RandomGenerator.SplittableGenerator split()
Returns a new pseudorandom number generator, split off from this one, that implements the `RandomGenerator` and `RandomGenerator.SplittableGenerator` interfaces.

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 `RandomGenerator` and `RandomGenerator.SplittableGenerator` interfaces

### split

RandomGenerator.SplittableGenerator split(RandomGenerator.SplittableGenerator source)
Returns a new pseudorandom number generator, split off from this one, that implements the `RandomGenerator` and `RandomGenerator.SplittableGenerator` interfaces.

Parameters:
  `source` - a `RandomGenerator.SplittableGenerator` instance 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 `RandomGenerator` and `RandomGenerator.SplittableGenerator` interfaces
Throws:
  `NullPointerException` - if source is null

### splits

default Stream<RandomGenerator.SplittableGenerator> splits()
Returns an effectively unlimited stream of new pseudorandom number generators, each of which implements the `RandomGenerator.SplittableGenerator` interface.

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.SplittableGenerator` objects

### splits

Stream<RandomGenerator.SplittableGenerator> splits(long streamSize)
Returns a stream producing the given `streamSize` number of new pseudorandom number generators, each of which implements the `RandomGenerator.SplittableGenerator` interface.

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.SplittableGenerator` objects
Throws:
  `IllegalArgumentException` - if `streamSize` is less than zero

### splits

Stream<RandomGenerator.SplittableGenerator> splits(RandomGenerator.SplittableGenerator source)
Returns an effectively unlimited stream of new pseudorandom number generators, each of which implements the `RandomGenerator.SplittableGenerator` interface.

Implementation Note:
  It is permitted to implement this method in a manner equivalent to `splits` (`Long.MAX_VALUE`, source).
Parameters:
  `source` - a `RandomGenerator.SplittableGenerator` instance 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.SplittableGenerator` objects
Throws:
  `NullPointerException` - if source is null

### splits

Stream<RandomGenerator.SplittableGenerator> splits(long streamSize, RandomGenerator.SplittableGenerator source)
Returns a stream producing the given `streamSize` number of new pseudorandom number generators, each of which implements the `RandomGenerator.SplittableGenerator` interface.

Parameters:
  `streamSize` - the number of values to generate
  `source` - a `RandomGenerator.SplittableGenerator` instance 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.SplittableGenerator` objects
Throws:
  `IllegalArgumentException` - if `streamSize` is less than zero
  `NullPointerException` - if source is null

### rngs

default Stream<RandomGenerator> rngs()
Returns an effectively unlimited stream of new pseudorandom number generators, each of which implements the `RandomGenerator` interface. Ideally the generators in the stream will appear to be statistically independent.

Specified by:
  `rngs` in interface `RandomGenerator.StreamableGenerator`
Implementation Requirements:
  The default implementation calls `splits`().
Returns:
  a stream of objects that implement the `RandomGenerator` interface

### rngs

default Stream<RandomGenerator> rngs(long streamSize)
Returns a stream producing the given `streamSize` number of new pseudorandom number generators, each of which implements the `RandomGenerator` interface. Ideally the generators in the stream will appear to be statistically independent.

Specified by:
  `rngs` in interface `RandomGenerator.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 `RandomGenerator` interface
Throws:
  `IllegalArgumentException` - if `streamSize` is less than zero