Added ability to iterate and some related tests

Author: FiddlyDigital

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speakingsoftware/fastmap",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "A 2d Array optimized for speed and memory usage.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",

src/index.ts

@@ -145,4 +145,48 @@ export class FastMap<T> {
             throw new Error("Specified dimensions are too large");
         }
     }
+
+    /**
+     * Iterate over entries in row-major order.
+     * Each entry is a tuple: [[x, y], value]
+     * @example [for (const [[x, y], value] of map) { ... }]
+     */
+    public *entries(): IterableIterator<[[number, number], T | undefined]> {
+        for (let y = 0; y < this.height; y++) {
+            for (let x = 0; x < this.width; x++) {
+                yield [[x, y], this.map[this.convert2DTo1D(x, y)]];
+            }
+        }
+    }
+
+    /**
+     * Iterate over keys as [x, y] tuples in row-major order.
+     * @example [for (const [x, y] of map.keys()) { ... }]
+     */
+    public *keys(): IterableIterator<[number, number]> {
+        for (let y = 0; y < this.height; y++) {
+            for (let x = 0; x < this.width; x++) {
+                yield [x, y];
+            }
+        }
+    }
+
+    /**
+     * Iterate over values in row-major order.
+     * @example [for (const value of map.values()) { ... }]
+     */
+    public *values(): IterableIterator<T | undefined> {
+        for (let y = 0; y < this.height; y++) {
+            for (let x = 0; x < this.width; x++) {
+                yield this.map[this.convert2DTo1D(x, y)];
+            }
+        }
+    }
+
+    /**
+     * Default iterator - same as `entries()` so constructs like `for (const [key, value] of map)` work.
+     */
+    public [Symbol.iterator](): IterableIterator<[[number, number], T | undefined]> {
+        return this.entries();
+    }
 }

tests/iteration.test.ts

@@ -0,0 +1,78 @@
+import { FastMap } from '../src/index';
+
+describe('FastMap iteration', () => {
+    it('entries() yields [[x,y], value] in row-major order', () => {
+        const width = 3;
+        const height = 2;
+        const map = new FastMap<number>(width, height);
+
+        // set a few values, leave others undefined
+        map.Set(0, 0, 1);
+        map.Set(2, 0, 2);
+        map.Set(1, 1, 3);
+
+        const entries = Array.from(map.entries());
+        expect(entries.length).toBe(width * height);
+
+        // each entry should match map.Get(x,y)
+        for (const [[x, y], value] of entries) {
+            expect(map.Get(x, y)).toBe(value);
+        }
+
+        // check first and last coordinates
+        expect(entries[0][0]).toEqual([0, 0]);
+        expect(entries[0][1]).toBe(1);
+        expect(entries[entries.length - 1][0]).toEqual([2, 1]);
+    });
+
+    it('keys() yields coordinates in row-major order', () => {
+        const width = 4;
+        const height = 3;
+        const map = new FastMap<number>(width, height);
+
+        const keys = Array.from(map.keys());
+        expect(keys.length).toBe(width * height);
+
+        let idx = 0;
+        for (let y = 0; y < height; y++) {
+            for (let x = 0; x < width; x++) {
+                expect(keys[idx]).toEqual([x, y]);
+                idx++;
+            }
+        }
+    });
+
+    it('values() yields values in row-major order', () => {
+        const width = 5;
+        const height = 2;
+        const map = new FastMap<number>(width, height);
+
+        // initialize map with predictable values: value = y * width + x
+        for (let y = 0; y < height; y++) {
+            for (let x = 0; x < width; x++) {
+                map.Set(x, y, y * width + x);
+            }
+        }
+
+        const values = Array.from(map.values());
+        expect(values.length).toBe(width * height);
+
+        for (let i = 0; i < values.length; i++) {
+            expect(values[i]).toBe(i);
+        }
+    });
+
+    it('default iterator yields same as entries()', () => {
+        const width = 3;
+        const height = 3;
+        const map = new FastMap<string>(width, height);
+
+        map.Set(0, 0, 'a');
+        map.Set(2, 2, 'z');
+
+        // Avoid using `for..of` (requires downlevelIteration for es5 target).
+        const fromDefault = Array.from((map as any)[Symbol.iterator]() as Iterable<[[number, number], string | undefined]>);
+
+        expect(fromDefault).toEqual(Array.from(map.entries()));
+    });
+});