rand: update README.md (#14341)

* update README for rand module

* use concrete values

* make sure code works

vlib/rand/README.md

@@ -2,30 +2,59 @@
 
 The V `rand` module provides two main ways in which users can generate pseudorandom numbers:
 
-1. Through top-level functions in the `rand` module.
+## Direct Access Through The `rand` Module
-   - `import rand` - Import the `rand` module.
+
-   - `rand.seed(seed_data)` to seed (optional).
+```
-   - Use `rand.int()`, `rand.u32n(max)`, etc.
+// Import the rand module
-2. Through a generator of choice. The PRNGs are included in their respective submodules.
+import rand
-   - `import rand.pcg32` - Import the module of the PRNG required.
+
-   - `mut rng := pcg32.PCG32RNG{}` - Initialize the struct. Note that the **`mut`** is important.
+...
-   - `rng.seed(seed_data)` - optionally seed it with an array of `u32` values.
+
-   - Use `rng.int()`, `rng.u32n(max)`, etc.
+// Optionally seed the default generator
+rand.seed([u32(3110), 50714])
+
+...
+
+// 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()`.
 
-For non-uniform distributions, refer to the `rand.dist` module which defined functions for
-sampling from non-uniform distributions. These functions make use of the global RNG.
-
 **Note:** The global PRNG is not thread safe. It is recommended to use separate generators for
-separate threads in multi-threaded applications. If you need to use non-uniform sampling functions,
+separate threads in multi-threaded applications.
-it is recommended to generate them before use in a multi-threaded context.
 
-For sampling functions and generating random strings, see `string_from_set()` and other related
+There are only a few extra functions that are defined only in this top-level `rand` module.
-functions defined in this top-level module.
+Otherwise, there is feature parity between the generator functions and the top-level functions.
-
-For arrays, see `rand.util`.
 
 # General Background
 
@@ -38,25 +67,6 @@ This is often useful for simulations that need the same starting seed.
 If you need truly random numbers that are going to be used for cryptography,
 use the `crypto.rand` module.
 
-# Guaranteed functions
-
-The following 21 functions are guaranteed to be supported by `rand`
-as well as the individual PRNGs.
-
-- `seed(seed_data)` where `seed_data` is an array of `u32` values.
-    Different generators require different number of bits as the initial seed.
-    The smallest is 32-bits, required by `sys.SysRNG`.
-    Most others require 64-bits or 2 `u32` values.
-- `u32()`, `u64()`, `int()`, `i64()`, `f32()`, `f64()`
-- `u32n(max)`, `u64n(max)`, `intn(max)`, `i64n(max)`, `f32n(max)`, `f64n(max)`
-- `u32_in_range(min, max)`, `u64_in_range(min, max)`, `int_in_range(min, max)`,
-    `i64_in_range(min, max)`, `f32_in_range(min, max)`, `f64_in_range(min, max)`
-- `int31()`, `int63()`
-
-There are several additional functions defined in the top-level module that rely
-on the global RNG. If you want to make use of those functions with a different
-PRNG, you can can change the global RNG to do so.
-
 # Seeding Functions
 
 All the generators are time-seeded.
@@ -64,7 +74,7 @@ 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.
+   that are generated from the current time.
 
 # Caveats
 
@@ -81,7 +91,7 @@ A workaround (if you _must_ use the libc RNG) is to:
 
 # Notes
 
-Please note that [math interval](https://en.wikipedia.org/wiki/Interval_(mathematics)#Including_or_excluding_endpoints) notation is used throughout
+Please note that [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 posible values
 between `0` and `max` **including** 0 but **excluding** `max`.