Iterators

The visit method provides a single high-level mechanism to traverse a quadrille in row-major order (rows 0..height-1, within each row columns 0..width-1). The callback is invoked with { row, col, value }, may read or mutate cells, and iteration stops early if the callback returns false. Traversal can apply to all cells, or be restricted by a collection of allowed values or a predicate function, encouraging a declarative programming approach.

Manual Iteration Using Nested Loops

The imperative programming style for traversing a grid—often seen with 2D arrays or matrices—uses nested for loops:

function callback(row, col, value) {
  /* callback body */
}

for (let row = 0; row < quadrille.height; row++) {
  for (let col = 0; col < quadrille.width; col++) {
    const value = quadrille.read(row, col);
    callback(row, col, value);
  }
}

While straightforward and likely familiar, this pattern is prone to off-by-one and indexing errors, and requires additional logic for filtering. It remains a useful fallback, but the iterator methods are typically cleaner and safer.

Method Overview

• visit(callback): iterates all cells in row-major order. Return false to stop early.
• visit(callback, collection): iterates only cells whose value is in the given Array or Set.
• visit(callback, predicate): iterates only cells where the predicate function returns true.