tur/random
Random capability implementation using the platform RNG.
Implements the Random capability typeclass for real random values.
NOT CRYPTOGRAPHICALLY SECURE. This is libc rand() seeded with time(NULL). Its output is fully predictable to anyone who can guess the second the process started -- a few thousand candidate streams, trivially enumerable. It is the right tool for simulation, sampling, shuffling, jitter, and procedural generation, and the wrong tool for anything an attacker benefits from predicting: session tokens, password-reset links, nonces, salts, IVs, or key material.
For those, use crypto-random-bytes! from the secret spice (spices/secret in turmeric-spices), which draws from the OS CSPRNG -- getrandom(2) / arc4random_buf / BCryptGenRandom / /dev/urandom.
Since: Phase 16
random-next-int!
(random-next-int! [min :int max :int] :int)
create a Random capability backed by libc rand().
A heap-allocated Random struct with: next_int -- returns a random integer in [min, max]. next_float -- returns a random integer in [0, 9999] (divide by 10000.0 to obtain a float in [0, 1)). The RNG is seeded with time(NULL) on first use. Free with Real-Random-free when done.
(let [rng (Real-Random)] ...)
random-next-int! -- Real-Random's next_int slot: a random integer in [min, max], auto-seeding libc rand() with time(NULL) on first use. Internal; hoisted to file scope so Real-Random's inline-C can take its address (nested + static functions are non-standard C).
Since: Phase 16
random-next-float!
(random-next-float! :int)
Real-Random's next_float slot: a random integer in [0, 10000), auto-seeding libc rand() with time(NULL) on first use. Internal; hoisted to file scope (see random-next-int!).
Real-Random
(Real-Random :ptr)
Real-Random-free
(Real-Random-free [rng :ptr] :void)
release a Random capability created by Real-Random.
| rng | the Random pointer returned by Real-Random. |
Since: Phase 16
seeded-next-int!
(seeded-next-int! [min :int max :int] :int)
create a deterministic Random capability from a fixed seed.
| seed | unsigned integer seed for srand; same seed produces the same sequence. |
A heap-allocated Random struct identical in interface to Real-Random but seeded immediately with the supplied value. Useful for reproducible tests. Free with Seeded-Random-free when done.
(let [rng (Seeded-Random 42)] ...)
seeded-next-int! -- Seeded-Random's next_int slot: a random integer in [min, max] drawn from the current libc rand() state. Does not auto-seed; Seeded-Random calls srand(seed) at construction. Internal; hoisted to file scope so Seeded-Random's inline-C can take its address.
Since: Phase 16
seeded-next-float!
(seeded-next-float! :int)
Seeded-Random's next_float slot: a random integer in [0, 10000) drawn from the current libc rand() state. Does not auto-seed (see seeded-next-int!). Internal; hoisted to file scope.
Seeded-Random
(Seeded-Random [seed :int] :ptr)
Seeded-Random-free
(Seeded-Random-free [rng :ptr] :void)
release a Random capability created by Seeded-Random.
| rng | the Random pointer returned by Seeded-Random. |
Since: Phase 16
rand-int
(rand-int [min max])
return a random integer in the inclusive range [min, max].
| min | the minimum value (inclusive). | |
| max | the maximum value (inclusive). |
A random integer in [min, max]. The libc RNG is auto-seeded with time(NULL) on first call.
(rand-int 1 6) ; => 4 (simulate a die roll) ; doctest: non-deterministic (seeded from time(NULL))
Since: Phase 16
rand-float
(rand-float)
return a random integer scaled to represent [0, 1).
An integer in [0, 9999]. Divide by 10000.0 to obtain a float in [0, 1). The libc RNG is auto-seeded with time(NULL) on first call.
(rand-float) ; => 7312 (represents ~0.7312) ; doctest: non-deterministic (seeded from time(NULL))
Since: Phase 16
rand-die
(rand-die [sides])
roll an n-sided die, returning a value in [1, sides].
| sides | the number of faces on the die. |
A random integer in [1, sides].
(rand-die 20) ; => 13 (D20 roll) ; doctest: non-deterministic (seeded from time(NULL))
Since: Phase 16
rand-bool
(rand-bool)
return a random boolean value.
1 (true) or 0 (false) with equal probability.
(rand-bool) ; => 1 (or 0) ; doctest: non-deterministic (fair coin, seeded from time(NULL))
Since: Phase 16