Draw a uniform integer in [0, n) by rejection sampling.
The naive mod(next(), n) is biased whenever n does not divide the
generator’s period: the first 2**64 mod n residues each get one extra
preimage, so for large n some outcomes are measurably more likely.
Instead a mask of the smallest 2**k - 1 at least n - 1 is applied to
a fresh 64-bit word and values at or above n are rejected and redrawn.
Every accepted value has exactly one preimage per draw, so the result is
exactly uniform. The acceptance probability is above 1/2, so the
expected number of draws is below 2 and the loop terminates with
probability one.
n == 1 returns 0 without consuming a draw. n <= 0 is a usage error:
it returns 0 and, if error is present, sets ERROR_VALIDATION.
Nodes of different colours represent the following:
Solid arrows point from a procedure to one which it calls. Dashed
arrows point from an interface to procedures which implement that interface.
This could include the module procedures in a generic interface or the
implementation in a submodule of an interface in a parent module.
Where possible, edges connecting nodes are
given different colours to make them easier to distinguish in
large graphs.
Uniform integer in [0, n) from a PCG32 generator. Each attempt consumes
two 32-bit outputs, so the stream stays word aligned no matter how many
rejections occur.