# RandomGenerator.LeapableGenerator

Added in[API level 35](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)

# LeapableGenerator

```
interface LeapableGenerator : RandomGenerator.JumpableGenerator
```

|----------------------------------------------------------------------------------------------------------------------------------------------------------|
| [java.util.random.RandomGenerator.LeapableGenerator](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.LeapableGenerator#) |

|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Known Direct Subclasses [RandomGenerator.ArbitrarilyJumpableGenerator](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.ArbitrarilyJumpableGenerator) |--------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [RandomGenerator.ArbitrarilyJumpableGenerator](https://developer.android.com/reference/kotlin/java/util/random/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. | |

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[LeapableGenerator](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.LeapableGenerator#)objects by iterative leaping from a single original[LeapableGenerator](https://developer.android.com/reference/kotlin/java/util/random/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[LeapableGenerator](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.LeapableGenerator#)objects produced by iterative leaping and jumping from a single original[LeapableGenerator](https://developer.android.com/reference/kotlin/java/util/random/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[JumpableGenerator](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.JumpableGenerator)interface but need not also implement the[LeapableGenerator](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.LeapableGenerator#)interface. A typical strategy for a multithreaded application is to create a single[LeapableGenerator](https://developer.android.com/reference/kotlin/java/util/random/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](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.JumpableGenerator#jump())() method of each such generator be called to produce a substream of generator objects.

Objects that implement[LeapableGenerator](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.LeapableGenerator#)are typically not cryptographically secure. Consider instead using[SecureRandom](https://developer.android.com/reference/kotlin/java/security/SecureRandom.html#)to get a cryptographically secure pseudo-random number generator for use by security-sensitive applications.

## Summary

|                                                                                                                                                                                                                                                                                                                                                                Public methods                                                                                                                                                                                                                                                                                                                                                                 ||
|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| abstract[RandomGenerator.LeapableGenerator](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.LeapableGenerator#)!                                                                                       | [copy](https://developer.android.com/reference/kotlin/java/util/random/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).                                                                                                                                                                                             |
| open[RandomGenerator.JumpableGenerator](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.JumpableGenerator)!                                                                                            | [copyAndLeap](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.LeapableGenerator#copyAndLeap())`()` Copy this generator, leap this generator forward, then return the copy.                                                                                                                                                                                                                                                                                            |
| abstract[Unit](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/index.html)                                                                                                                                                   | [leap](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.LeapableGenerator#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.                                                                                                                                                                                                                              |
| abstract[Double](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-double/index.html)                                                                                                                                               | [leapDistance](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.LeapableGenerator#leapDistance())`()` Returns the distance by which the[leap](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.LeapableGenerator#leap())() method will leap forward within the state cycle of this generator object.                                                                                                                                    |
| open[Stream](https://developer.android.com/reference/kotlin/java/util/stream/Stream.html#)\<[RandomGenerator.JumpableGenerator](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.JumpableGenerator)!\>! | [leaps](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.LeapableGenerator#leaps())`()` Returns an effectively unlimited stream of new pseudorandom number generators, each of which implements the[JumpableGenerator](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.JumpableGenerator)interface.                                                                                                                                    |
| open[Stream](https://developer.android.com/reference/kotlin/java/util/stream/Stream.html#)\<[RandomGenerator.JumpableGenerator](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.JumpableGenerator)!\>! | [leaps](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.LeapableGenerator#leaps(kotlin.Long))`(`streamSize:` `[Long](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-long/index.html)`)` Returns a stream producing the given`streamSize`number of new pseudorandom number generators, each of which implements the[JumpableGenerator](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.JumpableGenerator)interface.              |
| openstatic[RandomGenerator.LeapableGenerator](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.LeapableGenerator#)!                                                                                     | [of](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.LeapableGenerator#of(kotlin.String))`(`name:` `[String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)!`)` Returns an instance of[LeapableGenerator](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.LeapableGenerator#)that utilizes the`name`[algorithm](https://developer.android.com/reference/kotlin/java/util/random/package-summary#algorithms). |

| Inherited functions ||
|---|---|
| From class[JumpableGenerator](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.JumpableGenerator) |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [RandomGenerator](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator)!                                                                                          | [copyAndJump](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.JumpableGenerator#copyAndJump())`()` <br /> Copy this generator, jump this generator forward, then return the copy. <br />                                                                                                                                                                                                                                                                                                                                           | | [Unit](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/index.html)                                                                                                                 | [jump](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.JumpableGenerator#jump())`()` <br /> 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. <br />                                                                                                                                                                                                                                                                             | | [Double](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-double/index.html)                                                                                                             | [jumpDistance](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.JumpableGenerator#jumpDistance())`()` <br /> Returns the distance by which the[jump](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.JumpableGenerator#jump())() method will jump forward within the state cycle of this generator object. <br />                                                                                                                                                                                   | | [Stream](https://developer.android.com/reference/kotlin/java/util/stream/Stream.html#)<[RandomGenerator](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator)!>! | [jumps](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.JumpableGenerator#jumps())`()` <br /> Returns an effectively unlimited stream of new pseudorandom number generators, each of which implements the[RandomGenerator](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator)interface. <br />                                                                                                                                                                                                       | | [Stream](https://developer.android.com/reference/kotlin/java/util/stream/Stream.html#)<[RandomGenerator](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator)!>! | [jumps](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.JumpableGenerator#jumps(kotlin.Long))`(`streamSize:` `[Long](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-long/index.html)`)` <br /> Returns a stream producing the given`streamSize`number of new pseudorandom number generators, each of which implements the[RandomGenerator](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator)interface. <br />                                                                                 | | [Stream](https://developer.android.com/reference/kotlin/java/util/stream/Stream.html#)<[RandomGenerator](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator)!>! | [rngs](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.JumpableGenerator#rngs())`()` <br /> Returns an effectively unlimited stream of new pseudorandom number generators, each of which implements the[RandomGenerator](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator)interface. Ideally the generators in the stream will appear to be statistically independent. <br />                                                                                                                       | | [Stream](https://developer.android.com/reference/kotlin/java/util/stream/Stream.html#)<[RandomGenerator](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator)!>! | [rngs](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.JumpableGenerator#rngs(kotlin.Long))`(`streamSize:` `[Long](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-long/index.html)`)` <br /> Returns a stream producing the given`streamSize`number of new pseudorandom number generators, each of which implements the[RandomGenerator](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator)interface. Ideally the generators in the stream will appear to be statistically independent. <br /> | ||

## Public methods

### copy

Added in[API level 35](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)  

```
abstract fun copy(): RandomGenerator.LeapableGenerator!
```

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

|                                                                                         Return                                                                                          ||
|------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------|
| [RandomGenerator.LeapableGenerator](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.LeapableGenerator#)! | a new object that is a copy of this generator |

### copyAndLeap

Added in[API level 35](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)  

```
open fun copyAndLeap(): RandomGenerator.JumpableGenerator!
```

Copy this generator, leap this generator forward, then return the copy.

|                                                                                              Return                                                                                               ||
|-----------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------|
| [RandomGenerator.JumpableGenerator](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.JumpableGenerator)! | a copy of this generator object before the leap occurred |

### leap

Added in[API level 35](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)  

```
abstract fun leap(): Unit
```

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

Added in[API level 35](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)  

```
abstract fun leapDistance(): Double
```

Returns the distance by which the[leap](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.LeapableGenerator#leap())() method will leap forward within the state cycle of this generator object.

|                                                             Return                                                              ||
|----------------------------------------------------------------------------------|-----------------------------------------------|
| [Double](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-double/index.html) | the default leap distance (as a`double`value) |

### leaps

Added in[API level 35](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)  

```
open fun leaps(): Stream<RandomGenerator.JumpableGenerator!>!
```

Returns an effectively unlimited stream of new pseudorandom number generators, each of which implements the[JumpableGenerator](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.JumpableGenerator)interface.

|                                                                                                                                                                                                 Return                                                                                                                                                                                                  ||
|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Stream](https://developer.android.com/reference/kotlin/java/util/stream/Stream.html#)<[RandomGenerator.JumpableGenerator](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.JumpableGenerator)!>! | a stream of objects that implement the[JumpableGenerator](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.JumpableGenerator)interface |

### leaps

Added in[API level 35](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)  

```
open fun leaps(streamSize: Long): Stream<RandomGenerator.JumpableGenerator!>!
```

Returns a stream producing the given`streamSize`number of new pseudorandom number generators, each of which implements the[JumpableGenerator](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.JumpableGenerator)interface.

|                                                           Parameters                                                            ||
|--------------|-------------------------------------------------------------------------------------------------------------------|
| `streamSize` | [Long](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-long/index.html):the number of generators to generate |

|                                                                                                                                                                                                 Return                                                                                                                                                                                                  ||
|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Stream](https://developer.android.com/reference/kotlin/java/util/stream/Stream.html#)<[RandomGenerator.JumpableGenerator](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.JumpableGenerator)!>! | a stream of objects that implement the[JumpableGenerator](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.JumpableGenerator)interface |

|                              Exceptions                               ||
|--------------------------------------|---------------------------------|
| `java.lang.IllegalArgumentException` | if`streamSize`is less than zero |

### of

Added in[API level 35](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)  

```
open static fun of(name: String!): RandomGenerator.LeapableGenerator!
```

Returns an instance of[LeapableGenerator](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.LeapableGenerator#)that utilizes the`name`[algorithm](https://developer.android.com/reference/kotlin/java/util/random/package-summary#algorithms).

|                                                                                                            Parameters                                                                                                            ||
|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `name` | [String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)!:Name of random number generator[algorithm](https://developer.android.com/reference/kotlin/java/util/random/package-summary#algorithms) |

|                                                                                                                                     Return                                                                                                                                      ||
|------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------|
| [RandomGenerator.LeapableGenerator](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.LeapableGenerator#)! | An instance of[LeapableGenerator](https://developer.android.com/reference/kotlin/java/util/random/RandomGenerator.LeapableGenerator#) |

|                                Exceptions                                 ||
|--------------------------------------|-------------------------------------|
| `java.lang.NullPointerException`     | if name is null                     |
| `java.lang.IllegalArgumentException` | if the named algorithm is not found |