rand

Random integer sampling, string generation, selection, and shuffling.

Functions

Samples a uniformly distributed integer from the half-open range [0, end).

Name	Type	Description
`end`	`Int`	exclusive upper bound

Int - Sampled integer

Exception	Condition
`TypeError`	`end` is not an integer
`ValueError`	`end <= 0`

assert_eq (int 1) 0
let n = int 10
assert ((n >= 0) && (n < 10))

Samples a uniformly distributed integer from the half-open range [start, end).

Name	Type	Description
`end`	`Int`	exclusive upper bound
`start`	`Int`	lower bound

Int - Sampled integer

Exception	Condition
`TypeError`	`start` or `end` is not an integer
`ValueError`	`end <= start`

assert_eq (int 0 1) 0
let n = int 20 10
assert ((n >= 10) && (n < 20))
assert_eq (int -4 -5) -5

Generates a random string by sampling characters from alphabet.

Name	Type	Description
`len`	`Int`	number of characters to emit
`alphabet`	`str?`	characters to sample from

Str - Randomly generated text

Exception	Condition
`TypeError`	`len` is not an integer or `alphabet` is not a string
`ValueError`	`len` is negative
`ValueError`	`alphabet` is empty

alphabet is interpreted as characters, not raw UTF-8 bytes.

If alphabet: is omitted, it defaults to the URL-safe NanoID alphabet: _-0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ.

let token = string 12
assert_eq $token.len 12

let text = string 4 alphabet: "åß"
assert_eq $text.len 8

Selects one random element from an array.

Name	Type	Description
`collection`	`array`	source array

One element from collection

Exception	Condition
`TypeError`	`collection` is not an array
`ValueError`	`collection` is empty

let item = pick [1, 2, 3]
assert ([1, 2, 3].contains $item)

Shuffles an array in place using a uniform Fisher-Yates pass.

Name	Type	Description
`array`	`array`	array to mutate

nil

Exception	Condition
`TypeError`	`array` is not an array

let items = [1, 2, 3, 4]
shuffle $items
let sorted = [...items]
sorted.sort()
assert_eq $sorted [1, 2, 3, 4]