well1024a.js


This is a Javascript implementation of the
WELL-1024a
pseudorandom number generation algorithm.

Javascript's built-in Math.random() function is
implementation-dependent
and therefore of limited usefulness if your program depends on random
numbers, as you risk running into crappy implementations. Even the V8
engine (used by Node.js) only provides 32-bit entropy, and is based on
the platform-dependent C++ rand() function.

This module is very bare-bones. I have also written a randomness library called
randy that provides useful functions like
RandInt(min, max), shuffle(array) etc., based on this module.

Quick Example

``javascript
var rng = well1024a();
var number = rng.getUInt32();
var coin = ['heads', 'tails'][number % 2];
// coin == 'heads'
`

Download

For Node.js, use npm:

npm install prng-well1024a

$3

Download and include as a

I am years old!

`

Documentation

$3

* well1024a

$3

* getUInt32
* getState
* setState

-----------------------------------

well1024a(entropy)

The instance will use Math.random() to fill out the initial seed state.

__Arguments__

* entropy - default=[]. Array of numbers to add to the initial seed. These should be based on environmental values that are likely to be different on each run such as system time, process ID, browser window height, values from /dev/urandom etc.

__Example__

`javascript
var w = well1024a([
Date.now(),
os.freemem(),
process.pid
]);
`

-----------------------------------

getUInt32()

Returns a random positive integer less than 2^32.

__Example__

`javascript
var w = well1024a();

console.log('For Christmas this year, I want ' + w.getUInt32().toString() + ' ponies!');
`

-----------------------------------

getState()

Returns an array of 32-bit unsigned integers, of length 32. This represents the current state of the random number generator.

This array can be used as a parameter to setState.

-----------------------------------

setState(state)

Sets the random number generator to a specific state, allowing for replay of random values.

General use case is to give it a value previously received by calling getState().

__Arguments__

* state - Must be an array of 32-bit unsigned integers, of length 32.

__Example__

This will flip a pair of coins, reset the generator state, and flip the
coins again with the exact same output.

`javascript
var w = well1024a();
var coins = ['heads', 'tails'];

console.log("Flippin' the coins:");
var state = w.getState();
var d1 = coins[w.getUInt32() % 2];
var d2 = coins[w.getUInt32() % 2];
console.log(d1 + " and " + d2);

console.log("Instant replay:");
w.setState(state);
d1 = coins[w.getUInt32() % 2];
d2 = coins[w.getUInt32() % 2];
console.log(d1 + " and " + d2);
`

---------------------------------------

Notes

No functions rely on this, so it's safe to e.g. assign
randy.good.randInt` to a variable or pass it around as a
parameter.