One function per integer width, because the draw pattern (how many 64-bit
draws a sample consumes, and the full-range early return) is per width and
is part of the wire contract with the reference implementations.
nextWithUpperBoundU32(rng, bound) samples [0, bound) with Lemire's
nearly-divisionless method.
…Usize is the reference's usize instantiation over number
([0, 2^53 - 1]) with the 64-bit draw; the 32-bit samplers are not a
substitute for it (they consume the generator differently).
A signed range's length (end - start) must fit the signed width, as it
must in the reference, whose arithmetic is checked: nextInRangeI8(rng, -128, 127) is a RandErrorRangeTooLong, not a sample. The unsigned
full range (0..=255 for u8) reaches the reference's raw-draw path and
throws ValueDoesNotFit unless the draw fits, exactly as the reference
panics.
Every sampler draws nextU64() (masked to its width), as the reference
does for every width; generators that implement nextU64Low32 serve the
8/16/32-bit samplers without a bigint. Arguments must be integers inside
the width (InvalidArgument), and ranges must be ordered (EmptyRange);
every failure is a RandError thrown before any draw.
Bounded and ranged integer samplers over any RandomNumberGenerator.
One function per integer width, because the draw pattern (how many 64-bit draws a sample consumes, and the full-range early return) is per width and is part of the wire contract with the reference implementations.
nextWithUpperBoundU32(rng, bound)samples[0, bound)with Lemire's nearly-divisionless method.nextInRangeI16(rng, start, end)samples[start, end).nextInClosedRangeU64(rng, start, end)samples[start, end].…Usizeis the reference'susizeinstantiation overnumber([0, 2^53 - 1]) with the 64-bit draw; the 32-bit samplers are not a substitute for it (they consume the generator differently).A signed range's length (
end - start) must fit the signed width, as it must in the reference, whose arithmetic is checked:nextInRangeI8(rng, -128, 127)is aRandErrorRangeTooLong, not a sample. The unsigned full range (0..=255for u8) reaches the reference's raw-draw path and throwsValueDoesNotFitunless the draw fits, exactly as the reference panics.Every sampler draws
nextU64()(masked to its width), as the reference does for every width; generators that implementnextU64Low32serve the 8/16/32-bit samplers without abigint. Arguments must be integers inside the width (InvalidArgument), and ranges must be ordered (EmptyRange); every failure is a RandError thrown before any draw.