vercel-labs--zerolang/docs/articles/modules/rand.md

When To Use std.rand

In Zerolang, use std.rand for deterministic random sources and target-gated entropy.

Runnable today:

API	Return	Notes
std.rand.seed(value)	RandSource	Creates a deterministic test source.
std.rand.nextU32(&mut source)	u32	Advances an explicit random source.
std.rand.nextBool(&mut source)	Bool	Advances an explicit random source and returns one random bit.
std.rand.nextBelow(&mut source, bound)	Maybe<u32>	Returns a value in [0, bound) using rejection sampling, or null when bound is zero.
std.rand.rangeU32(&mut source, low, high)	Maybe<u32>	Returns a value in [low, high) using rejection sampling, or null for an empty range.
std.rand.entropyU32()	u32	Reads target entropy where the target provides it.
std.rand.entropySeed()	RandSource	Creates a RandSource from target entropy where available.
std.rand.entropyHex32(buffer)	Maybe<Span<u8>>	Writes an 8-byte lowercase entropy ID into caller storage.

Metadata labels:

• effects: rand
• allocation behavior: no allocation; entropyHex32 writes caller-provided storage
• target support: deterministic source is target-neutral; entropy requires a rand-capable target
• error behavior: bounded helpers return null for invalid bounds; entropyHex32 returns null when storage is too small
• ownership notes: deterministic helpers mutate the caller-owned source
• example: examples/std-platform.graph

Example

pub fn main(world: World) -> Void raises {
    var rng: RandSource = std.rand.seed(7_u32)
    let first: u32 = std.rand.nextU32(&mut rng)
    let second: Bool = std.rand.nextBool(&mut rng)
    let bounded: Maybe<u32> = std.rand.nextBelow(&mut rng, 10_u32)
    let ranged: Maybe<u32> = std.rand.rangeU32(&mut rng, 40_u32, 50_u32)
    var id_buf: [8]u8 = [0_u8; 8]
    let entropy_id: Maybe<Span<u8>> = std.rand.entropyHex32(id_buf)
    if first == 1025555898_u32 && second && bounded.has && ranged.has && entropy_id.has {
        check world.out.write("rand ok\n")
    }
}

Design Notes

Zero keeps random sources explicit. Deterministic tests use std.rand.seed; bounded helpers use rejection sampling so the range is not modulo-biased. Caller-facing IDs use entropyHex32 when target entropy is available.

Production entropy stays target-capability-gated.