Make Combination iteration O(size) per element

Fixes #75. The common iterator inherited from _CBase calls .at() for
every index, which goes through combinadic() and costs O(size**3)
BigInt operations per element. Combination now overrides
[Symbol.iterator] with the lexicographic successor algorithm, yielding
the same sequence with O(size) number operations per element.
Iterating all C(200,3) combinations drops from ~58s to ~40ms.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: dankogai

combinatorics.d.ts

@@ -151,6 +151,13 @@ export declare class Permutation<T> extends _CBase<T, T> {
 export declare class Combination<T> extends _CBase<T, T> {
     comb: (anyint: any) => number[];
     constructor(seed: Iterable<T>, size?: number);
+    /**
+     * Overrides the common iterator, which is `O(size**3)` per element
+     * because it calls `.at()` for each index.  This one yields each
+     * combination from its lexicographic successor in `O(size)`,
+     * in the same order as the common iterator.
+     */
+    [Symbol.iterator](): Generator<T[], void, unknown>;
     /**
      * returns an iterator which is more efficient
      * than the default iterator that uses .nth

combinatorics.js

@@ -275,6 +275,31 @@ class Combination extends _CBase {
         this.comb = combinadic(this.seed.length, this.size);
         Object.freeze(this);
     }
+    /**
+     * Overrides the common iterator, which is `O(size**3)` per element
+     * because it calls `.at()` for each index.  This one yields each
+     * combination from its lexicographic successor in `O(size)`,
+     * in the same order as the common iterator.
+     */
+    [Symbol.iterator]() {
+        return function* (it) {
+            if (it.length === 0n)
+                return;
+            const [n, k] = [it.seed.length, it.size];
+            const indices = Array.from({ length: k }, (_, i) => i);
+            while (true) {
+                yield indices.map(i => it.seed[i]);
+                let i = k - 1;
+                while (0 <= i && indices[i] === i + n - k)
+                    i--;
+                if (i < 0)
+                    return;
+                indices[i]++;
+                for (let j = i + 1; j < k; j++)
+                    indices[j] = indices[j - 1] + 1;
+            }
+        }(this);
+    }
     /**
      * returns an iterator which is more efficient
      * than the default iterator that uses .nth

combinatorics.ts

@@ -282,6 +282,27 @@ export class Combination<T> extends _CBase<T, T> {
         this.comb = combinadic(this.seed.length, this.size);
         Object.freeze(this);
     }
+    /**
+     * Overrides the common iterator, which is `O(size**3)` per element
+     * because it calls `.at()` for each index.  This one yields each
+     * combination from its lexicographic successor in `O(size)`,
+     * in the same order as the common iterator.
+     */
+    [Symbol.iterator]() {
+        return function* (it: Combination<T>) {
+            if (it.length === 0n) return;
+            const [n, k] = [it.seed.length, it.size];
+            const indices = Array.from({ length: k }, (_, i) => i);
+            while (true) {
+                yield indices.map(i => it.seed[i]);
+                let i = k - 1;
+                while (0 <= i && indices[i] === i + n - k) i--;
+                if (i < 0) return;
+                indices[i]++;
+                for (let j = i + 1; j < k; j++) indices[j] = indices[j - 1] + 1;
+            }
+        }(this);
+    }
     /**
      * returns an iterator which is more efficient
      * than the default iterator that uses .nth

commonjs/combinatorics.js

@@ -277,6 +277,31 @@ class Combination extends _CBase {
         this.comb = combinadic(this.seed.length, this.size);
         Object.freeze(this);
     }
+    /**
+     * Overrides the common iterator, which is `O(size**3)` per element
+     * because it calls `.at()` for each index.  This one yields each
+     * combination from its lexicographic successor in `O(size)`,
+     * in the same order as the common iterator.
+     */
+    [Symbol.iterator]() {
+        return function* (it) {
+            if (it.length === 0n)
+                return;
+            const [n, k] = [it.seed.length, it.size];
+            const indices = Array.from({ length: k }, (_, i) => i);
+            while (true) {
+                yield indices.map(i => it.seed[i]);
+                let i = k - 1;
+                while (0 <= i && indices[i] === i + n - k)
+                    i--;
+                if (i < 0)
+                    return;
+                indices[i]++;
+                for (let j = i + 1; j < k; j++)
+                    indices[j] = indices[j - 1] + 1;
+            }
+        }(this);
+    }
     /**
      * returns an iterator which is more efficient
      * than the default iterator that uses .nth

test/03-combination.js

@@ -37,4 +37,14 @@ describe('class Combination', () => {
         [[1, 2], [5, 6]],
         [[3, 4], [5, 6]]
     ]));
+    // https://github.com/dankogai/js-combinatorics/issues/75
+    const abc = 'abcdefgh';
+    for (let len = 0; len <= abc.length + 1; len++) {
+        it(`[...new Combination('${abc}', ${len})] === .at(0)...at(.length-1)`, () => {
+            let c = new Combination(abc, len);
+            let byAt = [];
+            for (let i = 0n; i < c.length; i++) byAt.push(c.at(i));
+            $$([...c]).to.deep.equal(byAt);
+        });
+    }
 });

umd/combinatorics.js

@@ -281,6 +281,31 @@
             this.comb = combinadic(this.seed.length, this.size);
             Object.freeze(this);
         }
+        /**
+         * Overrides the common iterator, which is `O(size**3)` per element
+         * because it calls `.at()` for each index.  This one yields each
+         * combination from its lexicographic successor in `O(size)`,
+         * in the same order as the common iterator.
+         */
+        [Symbol.iterator]() {
+            return function* (it) {
+                if (it.length === 0n)
+                    return;
+                const [n, k] = [it.seed.length, it.size];
+                const indices = Array.from({ length: k }, (_, i) => i);
+                while (true) {
+                    yield indices.map(i => it.seed[i]);
+                    let i = k - 1;
+                    while (0 <= i && indices[i] === i + n - k)
+                        i--;
+                    if (i < 0)
+                        return;
+                    indices[i]++;
+                    for (let j = i + 1; j < k; j++)
+                        indices[j] = indices[j - 1] + 1;
+                }
+            }(this);
+        }
         /**
          * returns an iterator which is more efficient
          * than the default iterator that uses .nth