Random Numbers
Eucalypt provides pseudo-random number generation through the io.random
stream and a set of prelude functions.
The Random Stream
Section titled “The Random Stream”The io.random binding is an opaque PRNG stream, seeded from system
entropy or the --seed command-line flag. Use random.* actions to
draw values from it, or random.as-list to obtain a lazy cons-list of
floats in [0, 1).
first-random: random.float(io.random).valueBecause io.random is seeded from the system clock by default, it
produces different values on each run. Use --seed for reproducible
results:
eu --seed 42 example.euRandom Number Generation
Section titled “Random Number Generation”| Function | Description |
|---|---|
random-stream(seed) |
|
stream-advance(n, s) |
|
random-ret(v, stream) |
|
random-bind(m, f, stream) |
|
random.stream(seed) |
Create an opaque PRNG stream from integer seed |
random.as-list(s) |
Convert an opaque random stream to a lazy cons-list of floats |
random.float(s) |
State-monad action returning a random float in [0,1) |
random.int(n, s) |
State-monad action returning a random integer in [0,n) |
random.split(s) |
State-monad action that splits the stream into two independent streams. Returns a value/rest block where value and rest are each independent streams |
random.choice(lst, stream) |
State-monad action returning a random element from list |
random.shuffle(lst) |
State-monad action returning a shuffled copy of list |
random.sample(n, lst, stream) |
State-monad action returning n elements sampled without replacement; a non-integer n is an error |
random.run(action, stream) |
Run a random action on a stream; returns a value/rest block |
random.eval(action, stream) |
Run a random action and return only the value |
random.exec(action, stream) |
DEPRECATED: use random.run(action, stream).rest. Run a random action and return only the remaining stream |
Usage Pattern
Section titled “Usage Pattern”The random namespace is a state monad. A random stream is provided
at startup as io.random. Each operation takes a stream and returns
a {value, rest} block:
result: random.int(6, io.random)die-roll: result.value # a number from 0 to 5For multiple random values, propagate .rest into the next call — or
use the random monad to handle threading automatically:
# Monadic block — no manual threadingdice: { :random a: random.int(6) b: random.int(6)}.[a + b + 2]
result: dice(io.random).valuerandom.sequence and random.map-m also handle threading:
two-dice: random.sequence([random.int(6), random.int(6)], io.random).valueShuffling and Sampling
Section titled “Shuffling and Sampling”deck: range(1, 53)hand: random.shuffle(deck, io.random).value take(5)colours: ["red", "green", "blue", "yellow", "purple"]two-colours: random.sample(2, colours, io.random).valueDeterministic Seeds
Section titled “Deterministic Seeds”For reproducible output (useful in tests), use --seed on the
command line or create a stream from a fixed seed:
eu --seed 42 my-template.eustream: random.stream(12345)x: random.int(100, stream)# x.value is always the same for seed 12345