tomo/examples/random

Random Number Generators (RNG)

This library provides an RNG type (Random Number Generator). This type represents a self-contained piece of data that encapsulates the state of a relatively fast and relatively secure pseudo-random number generator. The current implementation is based on the ChaCha20 stream cipher, inspired by arc4random in OpenBSD.

An RNG object can be used for deterministic, repeatable generation of pseudorandom numbers (for example, to be used in a video game for creating seeded levels). The default random number generator for Tomo is called random and is, by default, initialized with random data from the operating system when a Tomo program launches.

RNG Functions

This documentation provides details on RNG functions available in the API. Arrays also have some methods which use RNG values: array:shuffle(), array:shuffled(), array:random(), and array:sample().

• func bool(rng: RNG, p: Num = 0.5 -> Bool)
• func byte(rng: RNG -> Byte)
• func bytes(rng: RNG, count: Int -> [Byte])
• func copy(rng: RNG -> RNG)
• [func int(rng: RNG, min: Int, max: Int -> Int)](#int, int64, int32, int16, int8)
• func new(seed: [Byte] = (/dev/urandom):read_bytes(40)! -> RNG)
• [func num(rng: RNG, min: Num = 0.0, max: Num = 1.0 -> Num)](#num, num32)

---

bool

Generate a random boolean value with a given probability.

func bool(rng: RNG, p: Num = 0.5 -> Bool)

• rng: The random number generator to use.
• p: The probability of returning a yes value. Values less than zero and NaN values are treated as equal to zero and values larger than zero are treated as equal to one.

Returns:
yes with probability p and no with probability 1-p.

Example:

>> random:bool()
= no
>> random:bool(1.0)
= yes

---

byte

Generate a random byte with uniform probability.

func byte(rng: RNG -> Byte)

• rng: The random number generator to use.

Returns:
A random byte (0-255).

Example:

>> random:byte()
= 103[B]

---

bytes

Generate an array of uniformly random bytes with the given length.

func bytes(rng: RNG, count: Int -> [Byte])

• rng: The random number generator to use.
• count: The number of random bytes to return.

Returns:
An array of length count random bytes with uniform random distribution (0-255).

Example:

>> random:bytes(4)
= [135[B], 169[B], 103[B], 212[B]]

---

copy

Return a copy of a random number generator. This copy will be a parallel version of the given RNG with its own internal state.

func copy(rng: RNG -> RNG)

• rng: The random number generator to copy.

Returns:
A copy of the given RNG.

Example:

>> rng := RNG.new([:Byte])
>> copy := rng:copy()

>> rng:bytes(10)
= [224[B], 102[B], 190[B], 59[B], 251[B], 50[B], 217[B], 170[B], 15[B], 221[B]]

# The copy runs in parallel to the original RNG:
>> copy:bytes(10)
= [224[B], 102[B], 190[B], 59[B], 251[B], 50[B], 217[B], 170[B], 15[B], 221[B]]

---

int, int64, int32, int16, int8

Generate a random integer value with the given range.

func int(rng: RNG, min: Int, max: Int -> Int)
func int64(rng: RNG, min: Int64 = Int64.min, max: Int64 = Int64.max -> Int)
func int32(rng: RNG, min: Int32 = Int32.min, max: Int32 = Int32.max -> Int)
func int16(rng: RNG, min: Int16 = Int16.min, max: Int16 = Int16.max -> Int)
func int8(rng: RNG, min: Int8 = Int8.min, max: Int8 = Int8.max -> Int)

• rng: The random number generator to use.
• min: The minimum value to be returned.
• max: The maximum value to be returned.

Returns:
An integer uniformly chosen from the range [min, max] (inclusive). If min is greater than max, an error will be raised.

Example:

>> random:int(1, 10)
= 8

---

new

Return a new random number generator.

func new(seed: [Byte] = (/dev/urandom):read_bytes(40)! -> RNG)

• seed: The seed use for the random number generator. A seed length of 40 bytes is recommended. Seed lengths of less than 40 bytes are padded with zeroes.

Returns:
A new random number generator.

Example:

>> my_rng := RNG.new([1[B], 2[B], 3[B], 4[B]])
>> my_rng:bool()
= yes

---

num, num32

Generate a random floating point value with the given range.

func num(rng: RNG, min: Num = 0.0, max: Num = 1.0 -> Int)
func num32(rng: RNG, min: Num = 0.0_f32, max: Num = 1.0_f32 -> Int)

• rng: The random number generator to use.
• min: The minimum value to be returned.
• max: The maximum value to be returned.

Returns:
A floating point number uniformly chosen from the range [min, max] (inclusive). If min is greater than max, an error will be raised.

Example:

>> random:num(1, 10)
= 9.512830439975572