Added in API level VanillaIceCream

RandomGeneratorFactory

class RandomGeneratorFactory<T : RandomGenerator!>

kotlin.Any
↳	java.util.random.RandomGeneratorFactory

This is a factory class for generating multiple random number generators of a specific algorithm. RandomGeneratorFactory also provides methods for selecting random number generator algorithms. A specific RandomGeneratorFactory can be located by using the RandomGeneratorFactory#of(String) method, where the argument string is the name of the algorithm required. The method RandomGeneratorFactory#all() produces a non-empty Stream of all available RandomGeneratorFactorys that can be searched to locate a RandomGeneratorFactory suitable to the task. There are three methods for constructing a RandomGenerator instance, depending on the type of initial seed required. RandomGeneratorFactory#create(long) is used for long seed construction, RandomGeneratorFactory#create(byte[]) is used for byte[] seed construction, and RandomGeneratorFactory#create() is used for random seed construction. Example;

<code>RandomGeneratorFactory&lt;RandomGenerator&gt; factory = RandomGeneratorFactory.of("Random");
 
      for (int i = 0; i &lt; 10; i++) {
          new Thread(() -&gt; {
              RandomGenerator random = factory.create(100L);
              System.out.println(random.nextDouble());
          }).start();
      }
  </code>

RandomGeneratorFactory also provides methods describing the attributes (or properties) of a generator and can be used to select random number generator algorithms. These methods are typically used in conjunction with RandomGeneratorFactory#all(). In this example, the code locates the RandomGeneratorFactory that produces RandomGenerators with the highest number of state bits.

<code>RandomGeneratorFactory&lt;RandomGenerator&gt; best = RandomGeneratorFactory.all()
          .sorted(Comparator.comparingInt(RandomGenerator::stateBits).reversed())
          .findFirst()
          .orElse(RandomGeneratorFactory.of("Random"));
      System.out.println(best.name() + " in " + best.group() + " was selected");
 
      RandomGenerator rng = best.create();
      System.out.println(rng.nextLong());
  </code>

Summary

Public methods
static Stream<RandomGeneratorFactory<RandomGenerator!>!>!	`all()` Returns a non-empty stream of available `RandomGeneratorFactory(s)`.
T	`create()` Create an instance of `RandomGenerator` based on algorithm chosen.
T	`create(seed: Long)` Create an instance of `RandomGenerator` based on algorithm chosen providing a starting long seed.
T	`create(seed: ByteArray!)` Create an instance of `RandomGenerator` based on algorithm chosen providing a starting byte[] seed.
Int	`equidistribution()` Returns the equidistribution of the algorithm.
static RandomGeneratorFactory<RandomGenerator!>!	`getDefault()` Returns a `RandomGeneratorFactory` meeting the minimal requirement of having an algorithm whose state bits are greater than or equal 64.
String!	`group()` Return the group name of the algorithm used by the random number generator.
Boolean	`isArbitrarilyJumpable()` Return true if random generator can jump an arbitrarily specified distant point in the state cycle.
Boolean	`isDeprecated()` Return true if the implementation of RandomGenerator (algorithm) has been marked for deprecation.
Boolean	`isHardware()` Return true if random generator uses a hardware device (HRNG) to produce entropic input.
Boolean	`isJumpable()` Return true if random generator can jump a specified distant point in the state cycle.
Boolean	`isLeapable()` Return true if random generator is jumpable and can leap to a very distant point in the state cycle.
Boolean	`isSplittable()` Return true if random generator can be cloned into a separate object with the same properties but positioned further in the state cycle.
Boolean	`isStatistical()` Return true if random generator is computed using an arithmetic algorithm and is statistically deterministic.
Boolean	`isStochastic()` Return true if random generator is computed using external or entropic sources as inputs.
Boolean	`isStreamable()` Return true if random generator can be used to create `Streams` of random numbers.
String!	`name()` Return the name of the algorithm used by the random number generator.
static RandomGeneratorFactory<T>!	`of(name: String!)` Returns a `RandomGeneratorFactory` that can produce instances of `RandomGenerator` that utilize the `name` algorithm.
BigInteger!	`period()` Return the period of the algorithm used by the random number generator.
Int	`stateBits()` Returns number of bits used by the algorithm to maintain state of seed.

Public methods

all

Added in API level VanillaIceCream

static fun all(): Stream<RandomGeneratorFactory<RandomGenerator!>!>!

Returns a non-empty stream of available RandomGeneratorFactory(s). RandomGenerators that are marked as deprecated are not included in the result.

Return
`Stream<RandomGeneratorFactory<RandomGenerator!>!>!`	a non-empty stream of all available `RandomGeneratorFactory(s)`.

create

