Myrddin: 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[:] -> void)

        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. This is not secure.

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.