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

Author: make-github-pseudonymous-again

README.md

@@ -4,13 +4,18 @@
 Set n-multicombinations for JavaScript.
 See [docs](https://computational-combinatorics.github.io/n-multicombinations/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).
 
+```
+import {multicombinations} from '@combinatorics/n-multicombinations';
+multicombinations("ABC", 1); // A B C
+
+import {range} from '@iterable-iterator/range';
+multicombinations(range(3), 2); // 00 01 02 11 12 22
+```
+
 [![License](https://img.shields.io/github/license/computational-combinatorics/n-multicombinations.svg)](https://raw.githubusercontent.com/computational-combinatorics/n-multicombinations/main/LICENSE)
 [![Version](https://img.shields.io/npm/v/@combinatorics/n-multicombinations.svg)](https://www.npmjs.org/package/@combinatorics/n-multicombinations)
 [![Tests](https://img.shields.io/github/workflow/status/computational-combinatorics/n-multicombinations/ci:test?event=push&label=tests)](https://github.com/computational-combinatorics/n-multicombinations/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-multicombinations';
+	testlink.href =
+		'https://app.codecov.io/gh/computational-combinatorics/n-multicombinations';
 	testlink.target = '_BLANK';
 
 	const searchBox = document.querySelector('.search-box');

package.json

@@ -63,12 +63,17 @@
     "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/repeat": "^0.0.1"
+  },
   "devDependencies": {
     "@babel/core": "7.14.0",
     "@babel/preset-env": "7.14.0",
     "@babel/register": "7.13.16",
     "@commitlint/cli": "12.1.1",
+    "@iterable-iterator/range": "^1.0.0",
     "@js-library/commitlint-config": "0.0.4",
     "ava": "3.15.0",
     "babel-plugin-transform-remove-console": "6.9.4",

src/index.js

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

src/multicombinations.js

@@ -0,0 +1,57 @@
+import {list} from '@iterable-iterator/list';
+import {pick} from '@iterable-iterator/map';
+import {nrepeat} from '@iterable-iterator/repeat';
+
+/**
+ * Yields all combinations, with repetitions, of each possible choice of
+ * <code>r</code> elements of the input iterable.
+ *
+ * @example
+ * // A B C
+ * multicombinations('ABC', 1)
+ *
+ * @example
+ * // 00 01 02 11 12 22
+ * multicombinations(range(3), 2)
+ *
+ * @param {Iterable} iterable - The input iterable.
+ * @param {number} r - The size of the combinations to generate.
+ * @returns {IterableIterator}
+ */
+export default function* multicombinations(iterable, r) {
+	const pool = list(iterable);
+	const length = pool.length;
+
+	if (length === 0 && r > 0) {
+		return;
+	}
+
+	const indices = list(nrepeat(0, r));
+
+	yield list(pick(pool, indices));
+
+	while (true) {
+		let i = r - 1;
+
+		// eslint-disable-next-line no-constant-condition
+		while (true) {
+			if (i < 0) {
+				return;
+			}
+
+			if (indices[i] !== length - 1) {
+				const pivot = ++indices[i];
+
+				for (++i; i < r; ++i) {
+					indices[i] = pivot;
+				}
+
+				break;
+			}
+
+			--i;
+		}
+
+		yield list(pick(pool, indices));
+	}
+}

test/src/api.js

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