Add combinations.

src/algorithms/math/combinations/README.md

@@ -0,0 +1,55 @@
+# Combinations
+
+When the order doesn't matter, it is a **Combination**.
+
+When the order **does** matter it is a **Permutation**.
+
+**"My fruit salad is a combination of apples, grapes and bananas"**
+We don't care what order the fruits are in, they could also be 
+"bananas, grapes and apples" or "grapes, apples and bananas", 
+its the same fruit salad.
+
+## Combinations without repetitions
+
+This is how lotteries work. The numbers are drawn one at a 
+time, and if we have the lucky numbers (no matter what order) 
+we win!
+
+No Repetition: such as lottery numbers `(2,14,15,27,30,33)`
+
+**Number of combinations**
+
+![Formula](https://www.mathsisfun.com/combinatorics/images/combinations-no-repeat.png)
+
+where `n` is the number of things to choose from, and we choose `r` of them,
+no repetition, order doesn't matter.
+
+It is often called "n choose r" (such as "16 choose 3"). And is also known as the Binomial Coefficient.
+
+## Combinations with repetitions
+
+Repetition is Allowed: such as coins in your pocket `(5,5,5,10,10)`
+
+Or let us say there are five flavours of icecream: 
+`banana`, `chocolate`, `lemon`, `strawberry` and `vanilla`.
+
+We can have three scoops. How many variations will there be?
+
+Let's use letters for the flavours: `{b, c, l, s, v}`. 
+Example selections include:
+
+- `{c, c, c}` (3 scoops of chocolate)
+- `{b, l, v}` (one each of banana, lemon and vanilla)
+- `{b, v, v}` (one of banana, two of vanilla)
+
+**Number of combinations**
+
+![Formula](https://www.mathsisfun.com/combinatorics/images/combinations-repeat.gif)
+
+Where `n` is the number of things to choose from, and we 
+choose `r` of them. Repetition allowed, 
+order doesn't matter.
+
+## References
+
+[Math Is Fun](https://www.mathsisfun.com/combinatorics/combinations-permutations.html)

src/algorithms/math/combinations/__test__/combineWithRepetitions.test.js

@@ -0,0 +1,59 @@
+import combineWithRepetitions from '../combineWithRepetitions';
+import factorial from '../../factorial/factorial';
+
+describe('combineWithRepetitions', () => {
+  it('should combine string with repetitions', () => {
+    expect(combineWithRepetitions(['A'], 1)).toEqual([
+      ['A'],
+    ]);
+
+    expect(combineWithRepetitions(['A', 'B'], 1)).toEqual([
+      ['A'],
+      ['B'],
+    ]);
+
+    expect(combineWithRepetitions(['A', 'B'], 2)).toEqual([
+      ['A', 'A'],
+      ['A', 'B'],
+      ['B', 'B'],
+    ]);
+
+    expect(combineWithRepetitions(['A', 'B'], 3)).toEqual([
+      ['A', 'A', 'A'],
+      ['A', 'A', 'B'],
+      ['A', 'B', 'B'],
+      ['B', 'B', 'B'],
+    ]);
+
+    expect(combineWithRepetitions(['A', 'B', 'C'], 2)).toEqual([
+      ['A', 'A'],
+      ['A', 'B'],
+      ['A', 'C'],
+      ['B', 'B'],
+      ['B', 'C'],
+      ['C', 'C'],
+    ]);
+
+    expect(combineWithRepetitions(['A', 'B', 'C'], 3)).toEqual([
+      ['A', 'A', 'A'],
+      ['A', 'A', 'B'],
+      ['A', 'A', 'C'],
+      ['A', 'B', 'B'],
+      ['A', 'B', 'C'],
+      ['A', 'C', 'C'],
+      ['B', 'B', 'B'],
+      ['B', 'B', 'C'],
+      ['B', 'C', 'C'],
+      ['C', 'C', 'C'],
+    ]);
+
+    const combinationOptions = ['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H'];
+    const combinationSlotsNumber = 4;
+    const combinations = combineWithRepetitions(combinationOptions, combinationSlotsNumber);
+    const n = combinationOptions.length;
+    const r = combinationSlotsNumber;
+    const expectedNumberOfCombinations = factorial((r + n) - 1) / (factorial(r) * factorial(n - 1));
+
+    expect(combinations.length).toBe(expectedNumberOfCombinations);
+  });
+});

src/algorithms/math/combinations/__test__/combineWithoutRepetitions.test.js

@@ -0,0 +1,60 @@
+import combineWithoutRepetitions from '../combineWithoutRepetitions';
+import factorial from '../../factorial/factorial';
+
+describe('combineWithoutRepetitions', () => {
+  it('should combine string without repetitions', () => {
+    expect(combineWithoutRepetitions(['A', 'B'], 3)).toEqual([]);
+
+    expect(combineWithoutRepetitions(['A', 'B'], 1)).toEqual([
+      ['A'],
+      ['B'],
+    ]);
+
+    expect(combineWithoutRepetitions(['A'], 1)).toEqual([
+      ['A'],
+    ]);
+
+    expect(combineWithoutRepetitions(['A', 'B'], 2)).toEqual([
+      ['A', 'B'],
+    ]);
+
+    expect(combineWithoutRepetitions(['A', 'B', 'C'], 2)).toEqual([
+      ['A', 'B'],
+      ['A', 'C'],
+      ['B', 'C'],
+    ]);
+
+    expect(combineWithoutRepetitions(['A', 'B', 'C'], 3)).toEqual([
+      ['A', 'B', 'C'],
+    ]);
+
+    expect(combineWithoutRepetitions(['A', 'B', 'C', 'D'], 3)).toEqual([
+      ['A', 'B', 'C'],
+      ['A', 'B', 'D'],
+      ['A', 'C', 'D'],
+      ['B', 'C', 'D'],
+    ]);
+
+    expect(combineWithoutRepetitions(['A', 'B', 'C', 'D', 'E'], 3)).toEqual([
+      ['A', 'B', 'C'],
+      ['A', 'B', 'D'],
+      ['A', 'B', 'E'],
+      ['A', 'C', 'D'],
+      ['A', 'C', 'E'],
+      ['A', 'D', 'E'],
+      ['B', 'C', 'D'],
+      ['B', 'C', 'E'],
+      ['B', 'D', 'E'],
+      ['C', 'D', 'E'],
+    ]);
+
+    const combinationOptions = ['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H'];
+    const combinationSlotsNumber = 4;
+    const combinations = combineWithoutRepetitions(combinationOptions, combinationSlotsNumber);
+    const n = combinationOptions.length;
+    const r = combinationSlotsNumber;
+    const expectedNumberOfCombinations = factorial(n) / (factorial(r) * factorial(n - r));
+
+    expect(combinations.length).toBe(expectedNumberOfCombinations);
+  });
+});

src/algorithms/math/combinations/combineWithRepetitions.js

@@ -0,0 +1,38 @@
+/**
+ * @param {*[]} combinationOptions
+ * @param {number} combinationLength
+ * @return {*[]}
+ */
+
+export default function combineWithRepetitions(combinationOptions, combinationLength) {
+  // If combination length equal to 0 then return empty combination.
+  if (combinationLength === 0) {
+    return [[]];
+  }
+
+  // If combination options are empty then return "no-combinations" array.
+  if (combinationOptions.length === 0) {
+    return [];
+  }
+
+  // Init combinations array.
+  const combos = [];
+
+  // Find all shorter combinations and attach head to each of those.
+  const headCombo = [combinationOptions[0]];
+  const shorterCombos = combineWithRepetitions(combinationOptions, combinationLength - 1);
+
+  for (let combinationIndex = 0; combinationIndex < shorterCombos.length; combinationIndex += 1) {
+    const combo = headCombo.concat(shorterCombos[combinationIndex]);
+    combos.push(combo);
+  }
+
+  // Let's shift head to the right and calculate all the rest combinations.
+  const combinationsWithoutHead = combineWithRepetitions(
+    combinationOptions.slice(1),
+    combinationLength,
+  );
+
+  // Join all combinations and return them.
+  return combos.concat(combinationsWithoutHead);
+}

src/algorithms/math/combinations/combineWithoutRepetitions.js

@@ -0,0 +1,68 @@
+/*
+  @see: https://stackoverflow.com/a/127898/7794070
+
+  Lets say your array of letters looks like this: "ABCDEFGH".
+  You have three indices (i, j, k) indicating which letters you
+  are going to use for the current word, You start with:
+
+  A B C D E F G H
+  ^ ^ ^
+  i j k
+
+  First you vary k, so the next step looks like that:
+
+  A B C D E F G H
+  ^ ^   ^
+  i j   k
+
+  If you reached the end you go on and vary j and then k again.
+
+  A B C D E F G H
+  ^   ^ ^
+  i   j k
+
+  A B C D E F G H
+  ^   ^   ^
+  i   j   k
+
+  Once you j reached G you start also to vary i.
+
+  A B C D E F G H
+    ^ ^ ^
+    i j k
+
+  A B C D E F G H
+    ^ ^   ^
+    i j   k
+  ...
+ */
+
+/**
+ * @param {*[]} combinationOptions
+ * @param {number} combinationLength
+ * @return {*[]}
+ */
+export default function combineWithoutRepetitions(combinationOptions, combinationLength) {
+  // If combination length is just 1 then return combinationOptions.
+  if (combinationLength === 1) {
+    return combinationOptions.map(option => [option]);
+  }
+
+  // Init combinations array.
+  const combinations = [];
+
+  for (let i = 0; i <= (combinationOptions.length - combinationLength); i += 1) {
+    const smallerCombinations = combineWithoutRepetitions(
+      combinationOptions.slice(i + 1),
+      combinationLength - 1,
+    );
+
+    for (let j = 0; j < smallerCombinations.length; j += 1) {
+      const combination = [combinationOptions[i]].concat(smallerCombinations[j]);
+      combinations.push(combination);
+    }
+  }
+
+  // Return all calculated combinations.
+  return combinations;
+}

src/algorithms/math/permutations/README.md

@@ -0,0 +1,42 @@
+# Permutations
+
+When the order doesn't matter, it is a **Combination**.
+
+When the order **does** matter it is a **Permutation**.
+
+**"The combination to the safe is 472"**. We do care about the order. `724` won't work, nor will `247`. 
+It has to be exactly `4-7-2`.
+
+## Permutations without repetitions
+
+A permutation, also called an “arrangement number” or “order”, is a rearrangement of 
+the elements of an ordered list `S` into a one-to-one correspondence with `S` itself. 
+
+Below are the permutations of string `ABC`.
+
+`ABC ACB BAC BCA CBA CAB`
+
+Or for example the first three people in a running race: you can't be first and second.
+
+**Number of combinations**
+
+```
+n * (n-1) * (n -2) * ... * 1 = n!
+```
+
+## Permutations with repetitions
+
+When repetition is allowed we have permutations with repetitions.
+For example the the lock below: it could be `333`.
+
+![Permutation Lock](https://www.mathsisfun.com/combinatorics/images/combination-lock.jpg)
+
+**Number of combinations**
+
+```
+n * n * n ... (r times) = n^r
+```
+
+## References
+
+[Math Is Fun](https://www.mathsisfun.com/combinatorics/combinations-permutations.html)

src/algorithms/math/permutations/__test__/permutateWithRepetitions.test.js

@@ -0,0 +1,55 @@
+import permutateWithRepetitions from '../permutateWithRepetitions';
+
+describe('permutateWithRepetitions', () => {
+  it('should permutate string with repetition', () => {
+    const permutations0 = permutateWithRepetitions([]);
+    expect(permutations0).toEqual([]);
+
+    const permutations1 = permutateWithRepetitions(['A']);
+    expect(permutations1).toEqual([
+      ['A'],
+    ]);
+
+    const permutations2 = permutateWithRepetitions(['A', 'B']);
+    expect(permutations2).toEqual([
+      ['A', 'A'],
+      ['A', 'B'],
+      ['B', 'A'],
+      ['B', 'B'],
+    ]);
+
+    const permutations3 = permutateWithRepetitions(['A', 'B', 'C']);
+    expect(permutations3).toEqual([
+      ['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'],
+    ]);
+
+    const permutations4 = permutateWithRepetitions(['A', 'B', 'C', 'D']);
+    expect(permutations4.length).toBe(4 * 4 * 4 * 4);
+  });
+});

src/algorithms/math/permutations/__test__/permutateWithoutRepetitions.test.js

@@ -0,0 +1,71 @@
+import permutateWithoutRepetitions from '../permutateWithoutRepetitions';
+import factorial from '../../factorial/factorial';
+
+describe('permutateWithoutRepetitions', () => {
+  it('should permutate string', () => {
+    const permutations0 = permutateWithoutRepetitions([]);
+    expect(permutations0).toEqual([]);
+
+    const permutations1 = permutateWithoutRepetitions(['A']);
+    expect(permutations1).toEqual([
+      ['A'],
+    ]);
+
+    const permutations2 = permutateWithoutRepetitions(['A', 'B']);
+    expect(permutations2.length).toBe(2);
+    expect(permutations2).toEqual([
+      ['B', 'A'],
+      ['A', 'B'],
+    ]);
+
+    const permutations6 = permutateWithoutRepetitions(['A', 'A']);
+    expect(permutations6.length).toBe(2);
+    expect(permutations6).toEqual([
+      ['A', 'A'],
+      ['A', 'A'],
+    ]);
+
+    const permutations3 = permutateWithoutRepetitions(['A', 'B', 'C']);
+    expect(permutations3.length).toBe(factorial(3));
+    expect(permutations3).toEqual([
+      ['C', 'B', 'A'],
+      ['B', 'C', 'A'],
+      ['B', 'A', 'C'],
+      ['C', 'A', 'B'],
+      ['A', 'C', 'B'],
+      ['A', 'B', 'C'],
+    ]);
+
+    const permutations4 = permutateWithoutRepetitions(['A', 'B', 'C', 'D']);
+    expect(permutations4.length).toBe(factorial(4));
+    expect(permutations4).toEqual([
+      ['D', 'C', 'B', 'A'],
+      ['C', 'D', 'B', 'A'],
+      ['C', 'B', 'D', 'A'],
+      ['C', 'B', 'A', 'D'],
+      ['D', 'B', 'C', 'A'],
+      ['B', 'D', 'C', 'A'],
+      ['B', 'C', 'D', 'A'],
+      ['B', 'C', 'A', 'D'],
+      ['D', 'B', 'A', 'C'],
+      ['B', 'D', 'A', 'C'],
+      ['B', 'A', 'D', 'C'],
+      ['B', 'A', 'C', 'D'],
+      ['D', 'C', 'A', 'B'],
+      ['C', 'D', 'A', 'B'],
+      ['C', 'A', 'D', 'B'],
+      ['C', 'A', 'B', 'D'],
+      ['D', 'A', 'C', 'B'],
+      ['A', 'D', 'C', 'B'],
+      ['A', 'C', 'D', 'B'],
+      ['A', 'C', 'B', 'D'],
+      ['D', 'A', 'B', 'C'],
+      ['A', 'D', 'B', 'C'],
+      ['A', 'B', 'D', 'C'],
+      ['A', 'B', 'C', 'D'],
+    ]);
+
+    const permutations5 = permutateWithoutRepetitions(['A', 'B', 'C', 'D', 'E', 'F']);
+    expect(permutations5.length).toBe(factorial(6));
+  });
+});

src/algorithms/math/permutations/permutateWithRepetitions.js

@@ -0,0 +1,42 @@
+/**
+ * @param {*[]} permutationOptions
+ * @return {*[]}
+ */
+export default function permutateWithRepetitions(permutationOptions) {
+  // There is no permutations for empty array.
+  if (!permutationOptions || permutationOptions.length === 0) {
+    return [];
+  }
+
+  // There is only one permutation for the 1-element array.
+  if (permutationOptions.length === 1) {
+    return [permutationOptions];
+  }
+
+  // Let's create initial set of permutations.
+  let previousPermutations = permutationOptions.map(option => [option]);
+  let currentPermutations = [];
+  let permutationSize = 1;
+
+  // While the size of each permutation is less then or equal to options length...
+  while (permutationSize < permutationOptions.length) {
+    // Reset all current permutations.
+    currentPermutations = [];
+
+    for (let permIndex = 0; permIndex < previousPermutations.length; permIndex += 1) {
+      for (let optionIndex = 0; optionIndex < permutationOptions.length; optionIndex += 1) {
+        let currentPermutation = previousPermutations[permIndex];
+        currentPermutation = currentPermutation.concat([permutationOptions[optionIndex]]);
+        currentPermutations.push(currentPermutation);
+      }
+    }
+
+    // Make current permutations to be the previous ones.
+    previousPermutations = currentPermutations.slice(0);
+
+    // Increase permutation size counter.
+    permutationSize += 1;
+  }
+
+  return currentPermutations;
+}

src/algorithms/math/permutations/permutateWithoutRepetitions.js

@@ -0,0 +1,39 @@
+/**
+ * @param {*[]} permutationOptions
+ * @return {*[]}
+ */
+export default function permutateWithoutRepetitions(permutationOptions) {
+  if (permutationOptions.length === 0) {
+    return [];
+  }
+
+  if (permutationOptions.length === 1) {
+    return [permutationOptions];
+  }
+
+  const permutations = [];
+
+  // Get all permutations of length (n - 1).
+  const previousOptions = permutationOptions.slice(0, permutationOptions.length - 1);
+  const previousPermutations = permutateWithoutRepetitions(previousOptions);
+
+  // Insert last option into every possible position of every previous permutation.
+  const lastOption = permutationOptions.slice(permutationOptions.length - 1);
+
+  for (
+    let permutationIndex = 0;
+    permutationIndex < previousPermutations.length;
+    permutationIndex += 1
+  ) {
+    const currentPermutation = previousPermutations[permutationIndex];
+
+    // Insert last option into every possible position of currentPermutation.
+    for (let positionIndex = 0; positionIndex <= currentPermutation.length; positionIndex += 1) {
+      const permutationPrefix = currentPermutation.slice(0, positionIndex);
+      const permutationSuffix = currentPermutation.slice(positionIndex);
+      permutations.push(permutationPrefix.concat(lastOption, permutationSuffix));
+    }
+  }
+
+  return permutations;
+}