random

Utilities for generating random values in Koto.

At the core of the module is the Rng type, which is a seedable random number generator. Each thread has access to a generator with a randomly selected seed, or unique generators can be created with random.generator.

bool

|| -> Bool

Generates a random bool using the current thread's generator.

Example

# Seed the thread Rng so that we get predictable results
random.seed 99

random.bool()
# -> false
random.bool()
# -> true

generator

|| -> Rng

Creates an Rng with a randomly generated seed.

|Number| -> Rng

Creates an Rng with a specified seed.

Example

rng = random.generator 99
rng.pick (1, 2, 3)
# -> 3
rng.bool()
# -> false

number

|| -> Number

Generates a random number using the current thread's generator.

The number will be a floating point value in the range from 0 up to but not including 1.

Example

# Seed the thread Rng so that we get predictable results
random.seed 123

# Print random floats up to 3 decimal places
print '{random.number():.3}'
# -> 0.853
print '{random.number():.3}'
# -> 0.168

pick

|Indexable| -> Any?

Selects a random value from the input using the current thread's generator.

• If the input is empty, then null will be returned.
• If the input is a map, then a tuple containing the key and value of a randomly selected entry will be returned.
• If the input is a range, then the result will be an integer within the given range.
• If the input is some other indexable type (like a list or tuple), then a randomly selected element from the input will be returned.

Example

# Seed the thread Rng so that we get predictable results
random.seed -1

random.pick (123, -1, 99)
# -> 99
random.pick 10..20
# -> 14
random.pick {foo: 42, bar: 99, baz: 123}
# -> ('bar', 99)
random.pick []
# -> null

seed

|Number| -> Null

Seeds the current thread's generator so that it produces predictable results.

Example

from iterator import generate
from random import pick, seed

# Returns a tuple containing three numbers from 1 to 10
pick_3 = || generate(3, || pick 1..=10).to_tuple()

seed 1
pick_3()
# -> (5, 3, 8)

seed 2
pick_3()
# -> (6, 9, 3)

seed 1
pick_3()
# -> (5, 3, 8)

shuffle

|Indexable| -> Any

Reorders the entries in a container so that they have a new randomly shuffled order, and returns the container.

from random import seed, shuffle

x = [1, 2, 3, 4, 5]

seed 2
shuffle x
# -> [4, 1, 2, 3, 5]
shuffle x
# -> [5, 2, 4, 3, 1]

y = {a: 1, b: 2, c: 3}
shuffle y
# -> {b: 2, a: 1, c: 3}
shuffle y
# -> {a: 1, c: 3, b: 2}

Rng

Rng is the random module's core random generator.

The ChaCha algorithm with 8 rounds from the rand_chacha crate is used to generate random values. See the implementation's docs for more information.

Rng.bool

See random.bool.

Rng.number

See random.number.

Rng.pick

See random.pick.

Rng.shuffle

See random.shuffle.

Rng.seed

See random.seed.