summaryrefslogtreecommitdiff
path: root/doc/api/libstd/randomness.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/api/libstd/randomness.txt')
-rw-r--r--doc/api/libstd/randomness.txt88
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`.