RandomGenerator.SplittableGenerator (Java SE 26 & JDK 26)
Description: declaration: module: java.base, package: java.util.random, interface: RandomGenerator, interface: SplittableGenerator
Keywords: java.util.random.RandomGenerator.SplittableGenerator interface

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

Since:
  17

- ## Nested Class Summary

  ### Nested classes/interfaces declared in interface RandomGenerator

  `RandomGenerator.ArbitrarilyJumpableGenerator, RandomGenerator.JumpableGenerator, RandomGenerator.LeapableGenerator, RandomGenerator.SplittableGenerator, RandomGenerator.StreamableGenerator`
  Modifier and Type
  Interface
  Description
  `static interface`
  `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.
  `static interface`
  `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. 264) to a distant point in the state cycle.
  `static interface`
  `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. 2128), to a very distant point in the state cycle.
  `static interface`
  `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).
  `static interface`
  `RandomGenerator.StreamableGenerator`
  The `RandomGenerator.StreamableGenerator` interface augments the `RandomGenerator` interface to provide methods that return streams of `RandomGenerator` objects.

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

  `doubles, doubles, doubles, doubles, equiDoubles, 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`
  Modifier and Type
  Method
  Description
  `default DoubleStream`
  `doubles()`
  Returns an effectively unlimited stream of pseudorandomly chosen `double` values.
  `default DoubleStream`
  `doubles(double randomNumberOrigin, double randomNumberBound)`
  Returns an effectively unlimited stream of pseudorandomly chosen `double` 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 given `streamSize` number of pseudorandomly chosen `double` values.
  `default DoubleStream`
  `doubles(long streamSize, double randomNumberOrigin, double randomNumberBound)`
  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).
  `default DoubleStream`
  `equiDoubles(double left, double right, boolean isLeftIncluded, boolean isRightIncluded)`
  Returns an effectively unlimited stream of pseudorandomly chosen `double` values, where each value is between the specified `left` boundary and the specified `right` boundary.
  `default IntStream`
  `ints()`
  Returns an effectively unlimited stream of pseudorandomly chosen `int` values.
  `default IntStream`
  `ints(int randomNumberOrigin, int randomNumberBound)`
  Returns an effectively unlimited stream of pseudorandomly chosen `int` 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 given `streamSize` number of pseudorandomly chosen `int` values.
  `default IntStream`
  `ints(long streamSize, int randomNumberOrigin, int randomNumberBound)`
  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).
  `default boolean`
  `isDeprecated()`
  Return true if the implementation of RandomGenerator (algorithm) has been marked for deprecation.
  `default LongStream`
  `longs()`
  Returns an effectively unlimited stream of pseudorandomly chosen `long` values.
  `default LongStream`
  `longs(long streamSize)`
  Returns a stream producing the given `streamSize` number of pseudorandomly chosen `long` values.
  `default LongStream`
  `longs(long randomNumberOrigin, long randomNumberBound)`
  Returns an effectively unlimited stream of pseudorandomly chosen `long` 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 given `streamSize` number of pseudorandomly chosen `long` values, where each value is between the specified origin (inclusive) and the specified bound (exclusive).
  `default boolean`
  `nextBoolean()`
  Returns a pseudorandomly chosen `boolean` 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`
  `nextDouble()`
  Returns a pseudorandom `double` value between zero (inclusive) and one (exclusive).
  `default double`
  `nextDouble(double bound)`
  Returns a pseudorandomly chosen `double` value between zero (inclusive) and the specified bound (exclusive).
  `default double`
  `nextDouble(double origin, double bound)`
  Returns a pseudorandomly chosen `double` value between the specified origin (inclusive) and the specified bound (exclusive).
  `default double`
  `nextExponential()`
  Returns a nonnegative `double` value pseudorandomly chosen from an exponential distribution whose mean is 1.
  `default float`
  `nextFloat()`
  Returns a pseudorandom `float` value between zero (inclusive) and one (exclusive).
  `default float`
  `nextFloat(float bound)`
  Returns a pseudorandomly chosen `float` value between zero (inclusive) and the specified bound (exclusive).
  `default float`
  `nextFloat(float origin, float bound)`
  Returns a pseudorandomly chosen `float` value between the specified origin (inclusive) and the specified bound (exclusive).
  `default double`
  `nextGaussian()`
  Returns a `double` 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 a `double` value pseudorandomly chosen from a Gaussian (normal) distribution with a mean and standard deviation specified by the arguments.
  `default int`
  `nextInt()`
  Returns a pseudorandomly chosen `int` value.
  `default int`
  `nextInt(int bound)`
  Returns a pseudorandomly chosen `int` value between zero (inclusive) and the specified bound (exclusive).
  `default int`
  `nextInt(int origin, int bound)`
  Returns a pseudorandomly chosen `int` value between the specified origin (inclusive) and the specified bound (exclusive).
  `long`
  `nextLong()`
  Returns a pseudorandomly chosen `long` value.
  `default long`
  `nextLong(long bound)`
  Returns a pseudorandomly chosen `long` value between zero (inclusive) and the specified bound (exclusive).
  `default long`
  `nextLong(long origin, long bound)`
  Returns a pseudorandomly chosen `long` value between the specified origin (inclusive) and the specified bound (exclusive).

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