# Interface RandomGenerator.LeapableGenerator

All Superinterfaces:
  `RandomGenerator, RandomGenerator.JumpableGenerator, RandomGenerator.StreamableGenerator`

All Known Subinterfaces:
  `RandomGenerator.ArbitrarilyJumpableGenerator`

Enclosing interface:
  `RandomGenerator`

public static interface RandomGenerator.LeapableGenerator extends RandomGenerator.JumpableGenerator
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. Typically one will construct a series of `RandomGenerator.LeapableGenerator` objects by iterative leaping from a single original `RandomGenerator.LeapableGenerator` object, and then for each such object produce a subseries of objects by iterative jumping. There is little conceptual difference between leaping and jumping, but typically a leap will be a very long jump in the state cycle (perhaps distance 2128 or so).

Ideally, all `RandomGenerator.LeapableGenerator` objects produced by iterative leaping and jumping from a single original `RandomGenerator.LeapableGenerator` object are statistically independent of one another and individually uniform. In practice, one must settle for some approximation to independence and uniformity. In particular, a specific implementation may assume that each generator in a stream produced by the `leaps` method is used to produce (by jumping) a number of objects no larger than 264. Implementors are advised to use algorithms whose period is at least 2191.

Methods are provided to perform a single leap operation and also to produce a stream of generators produced from the original by iterative copying and leaping of internal state. The generators produced must implement the `RandomGenerator.JumpableGenerator` interface but need not also implement the `RandomGenerator.LeapableGenerator` interface. A typical strategy for a multithreaded application is to create a single `RandomGenerator.LeapableGenerator` object, calls its `leaps` method exactly once, and then parcel out generators from the resulting stream, one to each thread. Then the `jump`() method of each such generator be called to produce a substream of generator objects.

Objects that implement `RandomGenerator.LeapableGenerator` 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
`RandomGenerator.LeapableGenerator`
`copy()`
Returns a new generator whose internal state is an exact copy of this generator (therefore their future behavior should be identical if subjected to the same series of operations).
`default RandomGenerator.JumpableGenerator`
`copyAndLeap()`
Copy this generator, leap this generator forward, then return the copy.
`void`
`leap()`
Alter the state of this pseudorandom number generator so as to leap forward a large, fixed distance (typically 296 or more) within its state cycle.
`double`
`leapDistance()`
Returns the distance by which the `leap`() method will leap forward within the state cycle of this generator object.
`default Stream<RandomGenerator.JumpableGenerator>`
`leaps()`
Returns an effectively unlimited stream of new pseudorandom number generators, each of which implements the `RandomGenerator.JumpableGenerator` interface.
`default Stream<RandomGenerator.JumpableGenerator>`
`leaps(long streamSize)`
Returns a stream producing the given `streamSize` number of new pseudorandom number generators, each of which implements the `RandomGenerator.JumpableGenerator` interface.
`static RandomGenerator.LeapableGenerator`
`of(String name)`
Returns an instance of `RandomGenerator.LeapableGenerator` that utilizes the `name` algorithm.

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

### Methods declared in interface RandomGenerator.JumpableGenerator

`copyAndJump, jump, jumpDistance, jumps, jumps, rngs, rngs`
Modifier and Type
Method
Description
`default RandomGenerator`
`copyAndJump()`
Copy this generator, jump this generator forward, then return the copy.
`void`
`jump()`
Alter the state of this pseudorandom number generator so as to jump forward a large, fixed distance (typically 264 or more) within its state cycle.
`double`
`jumpDistance()`
Returns the distance by which the `jump`() method will jump forward within the state cycle of this generator object.
`default Stream<RandomGenerator>`
`jumps()`
Returns an effectively unlimited stream of new pseudorandom number generators, each of which implements the `RandomGenerator` interface.
`default Stream<RandomGenerator>`
`jumps(long streamSize)`
Returns a stream producing the given `streamSize` number of new pseudorandom number generators, each of which implements the `RandomGenerator` interface.
`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.

## Method Details

### of

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

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

### copy

RandomGenerator.LeapableGenerator copy()
Returns a new generator whose internal state is an exact copy of this generator (therefore their future behavior should be identical if subjected to the same series of operations).

Specified by:
  `copy` in interface `RandomGenerator.JumpableGenerator`
Returns:
  a new object that is a copy of this generator

### leap

void leap()
Alter the state of this pseudorandom number generator so as to leap forward a large, fixed distance (typically 296 or more) within its state cycle.

### leapDistance

double leapDistance()
Returns the distance by which the `leap`() method will leap forward within the state cycle of this generator object.

Returns:
  the default leap distance (as a `double` value)

### leaps

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

Implementation Requirements:
  The default implementation produces a sequential stream that repeatedly calls `copy`() and `leap`() on this generator, and the copies become the generators produced by the stream.
Implementation Note:
  It is permitted to implement this method in a manner equivalent to `leaps` (`Long.MAX_VALUE`).
Returns:
  a stream of objects that implement the `RandomGenerator.JumpableGenerator` interface

### leaps

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

Implementation Requirements:
  The default implementation produces a sequential stream that repeatedly calls `copy`() and `leap`() on this generator, and the copies become the generators produced by the stream.
Parameters:
  `streamSize` - the number of generators to generate
Returns:
  a stream of objects that implement the `RandomGenerator.JumpableGenerator` interface
Throws:
  `IllegalArgumentException` - if `streamSize` is less than zero

### copyAndLeap

default RandomGenerator.JumpableGenerator copyAndLeap()
Copy this generator, leap this generator forward, then return the copy.

Implementation Requirements:
  The default implementation copies this, leaps and then returns the copy.
Returns:
  a copy of this generator object before the leap occurred