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