summaryrefslogtreecommitdiff
path: root/doc/api/libstd/randomness.txt
blob: 3c9934eef021ea0d1eaf5fb3daa35b697ac01159 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
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`.