# pure-random

A purely functional random number generator. It implements the `xorshift`

algorithm. Xorshift RNGs which are a class of PRNGs that are extremely fast on modern computers and outperm other PRNGs in performance and BigCrush stress testing.

## Usage

`> const rnd = > rnd 2628481196 1837393298 2892949381 1706851469 > rnd`

Passing in the same seed with the same params produces the same number:

`> const seed = rnd> seed 426141121 700962946 3633913687 2605998810 > rnd> rnd> rnd`

## Reference

`genSeed`

`:: () -> [Uint32]`

Uses `Date.now`

to generate a non-cryptographically secure seed. It is more performant than `genCsSeed`

, and appropriate for most cases. The seed is an array of four `Uint32`

numbers. Since there is no `Uint32`

in javascript yet, integers within the range **[0, 4294967295]** are returned.

`genCsSeed`

`:: () -> [Uint32]`

Uses `crypto.randomBytes`

to generate a cryptographically secure seed. It is useful for creating an `initialization vector`

for cryptography, or in any situation where you need the generated random number to have significant entropy. The seed is an array of four `Uint32`

numbers. Since there is no `Uint32`

in javascript yet, integers within the range **[0, 4294967295]** are returned.

`randUint`

`:: [UInt32] -> UInt32`

Takes a `seed`

and returns a random `UInt32`

value, which in javascript is an integer within the range **[0, 4294967295]**. This function is actually the javascript `xorshift`

implementation, so it is extremely fast. The other methods call this method under the hood.

`randFloat`

` :: [UInt32] -> Int -> Int -> Either Error Float`

Takes a `seed`

and a `min`

and `max`

range. It returns an `Either`

value that is `Left Error`

if the function was called with invalid parameters, or a `Right Float`

within the specified range (inclusive).

`random`

` :: [UInt32] -> Int -> Int -> Either Error Int`

Takes a `seed`

and a `min`

and `max`

range. It returns an `Either`

value that is `Left Error`

if the function was called with invalid parameters, or a `Right Int`

within the specified range (inclusive).

## Faq

#### Why wasn't Math.random used?

`Math.random`

is non-deterministic and doesn't have take a seed value, which means that you cannot return results consistently, which is against the purely functional paradigm. Note that this library has an option for more powerful entropy than `Math.random`

by using the `genCsSeed`

option.

#### What about xorshift* or xorshift+?

The javascript number type uses a double-precision 64-bit binary format IEEE 754 value, which is a number between **-(2 ^{53} - 1)** and

**2**. The xorshift* and xorshift+ libraries rely on

^{53}- 1`Uint64`

types, which javascript does not support. If a developer erroneously decides to represent `Uint64`

using the native number type, then any `Uint64`

type will lose precision on the upper end because a javascript number will only go up to **2**but a range of

^{53}- 1**0**to

**2**is needed for

^{64}- 1`Uint64`

.In general, it would be too complicated to implement these other algorithms because you would have to jump through a lot of hoops with javascript's lack of a type system, and with very little gain. These improvements to xorshift are only slightly more performant.