Added in API level VanillaIceCream

fun create(): T

Create an instance of RandomGenerator based on algorithm chosen.

Return
`T`	new in instance of `RandomGenerator`.

create

Added in API level VanillaIceCream

fun create(seed: Long): T

Create an instance of RandomGenerator based on algorithm chosen providing a starting long seed. If long seed is not supported by an algorithm then the no argument form of create is used.

Parameters
`seed`	Long: long random seed value.

Return
`T`	new in instance of `RandomGenerator`.

create

Added in API level VanillaIceCream

fun create(seed: ByteArray!): T

Create an instance of RandomGenerator based on algorithm chosen providing a starting byte[] seed. If byte[] seed is not supported by an algorithm then the no argument form of create is used.

Parameters
`seed`	ByteArray!: byte array random seed value.

Return
`T`	new in instance of `RandomGenerator`.

Exceptions
`java.lang.NullPointerException`	if seed is null.

equidistribution

Added in API level VanillaIceCream

fun equidistribution(): Int

Returns the equidistribution of the algorithm.

Return
`Int`	the equidistribution of the algorithm.

getDefault

Added in API level VanillaIceCream

static fun getDefault(): RandomGeneratorFactory<RandomGenerator!>!

Returns a RandomGeneratorFactory meeting the minimal requirement of having an algorithm whose state bits are greater than or equal 64.

Return
`RandomGeneratorFactory<RandomGenerator!>!`	a `RandomGeneratorFactory`

group

Added in API level VanillaIceCream

fun group(): String!

Return the group name of the algorithm used by the random number generator.

Return
`String!`	Group name of the algorithm.

isArbitrarilyJumpable

Added in API level VanillaIceCream

fun isArbitrarilyJumpable(): Boolean

Return true if random generator can jump an arbitrarily specified distant point in the state cycle.

Return
`Boolean`	true if random generator is arbitrarily jumpable.

isDeprecated

Added in API level VanillaIceCream

fun isDeprecated(): Boolean

Return true if the implementation of RandomGenerator (algorithm) has been marked for deprecation.

Return
`Boolean`	true if the implementation of RandomGenerator (algorithm) has been marked for deprecation

isHardware

Added in API level VanillaIceCream

fun isHardware(): Boolean

Return true if random generator uses a hardware device (HRNG) to produce entropic input.

Return
`Boolean`	true if random generator is generated by hardware.

isJumpable

Added in API level VanillaIceCream

fun isJumpable(): Boolean

Return true if random generator can jump a specified distant point in the state cycle.

Return
`Boolean`	true if random generator is jumpable.

isLeapable

Added in API level VanillaIceCream

fun isLeapable(): Boolean

Return true if random generator is jumpable and can leap to a very distant point in the state cycle.

Return
`Boolean`	true if random generator is leapable.

isSplittable

Added in API level VanillaIceCream

fun isSplittable(): Boolean

Return true if random generator can be cloned into a separate object with the same properties but positioned further in the state cycle.

Return
`Boolean`	true if random generator is splittable.

isStatistical

Added in API level VanillaIceCream

fun isStatistical(): Boolean

Return true if random generator is computed using an arithmetic algorithm and is statistically deterministic.

Return
`Boolean`	true if random generator is statistical.

isStochastic

Added in API level VanillaIceCream

fun isStochastic(): Boolean

Return true if random generator is computed using external or entropic sources as inputs.

Return
`Boolean`	true if random generator is stochastic.

isStreamable

Added in API level VanillaIceCream

fun isStreamable(): Boolean

Return true if random generator can be used to create Streams of random numbers.

Return
`Boolean`	true if random generator is streamable.

name

Added in API level VanillaIceCream

fun name(): String!

Return the name of the algorithm used by the random number generator.

Return
`String!`	Name of the algorithm.

of

Added in API level VanillaIceCream

static fun <T : RandomGenerator!> of(name: String!): RandomGeneratorFactory<T>!

Returns a RandomGeneratorFactory that can produce instances of RandomGenerator that utilize the name algorithm.

Parameters
`name`	String!: Name of random number generator algorithm
`<T>`	Sub-interface of `RandomGenerator` to produce

Return
`RandomGeneratorFactory<T>!`	`RandomGeneratorFactory` of `RandomGenerator`

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

period

Added in API level VanillaIceCream

fun period(): BigInteger!

Return the period of the algorithm used by the random number generator. Returns BigInteger.ZERO if period is not determinable.

Return
`BigInteger!`	BigInteger period.

stateBits

Added in API level VanillaIceCream

fun stateBits(): Int

Returns number of bits used by the algorithm to maintain state of seed.

Return
`Int`	number of bits used by the algorithm to maintain state of seed.