Add permutations generator

README.md

@@ -532,9 +532,31 @@ d3.pairs([1, 2, 3, 4], (a, b) => b - a); // returns [1, 1, 1];
 
 If the specified iterable has fewer than two elements, returns the empty array.
 
-<a name="permute" href="#permute">#</a> d3.<b>permute</b>(<i>source</i>, <i>keys</i>) · [Source](https://github.com/d3/d3-array/blob/master/src/permute.js), [Examples](https://observablehq.com/@d3/d3-permute)
+<a name="permute" href="#permute">#</a> d3.<b>permute</b>(<i>source</i>[, <i>keys</i>]) · [Source](https://github.com/d3/d3-array/blob/master/src/permute.js), [Examples](https://observablehq.com/@d3/d3-permute)
 
-Returns a permutation of the specified *source* object (or array) using the specified iterable of *keys*. The returned array contains the corresponding property of the source object for each key in *keys*, in order. For example:
+Returns a generator of permutations or a single permutation of the specified *source* object (or array).
+
+If *keys* is omitted then a [generator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Generator) is returned which, when iterated, generates all permutations of the input. For example:
+
+```js
+const permutations = permute(["a", "b", "c"]);
+permutations.next().value; // returns ["a", "b", "c"]
+permutations.next().value; // returns ["a", "c", "b"]
+permutations.next().value; // returns ["c", "a", "b"]
+permutations.next().value; // returns ["c", "b", "a"]
+permutations.next().value; // returns ["b", "c", "a"]
+permutations.next().value; // returns ["b", "a", "c"]
+```
+
+Generators are iterable and can be used in [`for…of`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for...of):
+
+```js
+for (const permutation of permute(["a", "b", "c"])) {
+  // code looping over each permutation
+}
+```
+
+If *keys* is specified then a single permutation is returned. The returned array contains the corresponding property of the source object for each key in *keys*, in order. For example:
 
 ```js
 permute(["a", "b", "c"], [1, 2, 0]); // returns ["b", "c", "a"]

src/permute.js

@@ -1,3 +1,45 @@
-export default function(source, keys) {
-  return Array.from(keys, key => source[key]);
+export default function (source, keys) {
+  if (keys === undefined) {
+    return permute(source);
+  } else {
+    return Array.from(keys, (key) => source[key]);
+  }
+}
+
+// Based on https://github.com/google/guava/blob/f4b3f611c4e49ecaded58dcb49262f55e56a3322/guava/src/com/google/common/collect/Collections2.java#L622-L683
+// Apache-2.0 License, Copyright (C) 2008 The Guava Authors.
+export function* permute(source) {
+  if (source.length <= 1) {
+    yield source.slice();
+  } else {
+    source = source.slice();
+    const c = Array(source.length).fill(0);
+    const o = Array(source.length).fill(1);
+    let j = Infinity;
+    while (j > 0) {
+      yield source.slice();
+      j = source.length - 1;
+      let s = 0;
+      while (true) {
+        const q = c[j] + o[j];
+        if (q < 0) {
+          o[j] = -o[j];
+          j--;
+        } else if (q === j + 1) {
+          if (j === 0) {
+            break;
+          }
+          s++;
+          o[j] = -o[j];
+          j--;
+        } else {
+          const a = j - c[j] + s;
+          const b = j - q + s;
+          [source[a], source[b]] = [source[b], source[a]];
+          c[j] = q;
+          break;
+        }
+      }
+    }
+  }
 }

test/permute-test.js

@@ -1,6 +1,104 @@
 const tape = require("tape-await");
 const d3 = require("../");
 
+//#region Based on https://github.com/google/guava/blob/f4b3f611c4e49ecaded58dcb49262f55e56a3322/guava-tests/test/com/google/common/collect/Collections2Test.java
+
+tape("permute(…) permutes zero values", (test) => {
+  test.deepEqual(Array.from(d3.permute([])), [[]]);
+});
+
+tape("permute(…) permutes one value", (test) => {
+  test.deepEqual(Array.from(d3.permute([1])), [[1]]);
+});
+
+tape("permute(…) permutes two values", (test) => {
+  test.deepEqual(Array.from(d3.permute([1, 2])), [
+    [1, 2],
+    [2, 1],
+  ]);
+});
+
+tape("permute(…) permutes three values", (test) => {
+  test.deepEqual(Array.from(d3.permute([1, 2, 3])), [
+    [1, 2, 3],
+    [1, 3, 2],
+    [3, 1, 2],
+
+    [3, 2, 1],
+    [2, 3, 1],
+    [2, 1, 3],
+  ]);
+});
+
+tape("permute(…) permutes three values out of order", (test) => {
+  test.deepEqual(Array.from(d3.permute([3, 2, 1])), [
+    [3, 2, 1],
+    [3, 1, 2],
+    [1, 3, 2],
+
+    [1, 2, 3],
+    [2, 1, 3],
+    [2, 3, 1],
+  ]);
+});
+
+tape("permute(…) permutes three repeated values", (test) => {
+  test.deepEqual(Array.from(d3.permute([1, 1, 2])), [
+    [1, 1, 2],
+    [1, 2, 1],
+    [2, 1, 1],
+
+    [2, 1, 1],
+    [1, 2, 1],
+    [1, 1, 2],
+  ]);
+});
+
+tape("permute(…) permutes values", (test) => {
+  test.deepEqual(Array.from(d3.permute([1, 2, 3, 4])), [
+    [1, 2, 3, 4],
+    [1, 2, 4, 3],
+    [1, 4, 2, 3],
+    [4, 1, 2, 3],
+
+    [4, 1, 3, 2],
+    [1, 4, 3, 2],
+    [1, 3, 4, 2],
+    [1, 3, 2, 4],
+
+    [3, 1, 2, 4],
+    [3, 1, 4, 2],
+    [3, 4, 1, 2],
+    [4, 3, 1, 2],
+
+    [4, 3, 2, 1],
+    [3, 4, 2, 1],
+    [3, 2, 4, 1],
+    [3, 2, 1, 4],
+
+    [2, 3, 1, 4],
+    [2, 3, 4, 1],
+    [2, 4, 3, 1],
+    [4, 2, 3, 1],
+
+    [4, 2, 1, 3],
+    [2, 4, 1, 3],
+    [2, 1, 4, 3],
+    [2, 1, 3, 4],
+  ]);
+});
+
+tape("permute(…) permutes count of permutations", (test) => {
+  test.equal(count(d3.permute([])), 1);
+  test.equal(count(d3.permute([1])), 1);
+  test.equal(count(d3.permute([1, 2])), 2);
+  test.equal(count(d3.permute([1, 2, 3])), 6);
+  test.equal(count(d3.permute([1, 2, 3, 4, 5, 6, 7])), 5040);
+  test.equal(count(d3.permute([1, 2, 3, 4, 5, 6, 7, 8])), 40320);
+});
+
+//#endregion
+
 tape("permute(…) permutes according to the specified index", (test) => {
   test.deepEqual(d3.permute([3, 4, 5], [2, 1, 0]), [5, 4, 3]);
   test.deepEqual(d3.permute([3, 4, 5], [2, 0, 1]), [5, 3, 4]);
@@ -48,3 +146,12 @@ tape("permute(…) can take a typed array as the source", (test) => {
 tape("permute(…) can take an iterable as the keys", (test) => {
   test.deepEqual(d3.permute({foo: 1, bar: 2}, new Set(["bar", "foo"])), [2, 1]);
 });
+
+function count(values) {
+  let count = 0;
+  // eslint-disable-next-line no-unused-vars
+  for (const _value of values) {
+    count++;
+  }
+  return count;
+}