kex docs Standard Library

Random

module Random

Random values for simulations, sampling, games, and reproducible tests.

Import with using Random. Ordinary calls return a value directly; a Random.Generator returns (value, nextGenerator). Reusing the same generator replays the same draw. Pass its returned state to continue.

These generators are not cryptographic; do not use their output for secrets. Random.secureBytes and Random.token are, and are what secrets come from.

Examples

Roll a die or initialize a weight

using Random
let roll = Random.integer(1..6)
let weight = Random.float(-1.0..1.0)

Reproduce a sequence

let generator = Random.seeded(42)
let (first, afterFirst) = generator.integer(1..6)
let (second, afterSecond) = afterFirst.integer(1..6)

seeded

seeded(seed: Integer) -> Generator

Starts a deterministic sequence. Any Integer seed is reduced modulo 2^64.

Parameters
seed
reproducible seed, including negative or large values

Returns initial state; no draw has been consumed

fresh

fresh : Generator

Starts a generator using fresh host entropy.

Returns initial state for a sequence that varies between runs

integer

integer(range: Range<Integer>) -> Integer

Draws an integer from an inclusive range using fresh entropy.

Parameters
range
ascending inclusive bounds, span at most 2^64

Returns drawn value

float

float(range: Range<Float> = …) -> Float

Draws a float; defaults to [0.0, 1.0). The upper bound is excluded.

Parameters
range
finite, strictly ascending bounds

Returns drawn value

boolean

boolean : Bool

Draws a fair coin flip using fresh entropy.

Returns true or false with equal probability

chance?

chance?(probability: Float) -> Bool

Returns true with the supplied probability using fresh entropy.

Parameters
probability
probability from 0.0 through 1.0

Returns sampled outcome

choice

choice(items: [X]) -> X?

Chooses a position uniformly, returning None for an empty input.

Parameters
items
values to choose from

Returns chosen value, if any

sample

sample(items: [X], count: Integer) -> [X]

Samples positions without replacement; duplicate values remain possible.

Parameters
items
population
count
nonnegative count; capped at the input size

Returns values selected in random order

shuffle

shuffle(items: [X]) -> [X]

Returns a random permutation using fresh entropy.

Parameters
items
values to shuffle

Returns shuffled copy

secureBytes

secureBytes(count: Integer) -> Binary

Returns count bytes from the operating system's cryptographically secure generator: the source for keys, session tokens and unguessable identifiers, which the generators above must never be used for.

Nothing about it is reproducible, and there is no Generator form.

Parameters
count
how many bytes; zero or less gives an empty binary

Returns the random bytes

Examples

A 256-bit key

let key = Random.secureBytes(32)

token

token(bytes: Integer = …) -> String

Returns an unguessable token: bytes secure random bytes, as lowercase hex, so the text is twice as long as bytes.

Parameters
bytes
how many random bytes the token carries

Returns the token

Examples

A session identifier

let session = Random.token(32)   # => "9f86d081884c7d65..." (64 characters)

record Generator

Immutable state of a deterministic random sequence.

Construct with Random.seeded or Random.fresh. Each draw returns its value first and the advanced generator second. Equal seeds reproduce equal sequences for the same operations on both backends.

Fields

state
Integer optional

module Random.Generator

type Random.Generator

integer

integer(range: Range<Integer>) -> (Integer, Generator)

Draws an integer between both endpoints, with the advanced generator. The range must be ascending and contain at most 2^64 integers. A singleton range is valid and still consumes a draw.

Parameters
range
inclusive integer bounds

Returns drawn integer and advanced state

Examples

A reproducible die roll

let (roll, advanced) = Random.seeded(42).integer(1..6)

float

float(range: Range<Float>) -> (Float, Generator)

Draws a float from the lower bound inclusive to the upper bound exclusive. Defaults to 0.0..1.0. Bounds must be finite and strictly ascending.

Parameters
range
half-open floating-point bounds

Returns drawn float and advanced state

Examples

Initialize a model weight

let (weight, advanced) = Random.seeded(42).float(-1.0..1.0)

boolean

boolean : (Bool, Generator)

Draws a fair Boolean and returns the advanced generator.

Returns coin flip and advanced state

chance?

chance?(probability: Float) -> (Bool, Generator)

Draws true with the supplied probability. Consumes one draw even at 0 or 1.

Parameters
probability
probability from 0.0 through 1.0

Returns outcome and advanced state

choice

choice(items: [X]) -> (X?, Generator)

Chooses an input position uniformly. Empty input returns None without a draw.

Parameters
items
values to choose from

Returns optional value and advanced state

sample

sample(items: [X], count: Integer) -> ([X], Generator)

Selects input positions without replacement, in random order. Duplicate input values may appear more than once in the result. A count larger than the input selects every position; zero consumes no draws.

Parameters
items
population; unchanged by sampling
count
nonnegative number of positions to select

Returns selected values and advanced state

Examples

Deal five cards reproducibly

let (hand, advanced) = Random.seeded(42).sample(cards, count: 5)

shuffle

shuffle(items: [X]) -> ([X], Generator)

Returns a random permutation, preserving duplicates and the input itself. Empty input consumes no draws.

Parameters
items
values to shuffle

Returns permutation and advanced state