RandomNumberGenerator

public protocol RandomNumberGenerator

A source of pseudo-random UInt64 values. Implementers expose a single raw-uniform primitive; the extension on this protocol layers ergonomic helpers on top.

Conformers are free to choose any algorithm they like — the protocol makes no statement about cryptographic strength, period, or bias. Pick Lcg64 for cheap non-cryptographic randomness; bring your own type for anything stronger.

Examples

struct MyRng: RandomNumberGenerator {
    var state: UInt64;

    mutating func nextUInt64() -> UInt64 {
        // mix state, return a fresh value
    }
}

Methods

public mutating func nextInt(below: Int64) -> Int64

Returns a uniformly distributed integer in [0, upperBound). Returns 0 when upperBound <= 0 rather than panicking.

Uses naive modulo for simplicity — for upperBound close to UInt64.maxValue the result has slight bias toward smaller values. If you need exact uniformity, sample nextUInt64() and reject.

Examples

var rng = Lcg64(seed: 42);
let roll = rng.nextInt(below: 6);   // 0..5

mutating func nextUInt64() -> UInt64

Returns the next UInt64 from the stream and advances internal state. Each call should be independent and uniformly distributed over the full UInt64 range — implementers that can't promise uniformity (e.g. very small periods) should document the bias.

Defined in lang/std/numeric/random.ks