Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/acarl005/generatorics

An efficient combinatorics library for JavaScript utilizing ES2015 generators.
https://github.com/acarl005/generatorics

combination combinatorics generator permutation powerset

Last synced: 16 days ago
JSON representation

An efficient combinatorics library for JavaScript utilizing ES2015 generators.

Lists

README 

        
# Generatorics



### An efficient combinatorics library for JavaScript utilizing ES2015 generators. Generate combinations, permutations, and power sets of arrays or strings.



- Node

```

npm install generatorics

```

```javascript

var G = require('generatorics');

```



- Browser

```

bower install generatorics

```

```html



```



**Note:** This module is not transpiled for compatibility, as it degrades the performance. Check your browser/node version.



## Usage



### power set

```javascript

for (var subset of G.powerSet(['a', 'b', 'c'])) {

  console.log(subset);

}

// [ ]

// [ 'a' ]

// [ 'a', 'b' ]

// [ 'a', 'b', 'c' ]

// [ 'a', 'c' ]

// [ 'b' ]

// [ 'b', 'c' ]

// [ 'c' ]

```



### permutation

```javascript

for (var perm of G.permutation(['a', 'b', 'c'], 2)) {

  console.log(perm);

}

// [ 'a', 'b' ]

// [ 'a', 'c' ]

// [ 'b', 'a' ]

// [ 'b', 'c' ]

// [ 'c', 'a' ]

// [ 'c', 'b' ]



for (var perm of G.permutation(['a', 'b', 'c'])) { // assumes full length of array

  console.log(perm);

}

// [ 'a', 'b', 'c' ]

// [ 'a', 'c', 'b' ]

// [ 'b', 'a', 'c' ]

// [ 'b', 'c', 'a' ]

// [ 'c', 'b', 'a' ]

// [ 'c', 'a', 'b' ]

```



### combination

```javascript

for (var comb of G.combination(['a', 'b', 'c'], 2)) {

  console.log(comb);

}

// [ 'a', 'b' ]

// [ 'a', 'c' ]

// [ 'b', 'c' ]

```



For efficiency, each array being yielded is the same one being mutated on each iteration. **DO NOT** mutate the array.

```javascript

var combs = [];

for (var comb of G.combination(['a', 'b', 'c'], 2)) {

  combs.push(comb);

}

console.log(combs);

// [ [ 'b', 'c' ], [ 'b', 'c' ], [ 'b', 'c' ] ]

```

