# 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`.