Pandemonium

Method	Time	Memory	Note
-------------------------------------------------------	---------------	------	---------------------------------------------------------------------------
[dangerouslyMutatingSample](#dangerouslymutatingsample)	`O(k)`	`O(k)`	Must
[fisherYatesSample](#fisheryatessample)	`O(n)`	`O(n)`	Probably
[geometricReservoirSample](#geometricreservoirsample)	`O(k*log(n/k))`	`O(k)`	Probably
[naiveSample](#naivesample)	`Ω(k)`,	`O(k)`	Only
[reservoirSample](#reservoirsample)	`O(n)`	`O(k)`	Useful
[sampleWithReplacements](#samplewithreplacements)	`O(k)`	`O(k)`	Performant
[samplePairs](#samplepairs)	`Ω(k)`,	`O(k)`	Variant
[sampleOrderedPairs](#sampleorderedpairs)	`Ω(k)`,	`O(k)`	Variant
[weightedReservoirSample](#weightedreservoirsample)	`O(n)`	`O(k)`	Variant

choice

Function returning a random item from the given array.

```js
import choice from 'pandemonium/choice';
// Or
import {choice} from 'pandemonium';
choice(['apple', 'orange', 'pear']);
>>> 'orange'
// To create your own function using custom RNG
import {createChoice} from 'pandemonium/choice';
const customChoice = createChoice(rng);
```

random

Function returning a random integer between given a & b.

```js
import random from 'pandemonium/random';
// Or
import {random} from 'pandemonium';
random(3, 7);
>>> 4
// To create your own function using custom RNG
import {createRandom} from 'pandemonium/random';
const customRandom = createRandom(rng);
```

randomBoolean

Function returning a random boolean.

```js
import randomBoolean from 'pandemonium/random-boolean';
// Or
import {randomBoolean} from 'pandemonium';
randomBoolean();
>>> true
// To create your own function using custom RNG
import {createrandomBoolean} from 'pandemonium/random-boolean';
const customRandomBoolean = createRandomBoolean(rng);
```

randomFloat

Function returning a random float between given a & b.

```js
import randomFloat from 'pandemonium/random-float';
// Or
import {randomFloat} from 'pandemonium';
randomFloat(-5, 55);
>>> 6.756482
// To create your own function using custom RNG
import {createRandomFloat} from 'pandemonium/random-float';
const customRandomFloat = createRandomFloat(rng);
```

randomIndex

Function returning a random index of the given array.

```js
import randomIndex from 'pandemonium/random-index';
// Or
import {randomIndex} from 'pandemonium';
randomIndex(['apple', 'orange', 'pear']);
>>> 1
// Alternatively, you can give the array's length instead
randomIndex(3);
>>> 2
// To create your own function using custom RNG
import {createRandomIndex} from 'pandemonium/random-index';
const customRandomIndex = createRandomIndex(rng);
```

randomString

Function returning a random string.

```js
import randomString from 'pandemonium/random-string';
// Or
import {randomString} from 'pandemonium';
// To generate a string of fixed length
randomString(5);
>>> 'gHepM'
// To generate a string of variable length
randomString(3, 7);
>>> 'hySf3'
// To create your own function using custom RNG
import {createRandomString} from 'pandemonium/random-string';
const customRandomString = createRandomString(rng);
// If you need a custom alphabet
const customRandomString = createRandomString(rng, 'ATGC');
```

randomUint32

Function returning a random unsigned 32bits number.

```js
import {randomUint32} from 'pandemonium/random-typed-int';
// Or
import {randomUint32} from 'pandemonium';
randomUint32();
>>> 397536
// To create your own function using custom RNG
import {createRandomUint32} from 'pandemonium/random-typed-int';
const customRandomUint32 = createRandomUint32(rng);
```

randomPair

Function returning a random pair from the given array.

Note that this function will return unordered pairs (i.e. [0, 1] and [1, 0] are to be considered the same) and will not return pairs containing twice the same item (i.e. [0, 0]).

```js
import randomPair from 'pandemonium/random-pair';
// Or
import {randomPair} from 'pandemonium';
randomPair(['apple', 'orange', 'pear', 'cherry']);
>>> ['orange', 'cherry']
// Alternatively, you can give the array's length instead and get a pair of indices
randomPair(4);
>>> [1, 3]
// To create your own function using custom RNG
import {createRandomPair} from 'pandemonium/random-pair';
const customRandomPair = createRandomPair(rng);
```

randomOrderedPair

Function returning a random ordered pair (i.e. [0, 1] won't be considered to be the same as [1, 0]) from the given array.

```js
import randomOrderedPair from 'pandemonium/random-ordered-pair';
// Or
import {randomOrderedPair} from 'pandemonium';
randomOrderedPair(['apple', 'orange', 'pear', 'cherry']);
>>> ['cherry', 'apple']
// Alternatively, you can give the array's length instead and get a pair of indices
randomOrderedPair(4);
>>> [3, 0]
// To create your own function using custom RNG
import {createRandomOrderedPair} from 'pandemonium/random-ordered-pair';
const customRandomPair = createRandomOrderedPair(rng);
```

shuffle

Function returning a shuffled version of the given array using the Fisher-Yates algorithm.

If what you need is to shuffle the original array in place, check out [shuffleInPlace](#shuffleinplace).

```js
import shuffle from 'pandemonium/shuffle';
// Or
import {shuffle} from 'pandemonium';
shuffle(['apple', 'orange', 'pear', 'pineapple']);
>>> ['pear', 'orange', 'apple', 'pineapple']
// To create your own function using custom RNG
import {createShuffle} from 'pandemonium/shuffle';
const customShuffle = createShuffle(rng);
```

shuffleInPlace

Function shuffling the given array in place using the Fisher-Yates algorithm.

```js
import shuffleInPlace from 'pandemonium/shuffle-in-place';
// Or
import {shuffleInPlace} from 'pandemonium';
const array = ['apple', 'orange', 'pear', 'pineapple'];
shuffleInPlace(array);
// Array was mutated:
array >>> ['pear', 'orange', 'apple', 'pineapple'];
// To create your own function using custom RNG
import {createShuffleInPlace} from 'pandemonium/shuffle-in-place';
const customShuffleInPlace = createShuffleInPlace(rng);
```

weightedChoice

Function returning a random item from the given array of weights.

Note that weights don't need to be relative.

```js
import weightedChoice from 'pandemonium/weighted-choice';
// Or
import {weightedChoice} from 'pandemonium';
const array = [.1, .1, .4, .3, .1];
weightedChoice(array);
>>> .4
// To create your own function using custom RNG
import {createWeightedChoice} from 'pandemonium/weighted-choice';
const customWeightedChoice = createWeightedChoice(rng);
// If you have an array of objects
const customWeightedChoice = createWeightedChoice({
rng: rng,
getWeight: (item, index) => {
return item.weight;
}
});
const array = [{fruit: 'pear', weight: 4}, {fruit: 'apple', weight: 30}];
customWeightedChoice(array);
>>> 'apple'
// If you intent to call the function multiple times on the same array,
// you should use the cached version instead:
import {createCachedWeightedChoice} from 'pandemonium/weighted-choice';
const array = [.1, .1, .4, .3, .1];
const customWeightedChoice = createCachedWeightedChoice(rng, array);
customWeightedChoice();
>>> .3
```

weightedRandomIndex

Function returning a random index from the given array of weights.

Note that weights don't need to be relative.

```js
import weightedRandomIndex from 'pandemonium/weighted-random-index';
// Or
import {weightedRandomIndex} from 'pandemonium';
const array = [.1, .1, .4, .3, .1];
weightedRandomIndex(array);
>>> 2
// To create your own function using custom RNG
import {createWeightedRandomIndex} from 'pandemonium/weighted-random-index';
const customWeightedRandomIndex = createWeightedRandomIndex(rng);
// If you have an array of objects
const customWeightedRandomIndex = createWeightedRandomIndex({
rng: rng,
getWeight: (item, index) => {
return item.weight;
}
});
const array = [{fruit: 'pear', weight: 4}, {fruit: 'apple', weight: 30}];
customWeightedRandomIndex(array);
>>> 1
// If you intent to call the function multiple times on the same array,
// you should use the cached version instead:
import {createCachedWeightedRandomIndex} from 'pandemonium/weighted-random-index';
const array = [.1, .1, .4, .3, .1];
const customWeightedRandomIndex = createCachedWeightedRandomIndex(rng, array);
customWeightedRandomIndex();
>>> 3
```