You can clone if necessary, or use the [clone submodule](#clone-submodule)



### permutation of combination

```javascript

for (var perm of G.permutationCombination(['a', 'b', 'c'])) {

  console.log(perm);

}

// [ ]

// [ 'a' ]

// [ 'a', 'b' ]

// [ 'a', 'b', 'c' ]

// [ 'a', 'c' ]

// [ 'a', 'c', 'b' ]

// [ 'b' ]

// [ 'b', 'a' ]

// [ 'b', 'a', 'c' ]

// [ 'b', 'c' ]

// [ 'b', 'c', 'a' ]

// [ 'c' ]

// [ 'c', 'a' ]

// [ 'c', 'a', 'b' ]

// [ 'c', 'b' ]

// [ 'c', 'b', 'a' ]

```



### cartesian product

```javascript

for (var prod of G.cartesian([0, 1, 2], [0, 10, 20], [0, 100, 200])) {

  console.log(prod);

}

// [ 0, 0, 0 ],  [ 0, 0, 100 ],  [ 0, 0, 200 ]

// [ 0, 10, 0 ], [ 0, 10, 100 ], [ 0, 10, 200 ]

// [ 0, 20, 0 ], [ 0, 20, 100 ], [ 0, 20, 200 ]

// [ 1, 0, 0 ],  [ 1, 0, 100 ],  [ 1, 0, 200 ]

// [ 1, 10, 0 ], [ 1, 10, 100 ], [ 1, 10, 200 ]

// [ 1, 20, 0 ], [ 1, 20, 100 ], [ 1, 20, 200 ]

// [ 2, 0, 0 ],  [ 2, 0, 100 ],  [ 2, 0, 200 ]

// [ 2, 10, 0 ], [ 2, 10, 100 ], [ 2, 10, 200 ]

// [ 2, 20, 0 ], [ 2, 20, 100 ], [ 2, 20, 200 ]

```



### base N

```javascript

for (var num of G.baseN(['a', 'b', 'c'])) {

  console.log(num);

}

// [ 'a', 'a', 'a' ], [ 'a', 'a', 'b' ], [ 'a', 'a', 'c' ]

// [ 'a', 'b', 'a' ], [ 'a', 'b', 'b' ], [ 'a', 'b', 'c' ]

// [ 'a', 'c', 'a' ], [ 'a', 'c', 'b' ], [ 'a', 'c', 'c' ]

// [ 'b', 'a', 'a' ], [ 'b', 'a', 'b' ], [ 'b', 'a', 'c' ]

// [ 'b', 'b', 'a' ], [ 'b', 'b', 'b' ], [ 'b', 'b', 'c' ]

// [ 'b', 'c', 'a' ], [ 'b', 'c', 'b' ], [ 'b', 'c', 'c' ]

// [ 'c', 'a', 'a' ], [ 'c', 'a', 'b' ], [ 'c', 'a', 'c' ]

// [ 'c', 'b', 'a' ], [ 'c', 'b', 'b' ], [ 'c', 'b', 'c' ]

// [ 'c', 'c', 'a' ], [ 'c', 'c', 'b' ], [ 'c', 'c', 'c' ]

```



## Clone Submodule

Each array yielded from the generator is actually the same array in memory, just mutated to have different elements. This is to avoid the unnecessary creation of a bunch of arrays, which consume memory. As a result, you get a strange result when trying to generate an array.

```javascript

var combs = G.combination(['a', 'b', 'c'], 2);

console.log([...combs]);

// [ [ 'b', 'c' ], [ 'b', 'c' ], [ 'b', 'c' ] ]

```

Instead, you can use the clone submodule.

```javascript

var combs = G.clone.combination(['a', 'b', 'c'], 2);

console.log([...combs]);

// [ [ 'a', 'b' ], [ 'a', 'c' ], [ 'b', 'c' ] ]

```



### G.clone

This submodule produces generators that yield a different array on each iteration in case you need to mutate it. The [combination](#module_G.combination), [permutation](#module_G.permutation), [powerSet](#module_G.powerSet), [permutationCombination](#module_G.permutationCombination), [baseN](#module_G.baseN), [baseNAll](#module_G.baseNAll), and [cartesian](#module_G.cartesian) methods are provided on this submodule.



## Cool things to do with ES2015 generators

```javascript

var combs = G.clone.combination([1, 2, 3], 2);



// "for-of" loop

for (let comb of combs) {

  console.log(comb);

}



// generate arrays

Array.from(combs);

[...combs];



// generate sets

new Set(combs);



// spreading in function calls

console.log(...combs);

```



#### Writing a code generator? Need to produce an infinite stream of minified variable names?



No problem! Just pass in a collection of all your valid characters and start generating.



```javascript

var mininym = G.baseNAll('abcdefghijklmnopqrstuvwxyz$#')

var name = mininym.next().value.join('')

global[name] = 'some value'

```



#### Card games anyone?

```javascript

var cards = [...G.clone.cartesian('♠♥♣♦', 'A23456789JQK')];

console.log(G.shuffle(cards));

// [ [ '♦', '6' ], [ '♠', '6' ], [ '♣', '7' ], [ '♥', 'K' ],

//   [ '♣', 'J' ], [ '♥', '4' ], [ '♦', '2' ], [ '♥', '9' ],

//   [ '♦', 'Q' ], [ '♠', 'Q' ], [ '♠', '4' ], [ '♠', 'K' ],

//   [ '♥', '3' ], [ '♥', '7' ], [ '♠', '5' ], [ '♦', '7' ],

//   [ '♥', '5' ], [ '♣', 'Q' ], [ '♣', '9' ], [ '♠', 'A' ],

//   [ '♣', '4' ], [ '♣', '3' ], [ '♥', 'A' ], [ '♥', '8' ],

//   [ '♣', '8' ], [ '♦', '8' ], [ '♠', '8' ], [ '♣', '5' ],

//   [ '♥', '2' ], [ '♥', 'Q' ], [ '♦', 'A' ], [ '♥', '6' ],

//   [ '♠', '2' ], [ '♣', '6' ], [ '♠', '3' ], [ '♦', 'K' ],

//   [ '♦', 'J' ], [ '♠', '7' ], [ '♥', 'J' ], [ '♦', '5' ],

//   [ '♦', '9' ], [ '♦', '3' ], [ '♠', '9' ], [ '♣', '2' ],

//   [ '♣', 'A' ], [ '♣', 'K' ], [ '♦', '4' ], [ '♠', 'J' ] ]

```



## Documentation




## G



* [G](#module_G)

    * [.factorial(n)](#module_G.factorial) ⇒ Number

    * [.factoradic(n)](#module_G.factoradic) ⇒ Array

    * [.P(n, k)](#module_G.P) ⇒ Number

    * [.C(n, k)](#module_G.C) ⇒ Number

    * [.choices(n, k, [options])](#module_G.choices) ⇒ Number

    * [.combination(arr, [size])](#module_G.combination) ⇒ Generator

    * [.permutation(arr, [size])](#module_G.permutation) ⇒ Generator

    * [.powerSet(arr)](#module_G.powerSet) ⇒ Generator

    * [.permutationCombination(arr)](#module_G.permutationCombination) ⇒ Generator

    * [.baseN(arr, [size])](#module_G.baseN) ⇒ Generator

    * [.baseNAll(arr)](#module_G.baseNAll) ⇒ Generator

    * [.cartesian(...sets)](#module_G.cartesian) ⇒ Generator

    * [.shuffle(arr)](#module_G.shuffle) ⇒ Array






### G.factorial(n) ⇒ Number

Calculates a factorial



**Kind**: static method of [G](#module_G)  

**Returns**: Number - n!  



| Param | Type | Description |

| --- | --- | --- |

| n | Number | The number to operate the factorial on. |






### G.factoradic(n) ⇒ Array

Converts a number to the factorial number system. Digits are in least significant order.



**Kind**: static method of [G](#module_G)  

**Returns**: Array - digits of n in factoradic in least significant order  



| Param | Type | Description |

| --- | --- | --- |

| n | Number | Integer in base 10 |






### G.P(n, k) ⇒ Number

Calculates the number of possible permutations of "k" elements in a set of size "n".



**Kind**: static method of [G](#module_G)  

**Returns**: Number - n P k  



| Param | Type | Description |

| --- | --- | --- |

| n | Number | Number of elements in the set. |

| k | Number | Number of elements to choose from the set. |






### G.C(n, k) ⇒ Number

Calculates the number of possible combinations of "k" elements in a set of size "n".



**Kind**: static method of [G](#module_G)  

**Returns**: Number - n C k  



| Param | Type | Description |

| --- | --- | --- |

| n | Number | Number of elements in the set. |

| k | Number | Number of elements to choose from the set. |






### G.choices(n, k, [options]) ⇒ Number

Higher level method for counting number of possible combinations of "k" elements from a set of size "n".



**Kind**: static method of [G](#module_G)  

**Returns**: Number - Number of possible combinations.  



| Param | Type | Description |

| --- | --- | --- |

| n | Number | Number of elements in the set. |

| k | Number | Number of elements to choose from the set. |

| [options] | Object |  |

| options.replace | Boolean | Is replacement allowed after each choice? |

| options.ordered | Boolean | Does the order of the choices matter? |






### G.combination(arr, [size]) ⇒ Generator

Generates all combinations of a set.



**Kind**: static method of [G](#module_G)  

**Returns**: Generator - yields each combination as an array  



| Param | Type | Default | Description |

| --- | --- | --- | --- |

| arr | Array | String |  | The set of elements. |

| [size] | Number | arr.length | Number of elements to choose from the set. |






### G.permutation(arr, [size]) ⇒ Generator

Generates all permutations of a set.



**Kind**: static method of [G](#module_G)  

**Returns**: Generator - yields each permutation as an array  



| Param | Type | Default | Description |

| --- | --- | --- | --- |

| arr | Array | String |  | The set of elements. |

| [size] | Number | arr.length | Number of elements to choose from the set. |






### G.powerSet(arr) ⇒ Generator

Generates all possible subsets of a set (a.k.a. power set).



**Kind**: static method of [G](#module_G)  

**Returns**: Generator - yields each subset as an array  



| Param | Type | Description |

| --- | --- | --- |

| arr | Array | String | The set of elements. |






### G.permutationCombination(arr) ⇒ Generator

Generates the permutation of the combinations of a set.



**Kind**: static method of [G](#module_G)  

**Returns**: Generator - yields each permutation as an array  



| Param | Type | Description |

| --- | --- | --- |

| arr | Array | String | The set of elements. |






### G.baseN(arr, [size]) ⇒ Generator

Generates all possible "numbers" from the digits of a set.



**Kind**: static method of [G](#module_G)  

**Returns**: Generator - yields all digits as an array  



| Param | Type | Default | Description |

| --- | --- | --- | --- |

| arr | Array | String |  | The set of digits. |

| [size] | Number | arr.length | How many digits will be in the numbers. |






### G.baseNAll(arr) ⇒ Generator

Infinite generator for all possible "numbers" from a set of digits.



**Kind**: static method of [G](#module_G)  

**Returns**: Generator - yields all digits as an array  



| Param | Type | Description |

| --- | --- | --- |

| arr | Array | String | The set of digits |






### G.cartesian(...sets) ⇒ Generator

Generates the cartesian product of the sets.



**Kind**: static method of [G](#module_G)  

**Returns**: Generator - yields each product as an array  



| Param | Type | Description |

| --- | --- | --- |

| ...sets | Array | String | variable number of sets of n elements. |






### G.shuffle(arr) ⇒ Array

Shuffles an array in place using the Fisher–Yates shuffle.



**Kind**: static method of [G](#module_G)  

**Returns**: Array - a random, unbiased perutation of arr  



| Param | Type | Description |

| --- | --- | --- |

| arr | Array | A set of elements. |