Initial project import

tools/v/vlib/rand/README.md

@@ -0,0 +1,118 @@
+# Description
+
+The V `rand` module provides two main ways in which users can generate pseudorandom numbers:
+
+## Direct Access Through The `rand` Module
+
+```
+// Import the rand module
+import rand
+
+...
+
+// Optionally seed the default generator
+rand.seed([u32(3223878742), 1732001562])
+
+...
+
+// Use the top-level functions
+rand.u32n(100)!
+rand.int() // among others ...
+```
+
+## Through A Generator Of Choice
+
+```
+// Import the rand module
+import rand
+import rand.seed
+
+// Import the module of the generator you want to use
+import rand.pcg32
+
+...
+
+// Initialise the generator struct (note the `mut`)
+mut rng := &rand.PRNG(pcg32.PCG32RNG{})
+
+// Optionally seed the generator
+rng.seed(seed.time_seed_array(pcg32.seed_len))
+
+...
+
+// Use functions of your choice
+rng.u32n(100)!
+rng.int() // among others ...
+```
+
+## More Information
+
+You can change the default generator to a different one. The only requirement is that
+the generator must implement the `PRNG` interface. See `get_current_rng()` and `set_rng()`.
+
+> **Note**
+> The global PRNG is not thread safe. It is recommended to use separate generators for
+> separate threads in multi-threaded applications.
+
+There are only a few extra functions that are defined only in this top-level `rand` module.
+Otherwise, there is feature parity between the generator functions and the top-level functions.
+
+# General Background
+
+A PRNG is a Pseudo Random Number Generator.
+Computers cannot generate truly random numbers without an external source of noise or entropy.
+We can use algorithms to generate sequences of seemingly random numbers,
+but their outputs will always be deterministic, according to the seed values.
+
+This is often useful for simulations that need the same starting seeds.
+You may be debugging a program and want to restart it with the same
+seeds, or you want to verify a working program is still
+operating identically after compiler or operating system updates.
+
+If you need truly random numbers that are going to be used for cryptography,
+use the `crypto.rand` module.
+
+# Seeding Functions
+
+All the generators are initialized with time-based seeds.
+The helper functions publicly available in `rand.seed` module are:
+
+1. `time_seed_array()` - returns a `[]u32` that can be directly plugged into the `seed()` functions.
+2. `time_seed_32()` and `time_seed_64()` - 32-bit and 64-bit values respectively
+   that are generated from the current time.
+
+When composing your own seeds, use "typical" u32 numbers, not small numbers. This
+is especially important for PRNGs with large state, such as `mt19937`. You can create
+random unsigned integers with openssl `rand` or with `v repl` as follows:
+
+```
+$ openssl rand -hex 4
+e3655862
+$ openssl rand -hex 4
+97c4b1db
+$ v repl
+>>> import rand
+>>> [rand.u32(),rand.u32()]
+[2132382944, 2443871665]
+```
+
+# Caveats
+
+Note that the `sys.SysRNG` struct (in the C backend) uses `C.srand()` which sets the seed globally.
+Consequently, all instances of the RNG will be affected.
+This problem does not arise for the other RNGs.
+A workaround (if you _must_ use the libc RNG) is to:
+
+1. Seed the first instance.
+2. Generate all values required.
+3. Seed the second instance.
+4. Generate all values required.
+5. And so on...
+
+# Notes
+
+[Math interval](<https://en.wikipedia.org/wiki/Interval_(mathematics)#Including_or_excluding_endpoints>)
+notation is used throughout the function documentation to denote what numbers ranges include.
+
+An example of `[0, max)` thus denotes a range with all possible values
+between `0` and `max` **including** 0 but **excluding** `max`.