random
Two distinct randomness facilities, kept cleanly separated so PRNG output can never accidentally stand in for crypto. The PRNG path is seeded and reproducible — for simulation, sampling, and shuffling — and comes in a process-global form plus pure explicit-state mirrors. The crypto-random path is kernel-backed cryptographic randomness for tokens, keys, and salts, and is never seedable. This module owns generation of random values; keyed transforms belong to cx-stdlib/crypto.
random:seed
[$random:seed] -> null — Re-seed the process-global PRNG so its sequence becomes reproducible.
[?lib 'cx-stdlib/random']
[?let [= $a [$random:seed 42]] [$random:next-int]]
7510639304993616975
random:next-int
[$random:next-int] -> int — Draw a uniform 63-bit non-negative integer from the process-global PRNG.
[?lib 'cx-stdlib/random']
[?let [= $a [$random:seed 42]] [$random:next-int]]
7510639304993616975
random:next-float
[$random:next-float] -> float — Draw a uniform float in the half-open range 0.0 to 1.0 from the process-global PRNG.
[?lib 'cx-stdlib/random']
[?let [= $a [$random:seed 42]] [= $f [$random:next-float]] [and [>= $f 0.0] [< $f 1.0]]]
true
random:next-bool
[$random:next-bool] -> bool — Draw a uniform random boolean from the process-global PRNG.
[?lib 'cx-stdlib/random']
[?let [= $a [$random:seed 42]] [= $b [$random:next-bool]] [or [= $b true] [= $b false]]]
true
random:int-range
[$random:int-range] -> int — Draw a uniform integer in the inclusive range lo to hi, with no modulo bias.
[?lib 'cx-stdlib/random']
[$random:int-range 5 5]
5
random:float-range
[$random:float-range] -> float — Draw a uniform float in the half-open range lo to hi.
[?lib 'cx-stdlib/random']
[$random:float-range 2.5 2.5]
2.5
random:shuffle
[$random:shuffle] -> [sequence any] — Return a new Fisher-Yates shuffle of the sequence.
[?lib 'cx-stdlib/random']
[$random:shuffle (42)]
(42)
random:choose
[$random:choose] -> any — Pick one element uniformly at random from the sequence.
[?lib 'cx-stdlib/random']
[$random:choose ("only")]
'only'
random:sample
[$random:sample] -> [sequence any] — Draw a uniform sample of size n without replacement from the sequence.
[?lib 'cx-stdlib/random']
[$random:sample (1, 2, 3) 0]
()
random:from-seed
[$random:from-seed] -> element — Build an explicit-state generator carrying its own reproducible state from a seed.
[?lib 'cx-stdlib/random']
[?let [= $r [$random:next-int-with [$random:from-seed 42]]] $r/value]
7510639304993616975
random:next-int-with
[$random:next-int-with] -> element — Draw a 63-bit integer from an explicit generator, returning the value and next generator.
[?lib 'cx-stdlib/random']
[?let [= $r [$random:next-int-with [$random:from-seed 42]]] $r/value]
7510639304993616975
random:next-float-with
[$random:next-float-with] -> element — Draw a float in 0.0 to 1.0 from an explicit generator, returning the value and next generator.
[?lib 'cx-stdlib/random']
[?let [= $r [$random:next-float-with [$random:from-seed 42]]] $r/value]
0.8143051451229099
random:next-bool-with
[$random:next-bool-with] -> element — Draw a boolean from an explicit generator, returning the value and next generator.
[?lib 'cx-stdlib/random']
[?let [= $r [$random:next-bool-with [$random:from-seed 42]]] $r/value]
true
random:int-range-with
[$random:int-range-with] -> element — Draw an unbiased integer in lo to hi from an explicit generator, returning the value and next generator.
[?lib 'cx-stdlib/random']
[?let [= $r [$random:int-range-with [$random:from-seed 7] 9 9]] $r/value]
9
random:float-range-with
[$random:float-range-with] -> element — Draw a float in lo to hi from an explicit generator, returning the value and next generator.
[?lib 'cx-stdlib/random']
[?let [= $r [$random:float-range-with [$random:from-seed 7] 2.5 2.5]] $r/value]
2.5
random:shuffle-with
[$random:shuffle-with] -> element — Shuffle a sequence with an explicit generator, returning the result and next generator.
[?lib 'cx-stdlib/random']
[?let [= $r [$random:shuffle-with [$random:from-seed 42] (1, 2, 3, 4, 5)]] $r/value]
(4, 3, 1, 5, 2)
random:choose-with
[$random:choose-with] -> element — Pick one element with an explicit generator, returning the choice and next generator.
[?lib 'cx-stdlib/random']
[?let [= $r [$random:choose-with [$random:from-seed 3] ("solo")]] $r/value]
'solo'
random:sample-with
[$random:sample-with] -> element — Sample n elements without replacement with an explicit generator, returning the sample and next generator.
[?lib 'cx-stdlib/random']
[?let [= $r [$random:sample-with [$random:from-seed 42] (10, 20, 30, 40, 50) 3]] $r/value]
(40, 30, 10)
random:crypto-bytes
[$random:crypto-bytes] -> bytes — Return n cryptographically random bytes from the system CSPRNG.
[?lib 'cx-stdlib/random']
[$random:crypto-bytes -1]
cx-err:CXER0271
random:crypto-int
[$random:crypto-int] -> int — Return a cryptographically random integer in the inclusive range lo to hi, unbiased.
[?lib 'cx-stdlib/random']
[$random:crypto-int 7 7]
cx-err:CXER0271
random:crypto-hex
[$random:crypto-hex] -> string — Return n cryptographically random bytes as a lowercase hex string of length 2n.
[?lib 'cx-stdlib/random']
[$string-length [$random:crypto-hex 8]]
cx-err:CXER0271
random:crypto-base64-url
[$random:crypto-base64-url] -> string — Return n cryptographically random bytes as an unpadded base64-url string.
[?lib 'cx-stdlib/random']
[$contains [$random:crypto-base64-url 32] "="]
cx-err:CXER0271
random:crypto-token-urlsafe
[$random:crypto-token-urlsafe] -> string — Return a URL-safe random session token, base64-url with a default of 32 bytes.
[?lib 'cx-stdlib/random']
[$contains [$random:crypto-token-urlsafe 32] "="]
cx-err:CXER0271
random:gaussian
[$random:gaussian] -> float — Draw a normally-distributed float with the given mean and standard deviation.
[?lib 'cx-stdlib/random']
[$random:gaussian 5.0 0.0]
5.0
random:exponential
[$random:exponential] -> float — Draw an exponentially-distributed float with rate lambda.
[?lib 'cx-stdlib/random']
[$random:exponential 0.0]
cx-err:CXER1905
random:poisson
[$random:poisson] -> int — Draw a Poisson-distributed integer with mean lambda.
[?lib 'cx-stdlib/random']
[$random:poisson -2.0]
cx-err:CXER1905
random:gaussian-with
[$random:gaussian-with] -> element — Draw a normal value with an explicit generator, returning the value and next generator.
[?lib 'cx-stdlib/random']
[?let [= $r [$random:gaussian-with [$random:from-seed 11] 3.0 0.0]] $r/value]
3.0
random:exponential-with
[$random:exponential-with] -> element — Draw an exponential value with an explicit generator, returning the value and next generator.
[?lib 'cx-stdlib/random']
[?let [= $r [$random:exponential-with [$random:from-seed 42] 1.0]] $r/value]
1.683650517646569
random:poisson-with
[$random:poisson-with] -> element — Draw a Poisson value with an explicit generator, returning the value and next generator.
[?lib 'cx-stdlib/random']
[?let [= $r [$random:poisson-with [$random:from-seed 42] 4.0]] $r/value]
6
random:choose-weighted
[$random:choose-weighted] -> any — Pick one element with probability proportional to its weight.
[?lib 'cx-stdlib/random']
[$random:choose-weighted ("a", "b") (1.0)]
cx-err:CXER1904
random:sample-weighted
[$random:sample-weighted] -> [sequence any] — Sample n elements without replacement, proportional to remaining weights.
[?lib 'cx-stdlib/random']
[$random:sample-weighted ("a", "b") (1.0, 0.0) 2]
cx-err:CXER1903
random:choose-weighted-with
[$random:choose-weighted-with] -> element — Weighted pick with an explicit generator, returning the choice and next generator.
[?lib 'cx-stdlib/random']
[?let [= $r [$random:choose-weighted-with [$random:from-seed 5] ("a", "b") (0.0, 1.0)]] $r/value]
'b'
random:sample-weighted-with
[$random:sample-weighted-with] -> element — Weighted sample of n without replacement using an explicit generator, returning the sample and next generator.
[?lib 'cx-stdlib/random']
[?let [= $r [$random:sample-weighted-with [$random:from-seed 42] ("a", "b", "c") (1.0, 1.0, 1.0) 2]] [$count $r/value]]
2
random:next-floats
[$random:next-floats] -> [sequence float] — Return a sequence of n uniform floats in 0.0 to 1.0.
[?lib 'cx-stdlib/random']
[$count [$random:next-floats 5]]
5
random:next-ints
[$random:next-ints] -> [sequence int] — Return a sequence of n uniform 63-bit non-negative integers.
[?lib 'cx-stdlib/random']
[$count [$random:next-ints 7]]
7
random:next-floats-with
[$random:next-floats-with] -> element — Generate n floats with an explicit generator, returning the sequence and next generator.
[?lib 'cx-stdlib/random']
[?let [= $r [$random:next-floats-with [$random:from-seed 42] 3]] $r/value]
(0.8143051451229099, 0.3188210400616611, 0.9838941681774888)
random:next-ints-with
[$random:next-ints-with] -> element — Generate n integers with an explicit generator, returning the sequence and next generator.
[?lib 'cx-stdlib/random']
[?let [= $r [$random:next-ints-with [$random:from-seed 42] 3]] $r/value]
(7510639304993616975, 2940605065665682376, 9074821957992740550)
random:new
[$random:new] -> element — Create a stateful generator handle seeded with s; gen-* draws advance its private stream in place.
[?lib 'cx-stdlib/random']
[$random:gen-int [$random:new 42]]
7510639304993616975
random:free
[$random:free] -> null — Release a generator handle; later draws on it refuse with E_RANDOM_HANDLE_INVALID.
[?lib 'cx-stdlib/random']
[?let [= $g [$random:new 7]] [= $f [$random:free $g]] [$random:gen-int $g]]
cx-err:CXER1906
random:gen-int
[$random:gen-int] -> int — Draw a uniform 63-bit non-negative integer from a generator handle.
[?lib 'cx-stdlib/random']
[$random:gen-int [$random:new 42]]
7510639304993616975
random:gen-float
[$random:gen-float] -> float — Draw a uniform float in 0.0 to 1.0 from a generator handle.
[?lib 'cx-stdlib/random']
[$random:gen-float [$random:new 42]]
0.8143051451229099
random:gen-bool
[$random:gen-bool] -> bool — Draw a uniform boolean from a generator handle.
[?lib 'cx-stdlib/random']
[$random:gen-bool [$random:new 42]]
true
random:gen-int-range
[$random:gen-int-range] -> int — Draw a uniform integer in lo..hi inclusive from a generator handle (rejection-sampled, no modulo bias).
[?lib 'cx-stdlib/random']
[$random:gen-int-range [$random:new 7] 9 9]
9
random:gen-float-range
[$random:gen-float-range] -> float — Draw a uniform float in lo (inclusive) to hi (exclusive) from a generator handle.
[?lib 'cx-stdlib/random']
[$random:gen-float-range [$random:new 7] 2.5 2.5]
2.5
random:gen-shuffle
[$random:gen-shuffle] -> [sequence any] — Fisher-Yates shuffle drawn from a generator handle; returns a new sequence.
[?lib 'cx-stdlib/random']
[$random:gen-shuffle [$random:new 42] (1, 2, 3, 4, 5)]
(4, 3, 1, 5, 2)
random:gen-choose
[$random:gen-choose] -> any — Choose one element uniformly from a sequence, drawn from a generator handle.
[?lib 'cx-stdlib/random']
[$random:gen-choose [$random:new 3] ("solo")]
'solo'
random:gen-sample
[$random:gen-sample] -> [sequence any] — Uniform without-replacement sample of size n, drawn from a generator handle.
[?lib 'cx-stdlib/random']
[$random:gen-sample [$random:new 1] (1, 2, 3) 0]
()
random:gen-gaussian
[$random:gen-gaussian] -> float — Draw a normal(mean, stddev) sample from a generator handle.
[?lib 'cx-stdlib/random']
[$random:gen-gaussian [$random:new 1] 5.0 0.0]
5.0
random:gen-exponential
[$random:gen-exponential] -> float — Draw an exponential(lambda) sample from a generator handle.
[?lib 'cx-stdlib/random']
[$random:gen-exponential [$random:new 42] 1.0]
1.683650517646569
random:gen-poisson
[$random:gen-poisson] -> int — Draw a Poisson(lambda) sample from a generator handle.
[?lib 'cx-stdlib/random']
[$random:gen-poisson [$random:new 42] 4.0]
6
random:gen-choose-weighted
[$random:gen-choose-weighted] -> any — Choose one element with probability proportional to its weight, drawn from a generator handle.
[?lib 'cx-stdlib/random']
[$random:gen-choose-weighted [$random:new 5] ("a", "b") (0.0, 1.0)]
'b'
random:gen-sample-weighted
[$random:gen-sample-weighted] -> [sequence any] — Weighted without-replacement sample of size n, drawn from a generator handle.
[?lib 'cx-stdlib/random']
[$random:gen-sample-weighted [$random:new 5] ("a", "b") (1.0, 1.0) 0]
()
random:gen-floats
[$random:gen-floats] -> [sequence float] — Generate a sequence of n uniform floats from a generator handle.
[?lib 'cx-stdlib/random']
[$random:gen-floats [$random:new 1] 0]
()
random:gen-ints
[$random:gen-ints] -> [sequence int] — Generate a sequence of n uniform 63-bit integers from a generator handle.
[?lib 'cx-stdlib/random']
[$random:gen-ints [$random:new 42] 1]
(7510639304993616975)