Random
Module random
import random
| Module | random |
| Source | random/helpers.zirr, random/module-docs.zirr, random/operations.zirr, random/random.zirr |
Randomness as a value, so a test can pin it down.
A Source is a value carrying four functions, and every function here takes one as its first argument. Which source you pass decides where the bits come from; the code using it does not change.
seeded(n) is the only source built here, and it produces the same sequence every run. The two drawing on the host live in os, which is where everything reaching the machine enters: os.fastRandom() is seeded from the clock, and os.strongRandom() is the host’s cryptographic generator.
HasFastRandom and HasStrongRandom are separate attributes so that code needing secrecy has to say so, and cannot be handed a seeded generator by mistake.
Dependencies
Contents
- Data —
Source - Attributes —
HasFastRandom,HasStrongRandom - Functions —
bool,bytes,choice,float,floatBetween,int,intBetween,seeded,shuffle
Data
Source
`random/random.zirr:17`
data Source {
int: fn(Int) -> Int
float: fn() -> Float
bytes: fn(Int) -> Binary
bool: fn() -> Bool
}
A source of randomness. The constructors differ only in where the bits come from, so code written against a Source works with any of them.
Each field has a matching module function taking the source first, which is usually the nicer way to call it.
Fields
| Field | Description |
|---|---|
int |
|
float |
|
bytes |
|
bool |
Attributes
HasFastRandom
`random/random.zirr:5`
attr HasFastRandom {
random(self: @HasFastRandom) -> Source
}
Provides a fast source of randomness, for simulations, sampling and anything else where predictability is not a hazard.
A seeded source satisfies this, which is what lets a test pin down behaviour that depends on randomness.
Fields
| Field | Description |
|---|---|
random |
HasStrongRandom
`random/random.zirr:11`
attr HasStrongRandom {
random(self: @HasStrongRandom) -> Source
}
Provides a cryptographically strong source of randomness, for tokens, keys and anything an adversary should not predict.
Kept apart from HasFastRandom so that code needing secrecy says so, and cannot be handed a seeded generator by mistake.
Fields
| Field | Description |
|---|---|
random |
Functions
bool
`random/operations.zirr:21`
fn bool(source: Source) -> Bool
Returns true or false with equal likelihood.
bytes
`random/operations.zirr:16`
fn bytes(source: Source, count: Int) -> Binary
Returns count random bytes.
choice
`random/helpers.zirr:16`
fn choice(source: Source, items: [Any]) -> Option
Returns one element of items, or None if items is empty.
float
`random/operations.zirr:11`
fn float(source: Source) -> Float
Returns a number from 0 up to but excluding 1.
floatBetween
`random/helpers.zirr:11`
fn floatBetween(source: Source, low: Float, high: Float) -> Float
Returns a number from low up to but excluding high.
int
`random/operations.zirr:6`
fn int(source: Source, bound: Int) -> Int
Returns a whole number from 0 up to but excluding bound, which must be above zero.
intBetween
`random/helpers.zirr:6`
fn intBetween(source: Source, low: Int, high: Int) -> Int
Returns a whole number from low up to but excluding high.
seeded
`random/random.zirr:27`
extern fn seeded(seed: Int) -> Source
A generator seeded with the given value, producing the same sequence every run.
This is what makes code using randomness testable: pass a seeded source and the outcome is fixed.
It is the only source this module builds; the two that draw on the host are os.fastRandom and os.strongRandom.
shuffle
`random/helpers.zirr:24`
fn shuffle(source: Source, items: [Any]) -> [Any]
Returns items in a new order, leaving the original untouched.
