diff options
Diffstat (limited to 'doc/api/libstd/randomness.txt')
-rw-r--r-- | doc/api/libstd/randomness.txt | 88 |
1 files changed, 88 insertions, 0 deletions
diff --git a/doc/api/libstd/randomness.txt b/doc/api/libstd/randomness.txt new file mode 100644 index 0000000..3c9934e --- /dev/null +++ b/doc/api/libstd/randomness.txt @@ -0,0 +1,88 @@ +{ + title: Randomness + description: libstd: Randomness +} + + +Randomness +---------- + + pkg std = + type rng = struct + ... + ;; + + generic rand : (lo : @a::(numeric,integral), hi : @a::(numeric,integral) -> @a::(numeric,integral)) + generic randnum : (rng : rng# -> @a::(numeric,integral)) + const randbytes : (buf : byte[:] -> size) + + const mksrng : (seed : uint32 -> rng#) + const freerng : (rng : rng# -> void) + generic rngrand : (rng : rng#, lo : @a::(numeric,integral), hi : @a::(numeric,integral) -> @a::(numeric,integral)) + generic rngrandnum : (rng : rng# -> @a::(numeric,integral)) + const rngrandbytes : (rng : rng#, buf : byte[:] -> size) + ;; + + +Overview +-------- + +Currently, the random number generation interface is quite poor. It is not +cryptographically secure, although it should be. It exposes some functions +that it should not. + +Overall, deterministic random numbers should be removed from APIs that do not +define the specific generator. + +Types +----- + + type rng = struct + ... + ;; + +The `rng` type contains the state for the random number generator. + +Functions +--------- + + generic rand : (lo : @a::(numeric,integral), hi : @a::(numeric,integral) -> @a::(numeric,integral)) + +Generates a random integer in the range [lo, hi), returning the value. The +range [lo, hi) must be positive, nonempty, and the difference between hi and +lo must be less then 2^(type_bits - 1) + + generic randnum : (rng : rng# -> @a::(numeric,integral)) + +Generates a random integer of any magnitude the type may hold. The returned +value may be negative, if the type is signed. + + const randbytes : (buf : byte[:] -> size) + +Fills a buffer with random bytes. + + const mksrng : (seed : uint32 -> rng#) + +Allocates and initializes a random number generator. The seed `seed` is used +to seed the generator. The returned random number generator must be freed +using `freerng`. + + const freerng : (rng : rng# -> void) + +Frees all resources associated with the random number generator `rng`. + + generic rngrand : (rng : rng#, lo : @a::(numeric,integral), hi : @a::(numeric,integral) -> @a::(numeric,integral)) + + +Generates a random integer from `rng` in the range [lo, hi), returning the +value. The range [lo, hi) must be positive, nonempty, and the difference +between hi and lo must be less then 2^(type_bits - 1) + + generic rngrandnum : (rng : rng# -> @a::(numeric,integral)) + +Generates a random integer of any size from the random number generator `rng`. +The returned value may be negative, if the type is signed. + + const rngrandbytes : (rng : rng#, buf : byte[:] -> size) + +Fills a buffer with random bytes from the random number generator `rng`. |