Merge pull request #2 from N8Brooks/alternate_parameters

Alternate parameters

Author: N8Brooks

.github/workflows/ci.yml

@@ -36,7 +36,8 @@ jobs:
         run: deno lint
 
       - name: Test
-        run: deno test --doc --unstable
+        # run: deno test --doc
+        run: deno test
 
       - name: Benchmark
         run: deno run _benchmark.ts

README.md

@@ -20,7 +20,7 @@ inspired by the combinatorial iterators provided by the
 
 ## Usage
 
-### function combinations(r: number, iterable: Iterable<T>): Generator<T[]>
+### combinations
 
 Yields `r` length `Arrays` from the input `iterable`. Order of selection does
 not matter and elements are chosen without replacement.
@@ -29,7 +29,7 @@ not matter and elements are chosen without replacement.
 import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
 import { combinations } from "https://deno.land/x/combinatorics/mod.ts";
 
-const sequences = [...combinations(2, [1, 2, 3, 4])];
+const sequences = [...combinations([1, 2, 3, 4], 2)];
 
 assertEquals(sequences, [
   [1, 2],
@@ -41,7 +41,7 @@ assertEquals(sequences, [
 ]);
 ```
 
-### function permutations(r: number | undefined, iterable: Iterable<T>): Generator<T[]>
+### permutations
 
 Yields `r` length `Arrays` from the input `iterable`. Order of selection is
 important and elements are chosen without replacement. If `r` is undefined, then
@@ -52,7 +52,7 @@ the length of the `iterable` is used.
 import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
 import { permutations } from "https://deno.land/x/combinatorics/mod.ts";
 
-const sequences = [...permutations(2, [1, 2, 3, 4])];
+const sequences = [...permutations([1, 2, 3, 4], 2)];
 
 assertEquals(sequences, [
   [1, 2], [1, 3], [1, 4],
@@ -62,7 +62,7 @@ assertEquals(sequences, [
 ]);
 ```
 
-### function combinationsWithReplacement(r: number, iterable: Iterable<T>): Generator<T[]>
+### combinationsWithReplacement
 
 Yields `r` length `Arrays` from the input `iterable`. Order of selection is not
 important and elements are chosen with replacement.
@@ -71,7 +71,7 @@ important and elements are chosen with replacement.
 import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
 import { combinationsWithReplacement } from "https://deno.land/x/combinatorics/mod.ts";
 
-const sequences = [...combinationsWithReplacement(2, [1, 2, 3, 4])];
+const sequences = [...combinationsWithReplacement([1, 2, 3, 4], 2)];
 
 assertEquals(sequences, [
   [1, 1],
@@ -87,21 +87,17 @@ assertEquals(sequences, [
 ]);
 ```
 
-### function product(r: number, ...iterables: Iterable<T>[]): Generator<T[]>
+### permutationsWithReplacement
 
-Yields `r * iterables.length` length `Arrays` from the input `iterables`
-repeated `r` times. Order of selection is important and elements are chosen with
-replacement.
-
-When `iterables.length === 1` the output is equivalent to the permutations with
-replacement of `iterables[0]` with the given `r`.
+Yields `r` length `Arrays` from the input `iterable`. Order of selection is
+important and elements are chosen with replacement.
 
 <!-- deno-fmt-ignore -->
 ```ts
 import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
-import { product } from "https://deno.land/x/combinatorics/mod.ts";
+import { permutationsWithReplacement } from "https://deno.land/x/combinatorics/mod.ts";
 
-const sequences = [...product(2, [1, 2, 3, 4])];
+const sequences = [...permutationsWithReplacement(2, [1, 2, 3, 4])];
 
 assertEquals(sequences, [
   [1, 1], [1, 2], [1, 3], [1, 4],
@@ -111,17 +107,17 @@ assertEquals(sequences, [
 ]);
 ```
 
-When `iterables.length > 1` the output is equivalent to the cartesian product of
-the `iterables` repeated `r` times. This can also be explained as running nested
-`for...of` loops using one of the inputs to provide the element at each index
-for the yielded `Array`.
+### cartesianProduct
+
+Roughly equivalent to running nested `for...of` loops using one of the inputs to
+provide the element at each index for the yielded `Array`.
 
 <!-- deno-fmt-ignore -->
 ```ts
 import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
-import { product } from "https://deno.land/x/combinatorics/mod.ts";
+import { cartesianProduct } from "https://deno.land/x/combinatorics/mod.ts";
 
-const sequences = [...product(1, [1, 2, 3], [4, 5, 6], [7, 8, 9])];
+const sequences = [...cartesianProduct([1, 2, 3], [4, 5, 6], [7, 8, 9])];
 
 assertEquals(sequences, [
   [1, 4, 7], [1, 4, 8], [1, 4, 9],
@@ -136,7 +132,7 @@ assertEquals(sequences, [
 ]);
 ```
 
-### function powerSet(iterable: Iterable<T>): Generator<T[]>
+### powerSet
 
 The set of all subsets of the given `iterable`. Equivalent to running
 `combinations` with `0 <= r <= iterable.length` and flattening the results. The

_benchmark.ts

@@ -6,15 +6,16 @@ import {
 import { combinations } from "./combinations.ts";
 import { combinationsWithReplacement } from "./combinations_with_replacement.ts";
 import { permutations } from "./permutations.ts";
-import { product } from "./product.ts";
+import { permutationsWithReplacement } from "./permutations_with_replacement.ts";
+import { cartesianProduct } from "./cartesian_product.ts";
 import { powerSet } from "./power_set.ts";
 
 bench({
   name: "combinations",
   runs: 3,
   func(benchmarkTimer: BenchmarkTimer): void {
     benchmarkTimer.start();
-    for (const _ of combinations(12, Array(29)));
+    for (const _ of combinations(Array(29), 12));
     benchmarkTimer.stop();
   },
 });
@@ -24,7 +25,7 @@ bench({
   runs: 3,
   func(benchmarkTimer: BenchmarkTimer): void {
     benchmarkTimer.start();
-    for (const _ of combinationsWithReplacement(12, Array(18)));
+    for (const _ of combinationsWithReplacement(Array(18), 12));
     benchmarkTimer.stop();
   },
 });
@@ -34,17 +35,27 @@ bench({
   runs: 3,
   func(benchmarkTimer: BenchmarkTimer): void {
     benchmarkTimer.start();
-    for (const _ of permutations(11, Array(11)));
+    for (const _ of permutations(Array(11), 11));
     benchmarkTimer.stop();
   },
 });
 
 bench({
-  name: "product",
+  name: "permutationsWithReplacement",
   runs: 3,
   func(benchmarkTimer: BenchmarkTimer): void {
     benchmarkTimer.start();
-    for (const _ of product(7, Array(13)));
+    for (const _ of permutationsWithReplacement(Array(13), 7));
+    benchmarkTimer.stop();
+  },
+});
+
+bench({
+  name: "cartesianProduct",
+  runs: 3,
+  func(benchmarkTimer: BenchmarkTimer): void {
+    benchmarkTimer.start();
+    for (const _ of cartesianProduct(...Array(7).fill(Array(13))));
     benchmarkTimer.stop();
   },
 });

cartesian_product.ts

@@ -0,0 +1,63 @@
+// This module is browser compatible.
+
+/**
+ * Roughly equivalent to running nested `for...of` loops using one of the inputs to
+ * provide the element at each index for the yielded `Array`.
+ *
+ * ```ts
+ * import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
+ * import { cartesianProduct } from "https://deno.land/x/combinatorics/mod.ts";
+ *
+ * const sequences = [...cartesianProduct([1, 2, 3], [4, 5, 6], [7, 8, 9])];
+ *
+ * assertEquals(sequences, [
+ *   [1, 4, 7], [1, 4, 8], [1, 4, 9],
+ *   [1, 5, 7], [1, 5, 8], [1, 5, 9],
+ *   [1, 6, 7], [1, 6, 8], [1, 6, 9],
+ *   [2, 4, 7], [2, 4, 8], [2, 4, 9],
+ *   [2, 5, 7], [2, 5, 8], [2, 5, 9],
+ *   [2, 6, 7], [2, 6, 8], [2, 6, 9],
+ *   [3, 4, 7], [3, 4, 8], [3, 4, 9],
+ *   [3, 5, 7], [3, 5, 8], [3, 5, 9],
+ *   [3, 6, 7], [3, 6, 8], [3, 6, 9],
+ * ]);
+ * ```
+ */
+export function* cartesianProduct<T>(
+  ...iterables: Iterable<T>[]
+): Generator<T[]> {
+  const pools = iterables.map((iterable) => [...iterable]);
+  const n = pools.length;
+  if (n === 0) {
+    yield [];
+    return;
+  }
+  if (pools.some((pool) => pool.length === 0)) {
+    return;
+  }
+  const indices = new Uint32Array(n);
+  yield pools.map((pool) => pool[0]);
+  while (true) {
+    let i: number;
+    loop: {
+      for (i = n - 1; i >= 0; i--) {
+        if (indices[i] === pools[i].length - 1) {
+          continue;
+        }
+        const result: T[] = Array(n);
+        for (let j = 0; j < i; j++) {
+          result[j] = pools[j][indices[j]];
+        }
+        const index = indices[i] += 1;
+        result[i] = pools[i][index];
+        for (let j = i + 1; j < n; j++) {
+          indices[j] = 0;
+          result[j] = pools[j][0];
+        }
+        yield result;
+        break loop;
+      }
+      return;
+    }
+  }
+}

cartesian_product_test.ts

@@ -0,0 +1,128 @@
+import {
+  assertEquals,
+  assertStrictEquals,
+} from "https://deno.land/std@0.113.0/testing/asserts.ts";
+import { cartesianProduct } from "./cartesian_product.ts";
+import { range } from "./_util.ts";
+
+Deno.test("no iterables", () => {
+  const actual = [...cartesianProduct()];
+  assertEquals(actual, [[]]);
+});
+
+Deno.test("one iterable", () => {
+  const actual = [...cartesianProduct("abc")];
+  const expected = [["a"], ["b"], ["c"]];
+  assertEquals(actual, expected);
+});
+
+Deno.test("iterables of varying length", () => {
+  const actual = [...cartesianProduct([1], [2, 3, 4], [5, 6])];
+  const expected = [
+    [1, 2, 5],
+    [1, 2, 6],
+    [1, 3, 5],
+    [1, 3, 6],
+    [1, 4, 5],
+    [1, 4, 6],
+  ];
+  assertEquals(actual, expected);
+});
+
+Deno.test("iterables with empty", () => {
+  const actual = [...cartesianProduct([1, 2, 3], [], [4, 5, 6])];
+  assertEquals(actual, []);
+});
+
+Deno.test("r = 65_537", () => {
+  const actual = [...cartesianProduct(range(65_537))];
+  const expected = Array(65_537).fill(undefined).map((_, i) => [i]);
+  assertEquals(actual, expected);
+});
+
+test(cartesianProductLength);
+
+test(cartesianProductContent);
+
+/** Calls a function with varying `r`s and `iterables`. */
+function test(
+  func: typeof cartesianProductLength | typeof cartesianProductContent,
+): void {
+  for (let n0 = 0; n0 < 8; n0++) {
+    func(n0);
+  }
+
+  for (let n0 = 0; n0 < 8; n0++) {
+    for (let n1 = 0; n1 < 8; n1++) {
+      func(n0, n1);
+    }
+  }
+
+  for (let n0 = 0; n0 < 4; n0++) {
+    for (let n1 = 0; n1 < 4; n1++) {
+      for (let n2 = 0; n2 < 4; n2++) {
+        func(n0, n1, n2);
+      }
+    }
+  }
+
+  for (let n0 = 0; n0 < 4; n0++) {
+    for (let n1 = 0; n1 < 4; n1++) {
+      for (let n2 = 0; n2 < 4; n2++) {
+        for (let n3 = 0; n3 < 4; n3++) {
+          func(n0, n1, n2, n3);
+        }
+      }
+    }
+  }
+}
+
+/** Tests `product` for length against `prod`. */
+function cartesianProductLength(...ns: number[]) {
+  const iterables = getIterables(...ns);
+  Deno.test(`prod(${ns.join(", ")})`, () => {
+    const actual = [...cartesianProduct(...iterables)];
+    const expectedLength = prod(...ns);
+    assertStrictEquals(actual.length, expectedLength);
+  });
+}
+
+/** Tests `product` for content against `cartesianProduct1`. */
+function cartesianProductContent(...ns: number[]) {
+  const iterables = getIterables(...ns);
+  const restArgs = JSON.stringify(iterables).slice(1, -1);
+  Deno.test(`cartesianProduct1(${restArgs})`, () => {
+    const actual = [...cartesianProduct(...iterables)];
+    const expected1 = [...cartesianProduct1(...iterables)];
+    assertEquals(actual, expected1);
+  });
+}
+
+/** Creates arrays of the given lengths containing unique numbers. */
+function getIterables(...ns: number[]): number[][] {
+  let i = 0;
+  return ns.map((n) => Array.from({ length: n }, () => i++));
+}
+
+/** Calculate the product of all the `ns` repeated `r` times. */
+function prod(...ns: number[]): number {
+  let product = 1;
+  for (const n of ns) {
+    product *= n;
+  }
+  return product;
+}
+
+/** Equivalent to `product` for testing. */
+function* cartesianProduct1<T>(
+  ...iterables: Iterable<T>[]
+): Generator<T[]> {
+  const pools = iterables.map((iterable) => [...iterable]);
+  let result: T[][] = [[]];
+  for (const pool of pools) {
+    result = result.map((x) => pool.map((y) => [...x, y])).flat();
+  }
+  for (const prod of result) {
+    yield prod;
+  }
+}

combinations.ts

@@ -8,7 +8,7 @@
  * import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
  * import { combinations } from "https://deno.land/x/combinatorics/mod.ts";
  *
- * const sequences = [...combinations(2, [1, 2, 3, 4])];
+ * const sequences = [...combinations([1, 2, 3, 4], 2)];
  *
  * assertEquals(sequences, [
  *   [1, 2],
@@ -21,8 +21,8 @@
  * ```
  */
 export function* combinations<T>(
-  r: number,
   iterable: Iterable<T>,
+  r: number,
 ): Generator<T[]> {
   if (r < 0 || !Number.isInteger(r)) {
     throw RangeError("r must be a non-negative integer");