ludus::foundation::math::RandomStream¶

Class

Caller-owned, noncryptographic PCG32 stream with explicit logical call order.

Equal seed, selector and call order produce the versioned bit-exact sequence. No global state, entropy acquisition or automatic reseeding. See RandomState for explicit replay snapshots and docs/decisions/0010-foundation-math-module.md for conventions.

Declared in modules/foundation/math/include/ludus/foundation/math/random.hpp

#include <ludus/foundation/math/random.hpp>

class ludus::foundation::math::RandomStream

Methods¶

RandomStream¶

constexpr ludus::foundation::math::RandomStream::RandomStream() noexcept

Default construction uses a DETERMINISTIC seed=0/selector=0 (not entropy).

mState/mIncrement have default member initializers; seedInternal overwrites them with the documented two-step PCG seeding for seed=0, selector=0.

Declared in modules/foundation/math/include/ludus/foundation/math/random.hpp

TryReseed¶

bool ludus::foundation::math::RandomStream::TryReseed(uint64 seed, uint64 selector) noexcept

Reseed to the documented two-step PCG sequence. selector must be <= 0x7fffffffffffffff (a higher selector would alias its high bit and is rejected).

Returns false and leaves the stream unchanged on an invalid selector. seed is any uint64.

Related types: uint64

Declared in modules/foundation/math/include/ludus/foundation/math/random.hpp

NextUInt32¶

uint32 ludus::foundation::math::RandomStream::NextUInt32() noexcept

Next raw uint32 (XSH-RR output). Always advances the stream.

Related types: uint32

Declared in modules/foundation/math/include/ludus/foundation/math/random.hpp

TryNextBounded¶

MathStatus ludus::foundation::math::RandomStream::TryNextBounded(uint32 bound, uint32 &out) noexcept

Unbiased integer in [0, bound) via rejection sampling. bound must be > 0; an invalid bound leaves BOTH the output and the stream unchanged and returns InvalidArgument.

The rejection loop has small expected work but NO hard worst-case iteration bound — never call it from a deadline-bounded infrastructure callback.

Related types: uint32 · MathStatus

Declared in modules/foundation/math/include/ludus/foundation/math/random.hpp

NextFloat01¶

float32 ludus::foundation::math::RandomStream::NextFloat01() noexcept

Float in [0,1): high 24 bits of one draw times exactly 2^-24.

Includes 0, excludes 1, with a fixed single draw. Always advances the stream.

Related types: float32

Declared in modules/foundation/math/include/ludus/foundation/math/random.hpp

GetState¶

RandomState ludus::foundation::math::RandomStream::GetState() const noexcept

Save / restore.

GetState captures a versioned snapshot. TryRestore rejects a mismatched version or an even increment (PCG increments are always odd) WITHOUT changing the stream, returning InvalidArgument.

Related types: RandomState

Declared in modules/foundation/math/include/ludus/foundation/math/random.hpp

TryRestore¶

MathStatus ludus::foundation::math::RandomStream::TryRestore(const RandomState &state) noexcept

Restore a version-1 snapshot with an odd increment; rejection leaves the stream unchanged.

Related types: MathStatus · RandomState

Declared in modules/foundation/math/include/ludus/foundation/math/random.hpp