nish/random
A seeded generator of pseudo-random numbers whose every answer is the same natively and under Node.
import {
Rng,
} from "nish/random";
import { Rng } from "nish/random";
export const main = (): i32 => {
const r = new Rng(42);
const die: i32 = r.nextInt(1, 6); // 1 to 6, each with equal chance
const u: f64 = r.nextF64(); // in [0, 1)
return die;
};
The state is one 32-bit integer
Each step adds the odd constant
0x9E3779B9 (2^32 divided by the golden ratio) to it, wrapping, so the
states walk all 2^32 values before any repeats, whatever the seed — 0
included. Each answer is MurmurHash3's 32-bit finaliser applied to the new
state (Austin Appleby's fmix32; MurmurHash3 is public domain, and these
are its constants): two multiplies and three shifted exclusive ors that mix
every bit of the state into every bit of the answer, so seeds 1, 2 and 3
answer three unrelated sequences. That pairing of a Weyl sequence with a
mixing function is the shape of SplitMix (Steele, Lea and Flood, "Fast
splittable pseudorandom number generators", OOPSLA 2014), on 32 bits.
The same bits under Node
The two operations that wrap are spelled
wrappingAdd and wrappingMul from nish:unsafe, which define the
two's-complement wrap natively and answer (a + b) | 0 and Math.imul(a, b)
under Node (docs/LANGUAGE.md, "nish
^ and >>> 16 answer the same 32 bits in JavaScript as in the
compiled program.
nextInt reads its span and its draws as unsigned counts with no u32
(whose conversions saturate under Node): the sign bit flipped orders them
under a signed compare, and the remainder is taken in pieces that stay below
2^31. nextF64 builds its double from integers below 2^53, so its products
and sums are exact both ways. The program a test prints under Node is the one
it prints compiled (docs/RUN_UNDER_NODE.md).
It is not for cryptography
a key or a nonce comes from
crypto.getRandomValues.
An `Rng` is an ordinary object
An Rng is an ordinary object, so a parallel body or a task that makes one
of its own may step it as it likes: what a function allocates is its own
memory (docs/LANGUAGE.md, "Data parallelism"). One shared by several tasks
would be a write their caller can see, and is refused as any such write is;
give each task its own, seeded from its index.
Classes
Rng
A generator of pseudo-random numbers: a Weyl sequence from its seed, each state mixed.
class Rng
| Member | |
|---|---|
new Rng(seed: i32) |
A generator whose sequence seed decides: two made from one seed answer the same numbers. |
nextF64(): f64 |
The next number in [0, 1), from two steps: the high 27 bits of one and the high 26 of the next make a 53-bit integer, which a double holds exactly, scaled by 2^-53. |
nextI32(): i32 |
The next 32 bits, as an i32: over 2^32 steps each value is answered exactly once. |
nextInt(lo: i32, hi: i32): i32 |
An integer in [lo, hi], both ends included, each with equal chance; nextInt(1, 6) is a die. It panics when lo is greater than hi, and the whole i32 range, nextInt(-2147483648, 2147483647), is one nextI32().There is no modulo bias: where the span hi - lo + 1, an unsigned count up to 2^32, does not divide 2^32 evenly, a draw among the lowest 2^32 mod span is refused and drawn again, and what is left holds every answer equally often. Fewer than half the draws are ever refused, so an answer takes one nextI32() step usually and fewer than two on average, and a sequence is still the seed's. |

