🚧 progress: Import existing sources, tests, and code samples.

Author: make-github-pseudonymous-again

README.md

@@ -4,13 +4,18 @@
 Set n-permutations for JavaScript.
 See [docs](https://computational-combinatorics.github.io/n-permutations/index.html).
 
-> :building_construction: Caveat emptor! This is work in progress. Code may be
-> working. Documentation may be present. Coherence may be. Maybe.
-
 > :warning: Depending on your environment, the code may require
 > `regeneratorRuntime` to be defined, for instance by importing
 > [regenerator-runtime/runtime](https://www.npmjs.com/package/regenerator-runtime).
 
+```js
+import {permutations} from '@combinatorics/n-permutations';
+permutations("ABCD", 2); // AB AC AD BA BC BD CA CB CD DA DB DC
+
+import {range} from '@iterable-iterator/range';
+permutations(range(3), 3); // 012 021 102 120 201 210
+```
+
 [![License](https://img.shields.io/github/license/computational-combinatorics/n-permutations.svg)](https://raw.githubusercontent.com/computational-combinatorics/n-permutations/main/LICENSE)
 [![Version](https://img.shields.io/npm/v/@combinatorics/n-permutations.svg)](https://www.npmjs.org/package/@combinatorics/n-permutations)
 [![Tests](https://img.shields.io/github/workflow/status/computational-combinatorics/n-permutations/ci:test?event=push&label=tests)](https://github.com/computational-combinatorics/n-permutations/actions/workflows/ci:test.yml?query=branch:main)

doc/scripts/header.js

@@ -17,7 +17,8 @@ domReady(() => {
 	header.insertBefore(projectname, header.firstChild);
 
 	const testlink = document.querySelector('header > a[data-ice="testLink"]');
-	testlink.href = 'https://app.codecov.io/gh/computational-combinatorics/n-permutations';
+	testlink.href =
+		'https://app.codecov.io/gh/computational-combinatorics/n-permutations';
 	testlink.target = '_BLANK';
 
 	const searchBox = document.querySelector('.search-box');

package.json

@@ -58,7 +58,12 @@
     "release": "np --message ':hatching_chick: release: Bumping to v%s.'",
     "test": "ava"
   },
-  "dependencies": {},
+  "dependencies": {
+    "@iterable-iterator/list": "^0.0.2",
+    "@iterable-iterator/map": "^0.1.0",
+    "@iterable-iterator/range": "^1.0.0",
+    "@iterable-iterator/slice": "^0.0.1"
+  },
   "devDependencies": {
     "@babel/core": "7.14.0",
     "@babel/preset-env": "7.14.0",

src/index.js

@@ -1,2 +1 @@
-const answer = 42;
-export default answer;
+export {default as permutations} from './permutations.js';

src/permutations.js

@@ -0,0 +1,68 @@
+import assert from 'assert';
+import {_take} from '@iterable-iterator/slice';
+
+import {list} from '@iterable-iterator/list';
+import {pick} from '@iterable-iterator/map';
+import {range} from '@iterable-iterator/range';
+
+/**
+ * Yields all permutations of each possible choice of <code>r</code> elements
+ * of the input iterable.
+ *
+ * @example
+ * // AB AC AD BA BC BD CA CB CD DA DB DC
+ * permutations('ABCD', 2) ;
+ *
+ * @example
+ * // 012 021 102 120 201 210
+ * permutations(range(3), 3) ;
+ *
+ * @param {Iterable} iterable - The input iterable.
+ * @param {number} r - The size of the permutations to generate.
+ * @returns {IterableIterator}
+ */
+export default function* permutations(iterable, r) {
+	assert(Number.isInteger(r) && r >= 0);
+	const pool = list(iterable);
+
+	const length = pool.length;
+
+	if (r > length) {
+		return;
+	}
+
+	const indices = list(range(0, length, 1));
+	const cycles = list(range(length, length - r, -1));
+
+	yield list(pick(pool, _take(indices, r)));
+
+	if (r === 0 || length === 0) {
+		return;
+	}
+
+	while (true) {
+		let i = r;
+
+		while (i--) {
+			--cycles[i];
+
+			if (cycles[i] === 0) {
+				// Could be costly
+				indices.push(indices.splice(i, 1)[0]);
+
+				cycles[i] = length - i;
+			} else {
+				const j = cycles[i];
+
+				[indices[i], indices[length - j]] = [indices[length - j], indices[i]];
+
+				yield list(pick(pool, _take(indices, r)));
+				break;
+			}
+		}
+
+		if (i === -1) {
+			return;
+		}
+	}
+}

test/src/api.js

@@ -0,0 +1,43 @@
+import test from 'ava';
+
+import {list} from '@iterable-iterator/list';
+import {range} from '@iterable-iterator/range';
+import {permutations} from '../../src/index.js';
+
+const repr = (x) => (Array.isArray(x) ? JSON.stringify(x) : x);
+
+const macro = (t, iterable, r, expected) => {
+	t.deepEqual(list(permutations(iterable, r)), expected);
+};
+
+macro.title = (title, iterable, r, expected) =>
+	title ?? `permutations(${repr(iterable)}, ${r}) is ${repr(expected)}`;
+
+test(macro, [], 1, []);
+test(macro, [], 0, [[]]);
+test(macro, [1, 2, 3], 0, [[]]);
+test(macro, [1, 2, 3], 4, []);
+
+test(macro, 'ABCD', 2, [
+	['A', 'B'],
+	['A', 'C'],
+	['A', 'D'],
+	['B', 'A'],
+	['B', 'C'],
+	['B', 'D'],
+	['C', 'A'],
+	['C', 'B'],
+	['C', 'D'],
+	['D', 'A'],
+	['D', 'B'],
+	['D', 'C'],
+]);
+
+test(macro, range(0, 3, 1), 3, [
+	[0, 1, 2],
+	[0, 2, 1],
+	[1, 0, 2],
+	[1, 2, 0],
+	[2, 0, 1],
+	[2, 1, 0],
+]);