📝 Clarify the README (#556)

* 📝 Clarify the README

* format

README.md

@@ -18,88 +18,43 @@ Fast Pseudorandom number generators (aka PRNG) with purity in mind!
 
 ## Getting started
 
-### In node
+**Install it in node via:**
 
-Install the module with: `npm install pure-rand`
+`npm install pure-rand` or `yarn add pure-rand`
 
-Unlike classical random number generators, `pure-rand` comes with a set of _pure_ and _seeded_ generators (implementing the interface [RandomGenerator](https://github.com/dubzzz/pure-rand/blob/main/src/generator/RandomGenerator.ts)).
-Each time a call to `.next()` method is done, the generator provides both the generated value and the next generator.
+**Use it in browser by doing:**
 
-As a consequence, a given generator will always produce the same value. It can be called as many times as required without impacting its state. This ability makes it easier to replay code section relying on random without having to re-seed a new generator and replay the whole path to be in the same state.
+`import * as prand from 'https://unpkg.com/pure-rand/lib/esm/pure-rand.js';`
 
-### In a web-page
-
-In order to use `pure-rand` from a web-page, you have to reference the web-aware script as follow:
+## Usage
 
-```html
-<script type="module">
-  import * as prand from 'https://unpkg.com/pure-rand/lib/esm/pure-rand.js';
-  // prand is now available
-</script>
-```
+**Simple usage**
 
-You can also reference a precise version by setting the version you want in the url:
+```javascript
+import prand from 'pure-rand';
 
-```html
-<script type="module">
-  import * as prand from 'https://unpkg.com/pure-rand@1.2.0/lib/esm/pure-rand.js';
-  // prand is now available
-</script>
+const seed = 42;
+const rng = prand.xoroshiro128plus(seed);
+const firstDiceValue = unsafeUniformIntDistribution(1, 6, rng); // value in {1..6}, here: 2
+const secondDiceValue = unsafeUniformIntDistribution(1, 6, rng); // value in {1..6}, here: 4
+const thirdDiceValue = unsafeUniformIntDistribution(1, 6, rng); // value in {1..6}, here: 6
 ```
 
-## Usage
+**Pure usage**
+
+Pure means that the instance `rng` will never be altered in-place. It can be called again and again and it will always return the same value. But it will also return the next `rng`. Here is an example showing how the code above can be translated into its pure version:
 
 ```javascript
 import prand from 'pure-rand';
 
 const seed = 42;
+const rng1 = prand.xoroshiro128plus(seed);
+const [firstDiceValue, rng2] = prand.uniformIntDistribution(1, 6, rng1); // value in {1..6}, here: 2
+const [secondDiceValue, rng3] = prand.uniformIntDistribution(1, 6, rng2); // value in {1..6}, here: 4
+const [thirdDiceValue, rng4] = prand.uniformIntDistribution(1, 6, rng3); // value in {1..6}, here: 6
 
-// Instanciates a Mersenne Twister
-// random number generator with the seed=42
-const gen1 = prand.mersenne(seed);
-
-// Build a random value `n` and the next generator `gen2`
-// the random value `n` is within the range:
-// gen1.min() (included) to gen1.max() (included)
-const [n, gen2] = gen1.next();
-// Calling again next on gen1 will provide the very same output:
-// `n: number` and `gen2: RandomGenerator`
-
-// In order to generate values within range,
-// distributions are provided by the pure-rand
-
-// Like `.next()` method,
-// distributions take an incoming generator and extract a couple:
-// (n: number, nextGenerator: RandomGenerator)
-
-// The distribution built by the call to prand.uniformIntDistribution(0, 9)
-// generates uniformly integers within 0 (included) and 9 (included)
-const [nRange, gen3] = prand.uniformIntDistribution(0, 9)(gen1);
-// Calling again the same Distribution with the same RandomGenerator
-// will provide the same output
-
-// Whenever you want to use the distribution only once you can directly call
-// prand.uniformIntDistribution(from, to, rng) which is totally equivalent to prand.uniformIntDistribution(from, to)(rng)
-// In terms of performances, the 3 parameters version is faster
-const [nNoDistributionInstance, gen4] = prand.uniformIntDistribution(0, 9, gen3);
-
-// Some generators come with built-in jump
-// jump provides the ability to skip a very large number of intermediate values
-// Calling jump is recommended whenever you want to build non-overlapping subsequences
-const gen4 = prand.xoroshiro128plus(seed);
-const offsetGen4 = gen4.jump();
-// In the case of:
-// - xoroshiro128plus - jump is equivalent to 2^64 calls to next
-// - xorshift128plus  - jump is equivalent to 2^64 calls to next
-```
-
-Module import can also be done using one of the following syntaxes:
-
-```javascript
-import * as prand from 'pure-rand';
-import { mersenne } from 'pure-rand';
-const prand = require('pure-rand');
-const { mersenne } = require('pure-rand');
+// You can call: prand.uniformIntDistribution(1, 6, rng1);
+// over and over it will always give you back the same value along with a new rng (always producing the same values too).
 ```
 
 ## Documentation
@@ -110,11 +65,10 @@ All the [RandomGenerator](https://github.com/dubzzz/pure-rand/blob/main/src/gene
 
 The following generators are available:
 
-- `prand.xorshift128plus(seed: number)`: xorshift128+ generator whose values are within the range -0x80000000 to 0x7fffffff
-- `prand.xoroshiro128plus(seed: number)`: xoroshiro128+ generator whose values are within the range -0x80000000 to 0x7fffffff
-- `prand.mersenne(seed: number)`: Mersenne Twister generator whose values are within the range 0 to 0xffffffff
-- `prand.congruential(seed: number)`: Linear Congruential generator whose values are within the range 0 to 0x7fff
-- `prand.congruential32(seed: number)`: Linear Congruential generator whose values are within the range 0 to 0xffffffff
+- `prand.xorshift128plus(seed: number)`: Xorshift 128+ generator
+- `prand.xoroshiro128plus(seed: number)`: Xoroshiro 128+ generator
+- `prand.mersenne(seed: number)`: Mersenne Twister generator
+- `prand.congruential32(seed: number)`: Linear Congruential generator
 
 Some helpers are also provided in order to ease the use of `RandomGenerator` instances: