amd-utils / random

Pseudo-random generators.

amd-utils uses Math.random by default on all the pseudo-random generators, if you need a seeded random or a better algorithm see the random() documentation for instructions.

Table of Contents #

choice(...items):* #

Returns a random element from the supplied arguments or from an array if single argument is an array.

Example:


choice(1, 2, 3, 4, 5); // 3

var arr = ['lorem', 'ipsum', 'dolor'];
choice(arr); // 'dolor'

guid():String #

Generates a pseudo-random Globally Unique Identifier (v4).

Since the total number of GUIDs is 2122 the chance of generating the same value twice is negligible.

Important: this method uses Math.random by default so the UUID isn't safe (sequence of outputs can be predicted in some cases), check the random() documentation for more info on how to replace the default PRNG if you need extra safety or need seeded results.

See: randHex(), random()

Example:


guid();      // 830e9f50-ac7f-4369-a14f-ed0e62b2fa0b
guid();      // 5de3d09b-e79c-4727-932b-48c49228d508

rand([min], [max]):Number #

Gets a random number inside range or snap to min/max values.

Arguments:

  1. [min] (Number) : Minimum value. Defaults to number/MIN_INT.
  2. [max] (Number) : Maximum value. Defaults to number/MAX_INT.

Example:


rand();      // 448740433.55274725
rand();      // -31797596.097682
rand(0, 10); // 7.369723
rand(0, 10); // 5.987042

See: random()

randBit():Number #

Returns a random "bit" (0 or 1). Useful for addition/subtraction.

It's slightly faster than choice(0, 1) since implementation is simpler (not that it will make a huge difference in most cases).

See: choice()

Example:


randBit(); // 1
randBit(); // 0

//same effect as
choice(0, 1);

randHex([size]):String #

Returns a random hexadecimal string.

The default size is 6.

Example:


randHex();   // "dd8575"
randHex();   // "e6baeb"
randHex(2);  // "a2"
randHex(30); // "effd7e2ad9a4a3067e30525fab983a"

randInt([min], [max]):Number #

Gets a random integer inside range or snap to min/max values.

Arguments:

  1. [min] (Number) : Minimum value. Defaults to number/MIN_INT.
  2. [max] (Number) : Maximum value. Defaults to number/MAX_INT.

Example:


randInt();      // 448740433
randInt();      // -31797596
randInt(0, 10); // 7
randInt(0, 10); // 5

randSign():Number #

Returns a random "sign" (-1 or 1). Useful for multiplications.

It's slightly faster than choice(-1, 1) since implementation is simpler (not that it will make a huge difference in most cases).

See: choice()

Example:


randSign(); // -1
randSign(); // 1

//same effect as
choice(-1, 1);

random():Number #

Returns a random number between 0 and 1. Same as Math.random().


random(); // 0.35435103671625257
random(); // 0.8768321881070733

Important: No methods inside amd-utils should call Math.random() directly, they all use random/random as a proxy, that way we can inject/replace the pseudo-random number generator if needed (ie. in case we need a seeded random or a better algorithm than the native one).

Replacing the PRNG

In some cases we might need better/different algorithms than the one provided by Math.random (ie. safer, seeded).

Because of licensing issues, file size limitations and different needs we decided to not implement a custom PRNG and instead provide a easy way to override the default behavior. - issue #99

If you are using amd-utils with a loader that supports the AMD map config, such as RequireJS, you can use it to replace the PRNG (recommended approach):


requirejs.config({
    map : {
        // all modules will load "my_custom_prng" instead of
        // "amd-utils/random/random"
        '*' : {
            'amd-utils/random/random' : 'my_custom_prng'
        }
    }
});

You also have the option to override random.get in case you are using amd-utils on node.js or with a loader which doesn't support the map config:


// replace the PRNG
var n = 0;
random.get = function(){
    return ++n % 2? 0 : 1; // not so random :P
};
random(); // 0
random(); // 1
random(); // 0
random(); // 1

See this detailed explanation about PRNG in JavaScript to understand the issues with the native Math.random and also for a list of algorithms that could be used instead.

For more usage examples check specs inside /tests folder. Unit tests are the best documentation you can get...

Documentation generated by mdoc.