← Index

x/num/random

Pseudo- and hardware random number generation.

Two backends behind one interface: (Random sw [seed]) software, (Random hw) kernel. The software stream is not cryptographically secure.

Class Random

A source of random integers with a pluggable entropy backend.

Make one with (Random sw) / (Random sw seed) for the software PRNG, or (Random hw) for the kernel CSPRNG. The software stream is NOT cryptographically secure.

kind

Member: data carried by a Random instance.

state

Member: data carried by a Random instance.

fd

Member: data carried by a Random instance.

(Random sw . opt)

A software xorshift PRNG. Deterministic; pass a seed for a reproducible stream.

Parameters:

• opt : LIST — Optional (seed) – a nonzero integer seed

Returns: Random — A software RNG

(Random hw)

A hardware RNG reading the kernel CSPRNG from /dev/urandom.

Returns: Random — A hardware RNG

(seed! n)

Reseed the software PRNG. A zero seed is replaced – xorshift needs a nonzero state.

Instance method: called on a Random instance.

Parameters:

• n : INT — Seed value

Returns: Random — self, for chaining

(%bits)

Instance method: called on a Random instance.

(%sw-bits)

Instance method: called on a Random instance.

(%hw-bits)

Instance method: called on a Random instance.

(%fd)

Instance method: called on a Random instance.

(int n)

A random integer in [0, n), uniform via rejection sampling.

Instance method: called on a Random instance.

Parameters:

• n : INT — Exclusive upper bound (must be > 0)

Returns: INT — A value in [0, n)

Examples:

((Random sw 1) int 6) => 3

(range lo hi)

A random integer in [lo, hi) – exclusive upper bound; between is the inclusive twin. The name carries the bound contract.

Instance method: called on a Random instance.

Parameters:

• lo : INT — Inclusive lower bound
• hi : INT — Exclusive upper bound

Returns: INT — A value in [lo, hi)

(between lo hi)

A random integer in [lo, hi] – both ends inclusive; range is the exclusive twin. The name carries the bound contract.

Instance method: called on a Random instance.

Parameters:

• lo : INT — Inclusive lower bound
• hi : INT — Inclusive upper bound

Returns: INT — A value in [lo, hi]

(bool)

A random boolean (a fair coin).

Instance method: called on a Random instance.

Returns: BOOL — #t or #f

Examples:

((Random sw 9) bool) => #f

(bytes n)

A list of n random byte values (0-255).

Instance method: called on a Random instance.

Parameters:

• n : INT — How many bytes

Returns: LIST — n byte values

(choice lst)

A uniformly random element of a non-empty list.

Instance method: called on a Random instance.

Parameters:

• lst : LIST — A non-empty list

Returns: ANY — A random element

Examples:

((Random sw 5) choice (list 'a 'b 'c)) => 'a

(float)

A uniform float in [0.0, 1.0) with 53-bit resolution – two 31-bit draws, hi supplying 31 bits and lo’s top 22 joining them, over 2^53 (#363). Late-bound like every cross-class call: needs x/num/float loaded.

Instance method: called on a Random instance.

Returns: FLOAT — A float in [0, 1)

(uuid)

A random version-4 UUID string from this source – 16 bytes with the version (byte 6) and IETF-variant (byte 8) bits set, rendered 8-4-4-4-12 lowercase hex (#375). A seeded software source yields reproducible UUIDs (tests); (Random hw) yields real ones. Late-bound: needs x/codec/hex loaded.

Instance method: called on a Random instance.

Returns: STRING — “xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx”

(sample k lst)

k distinct elements of lst, uniformly, in random order – a shuffled prefix (#363). Raises tag ‘value when k exceeds the population.

Instance method: called on a Random instance.

Parameters:

• k : INT — How many to draw
• lst : LIST — The population

Returns: LIST — k distinct elements

(shuffle lst)

A new list holding the elements of lst in random order (Fisher-Yates).

Instance method: called on a Random instance.

Parameters:

• lst : LIST — A list

Returns: LIST — A randomly ordered copy

Examples:

((Random sw 5) shuffle (list 1 2 3)) => (3 2 1)