Iterator Pattern
Every for loop over a collection uses this pattern, which is why it's easy to dismiss. The interesting part isn't using iterators; it's knowing when to write one, what contract it must honour, and what happens when the collection changes underneath it. Interviewers use Iterator to check whether you understand encapsulation (callers shouldn't know your collection is a circular array), laziness (a generator that never builds the full list), and concurrent modification (why ArrayList throws when you remove inside a for-each).
The behavioral patterns overview doesn't cover Iterator. This page does, in depth: a custom collection with a fail-fast iterator in three languages, generators and yield for lazy and recursive traversal, the Java Iterator and Iterable contracts and their Python and TypeScript equivalents, and the three behaviours an iterator can have when its collection is modified.
Intent
Give a way to visit the elements of a collection one at a time without exposing how the collection stores them.
Three properties follow from that:
- Encapsulation. The collection can be an array, a linked list, a tree, a database cursor or a remote paginated API. Callers see only "is there another?" and "give me the next one".
- Traversal state lives in the iterator, not the collection. Two loops over the same collection at the same time each have their own position.
- Uniform access. Any code written against the iteration interface (a
forloop,map,filter,sum, spread syntax) works with any collection that provides an iterator.
The problem
An analytics dashboard keeps the last N events in a fixed-size ring buffer. New events overwrite the oldest. The first version exposed the internals so callers could loop.
class RingBuffer {
final String[] slots; // exposed so callers can loop
int head; // index of the oldest element
int size;
RingBuffer(int capacity) { slots = new String[capacity]; }
void add(String item) {
slots[(head + size) % slots.length] = item;
if (size < slots.length) size++; else head = (head + 1) % slots.length;
}
}
class Dashboard {
String render(RingBuffer buf) {
StringBuilder sb = new StringBuilder();
for (int i = 0; i < buf.size; i++) {
sb.append(buf.slots[(buf.head + i) % buf.slots.length]).append('\n');
}
return sb.toString();
}
}
class CsvExporter {
String export(RingBuffer buf) {
StringBuilder sb = new StringBuilder();
for (int i = 0; i < buf.size; i++) {
sb.append(buf.slots[buf.head + i]).append(','); // forgot the modulo: breaks after wrap-around
}
return sb.toString();
}
}
What's wrong:
- Every caller re-implements the traversal. The modular arithmetic is copied into each consumer, and one copy (
CsvExporter) already has a bug that only appears once the buffer wraps around. - The representation is frozen. If you later switch to a linked structure or a primitive array, every caller breaks. The fields are now a public API.
- Callers can corrupt the buffer. With
headandsizepublic, any caller can write to them. - It doesn't fit the language. You can't use a for-each loop, streams,
sum, or any library function that accepts an iterable.
The fix is for the buffer to hand out an object that knows how to walk it.
Structure
classDiagram
class Iterable~T~ {
<<interface>>
+iterator() Iterator~T~
}
class Iterator~T~ {
<<interface>>
+hasNext() boolean
+next() T
}
class RingBuffer~T~ {
-slots: array
-head: int
-size: int
-modCount: int
+add(item) void
+iterator() Iterator~T~
}
class RingIterator {
-offset: int
-expectedModCount: int
+hasNext() boolean
+next() T
}
Iterable <|.. RingBuffer
Iterator <|.. RingIterator
RingBuffer ..> RingIterator : creates
RingIterator --> RingBuffer : reads
class Client
Client --> Iterable : for-each
The collection implements Iterable and acts as a factory for iterators. Each iterator holds its own cursor (offset) and a reference back to the collection. The client depends only on the two interfaces.
Participants
| Participant | Java | Python | TypeScript | Responsibility |
|---|---|---|---|---|
| Iterator | java.util.Iterator<T> | object with __next__ (and __iter__ returning itself) | object with next() returning { value, done } | Holds the traversal position and yields elements one at a time. |
| Concrete iterator | inner class RingIterator | a generator | a generator | Knows the collection's layout and walks it. |
| Aggregate | java.lang.Iterable<T> | object with __iter__ | object with [Symbol.iterator]() | Creates fresh iterators on demand. |
| Concrete aggregate | RingBuffer<T> | RingBuffer[T] | RingBuffer<T> | Stores the data and hides its representation. |
| Client | for-each loop, streams | for, list(), sum() | for...of, spread, Array.from | Consumes elements through the interface only. |
The key distinction is between iterable and iterator. An iterable can be traversed many times: each call to iterator() returns a new, independent cursor. An iterator is a single, one-shot traversal. Mixing them up is one of the most common iterator bugs, and it comes up again with Python generators below.
Implementation
The buffer below hides its layout, supports any number of simultaneous traversals, and detects modification during iteration (fail-fast). The Python and TypeScript versions use generators for the iterator, which is how most iterators are written in those languages.
import java.util.*;
public class RingBufferDemo {
public static void main(String[] args) {
RingBuffer<String> recent = new RingBuffer<>(3);
for (String e : List.of("login", "view", "cart", "pay")) recent.add(e);
List<String> seen = new ArrayList<>();
for (String e : recent) seen.add(e); // for-each calls iterator()
assert seen.equals(List.of("view", "cart", "pay")) : seen;
// Two independent traversals at once.
Iterator<String> a = recent.iterator();
Iterator<String> b = recent.iterator();
a.next();
assert a.next().equals("cart") && b.next().equals("view");
// Fail-fast: a change during iteration is detected on the next call.
Iterator<String> it = recent.iterator();
it.next();
recent.add("logout");
try { it.next(); assert false; } catch (ConcurrentModificationException expected) { }
Iterator<String> empty = new RingBuffer<String>(2).iterator();
assert !empty.hasNext();
try { empty.next(); assert false; } catch (NoSuchElementException expected) { }
System.out.println("ring buffer: all assertions passed");
}
}
final class RingBuffer<T> implements Iterable<T> {
private final Object[] slots;
private int head; // index of the oldest element
private int size;
private int modCount; // bumped on every structural change
RingBuffer(int capacity) {
if (capacity <= 0) throw new IllegalArgumentException("capacity must be positive");
slots = new Object[capacity];
}
void add(T item) {
slots[(head + size) % slots.length] = item;
if (size < slots.length) size++; else head = (head + 1) % slots.length;
modCount++;
}
int size() { return size; }
@Override
public Iterator<T> iterator() { return new RingIterator(); }
private final class RingIterator implements Iterator<T> {
private int offset = 0;
private final int expectedModCount = modCount;
@Override public boolean hasNext() { return offset < size; }
@Override
@SuppressWarnings("unchecked")
public T next() {
if (modCount != expectedModCount) throw new ConcurrentModificationException();
if (!hasNext()) throw new NoSuchElementException();
return (T) slots[(head + offset++) % slots.length];
}
}
}
from collections.abc import Iterator
from typing import cast
class RingBuffer[T]:
def __init__(self, capacity: int) -> None:
if capacity <= 0:
raise ValueError("capacity must be positive")
self._slots: list[object] = [None] * capacity
self._head = 0 # index of the oldest element
self._size = 0
self._mod_count = 0 # bumped on every structural change
def add(self, item: T) -> None:
cap = len(self._slots)
self._slots[(self._head + self._size) % cap] = item
if self._size < cap:
self._size += 1
else:
self._head = (self._head + 1) % cap
self._mod_count += 1
def __len__(self) -> int:
return self._size
def __iter__(self) -> Iterator[T]:
# Capture the count now: a generator's body doesn't run until the first next().
return self._walk(self._mod_count)
def _walk(self, expected: int) -> Iterator[T]:
cap = len(self._slots)
for offset in range(self._size):
if self._mod_count != expected:
raise RuntimeError("RingBuffer changed during iteration")
yield cast(T, self._slots[(self._head + offset) % cap])
if __name__ == "__main__":
recent: RingBuffer[str] = RingBuffer(3)
for event in ["login", "view", "cart", "pay"]:
recent.add(event)
assert list(recent) == ["view", "cart", "pay"]
a, b = iter(recent), iter(recent)
next(a)
assert next(a) == "cart" and next(b) == "view"
it = iter(recent)
next(it)
recent.add("logout")
try:
next(it)
raise AssertionError("expected RuntimeError")
except RuntimeError as e:
assert "changed during iteration" in str(e)
try:
next(iter(RingBuffer[str](2)))
raise AssertionError("expected StopIteration")
except StopIteration:
pass
print("ring buffer: all assertions passed")
class RingBuffer<T> implements Iterable<T> {
private readonly slots: (T | undefined)[];
private head = 0; // index of the oldest element
private count = 0;
private modCount = 0; // bumped on every structural change
constructor(capacity: number) {
if (!Number.isInteger(capacity) || capacity <= 0) throw new RangeError("capacity must be a positive integer");
this.slots = new Array<T | undefined>(capacity).fill(undefined);
}
add(item: T): void {
this.slots[(this.head + this.count) % this.slots.length] = item;
if (this.count < this.slots.length) this.count++;
else this.head = (this.head + 1) % this.slots.length;
this.modCount++;
}
get size(): number {
return this.count;
}
[Symbol.iterator](): Iterator<T> {
// Capture the count now: a generator's body doesn't run until the first next().
return this.walk(this.modCount);
}
private *walk(expected: number): Generator<T, void, undefined> {
for (let offset = 0; offset < this.count; offset++) {
if (this.modCount !== expected) throw new Error("RingBuffer changed during iteration");
yield this.slots[(this.head + offset) % this.slots.length] as T;
}
}
}
function assert(cond: boolean, msg = "assertion failed"): void {
if (!cond) throw new Error(msg);
}
const recent = new RingBuffer<string>(3);
for (const e of ["login", "view", "cart", "pay"]) recent.add(e);
assert([...recent].join() === "view,cart,pay");
const a = recent[Symbol.iterator]();
const b = recent[Symbol.iterator]();
a.next();
assert(a.next().value === "cart" && b.next().value === "view");
const it = recent[Symbol.iterator]();
it.next();
recent.add("logout");
let threw = false;
try { it.next(); } catch { threw = true; }
assert(threw, "expected fail-fast error");
// JavaScript iterators signal the end with done: true instead of throwing.
assert(new RingBuffer<string>(2)[Symbol.iterator]().next().done === true);
console.log("ring buffer: all assertions passed");
Walking through the design
The collection's fields are private again. head, size and the array are invisible to callers, so the buffer could switch to a different layout without breaking anyone. The bug in the old CsvExporter can't happen, because the modular arithmetic exists in exactly one place.
Each call to iterator() returns a fresh cursor. That's what makes the nested-loop and two-traversal cases work. A common mistake is to store the cursor on the collection itself (buffer.reset(); while (buffer.hasNext())), which breaks as soon as two loops overlap.
hasNext has no side effects. Calling it twice must not skip an element. All movement happens in next. Java's contract also says next throws NoSuchElementException when there is nothing left, which the demo checks. Python signals the end by raising StopIteration (a generator does this automatically when its function returns), and JavaScript returns { done: true }.
The fail-fast check uses a modification counter. Every structural change increments modCount. The iterator remembers the value it saw at creation and compares on each next. This is exactly how java.util.ArrayList and HashMap detect concurrent modification, as the fail-fast section below shows.
The generator versions capture the counter eagerly. A generator's body doesn't start running until the first next(). If __iter__ were itself the generator, expected would be captured at the first next(), not when the iterator was created, and a change in between would go unnoticed. Splitting it into a normal method that passes the current count to a private generator fixes this. It's a small detail that shows you understand how generators actually execute.
Generators and yield
Writing the Java RingIterator took an inner class with a field for the cursor. The Python and TypeScript versions are a loop with yield in it. That's the main idea of a generator: a function that can pause in the middle, hand a value to the caller, and resume where it stopped on the next request. The language turns the function's local variables and position into the iterator's state for you.
This matters most for traversals whose state is awkward to keep by hand. In-order traversal of a binary tree is the classic example. With recursion it's three lines, but an explicit iterator has to manage a stack itself.
import java.util.*;
public class InOrderDemo {
record Node(int value, Node left, Node right) {
static Node leaf(int v) { return new Node(v, null, null); }
}
// Without generators, the call stack must be rebuilt by hand.
static final class InOrder implements Iterator<Integer> {
private final Deque<Node> stack = new ArrayDeque<>();
InOrder(Node root) { pushLeft(root); }
private void pushLeft(Node n) { for (; n != null; n = n.left()) stack.push(n); }
@Override public boolean hasNext() { return !stack.isEmpty(); }
@Override public Integer next() {
if (stack.isEmpty()) throw new NoSuchElementException();
Node n = stack.pop();
pushLeft(n.right());
return n.value();
}
}
public static void main(String[] args) {
Node root = new Node(5, new Node(3, Node.leaf(1), Node.leaf(4)), new Node(8, null, Node.leaf(9)));
List<Integer> all = new ArrayList<>();
new InOrder(root).forEachRemaining(all::add);
assert all.equals(List.of(1, 3, 4, 5, 8, 9)) : all;
Iterator<Integer> lazy = new InOrder(root); // stops early: only part of the tree is visited
assert lazy.next() == 1 && lazy.next() == 3;
System.out.println("in-order iterator: all assertions passed");
}
}
from __future__ import annotations
from collections.abc import Iterator
from dataclasses import dataclass
from itertools import count, islice
@dataclass
class Node:
value: int
left: Node | None = None
right: Node | None = None
def in_order(node: Node | None) -> Iterator[int]:
if node is not None:
yield from in_order(node.left)
yield node.value
yield from in_order(node.right)
def order_ids(prefix: str) -> Iterator[str]:
for n in count(1): # infinite, but only computed on demand
yield f"{prefix}-{n:04d}"
if __name__ == "__main__":
root = Node(5, Node(3, Node(1), Node(4)), Node(8, None, Node(9)))
assert list(in_order(root)) == [1, 3, 4, 5, 8, 9]
gen = in_order(root)
assert next(gen) == 1 and next(gen) == 3 # lazy: the rest is not visited yet
assert list(gen) == [4, 5, 8, 9]
assert list(gen) == [] # a generator is one-shot
assert list(islice(order_ids("ORD"), 3)) == ["ORD-0001", "ORD-0002", "ORD-0003"]
log = "INFO start\nERROR disk full\nINFO retry\nERROR disk full again"
errors = (line for line in log.splitlines() if line.startswith("ERROR"))
assert next(errors) == "ERROR disk full" # stops reading at the first match
print("generators: all assertions passed")
type TreeNode = { value: number; left?: TreeNode; right?: TreeNode };
function* inOrder(node: TreeNode | undefined): Generator<number, void, undefined> {
if (!node) return;
yield* inOrder(node.left);
yield node.value;
yield* inOrder(node.right);
}
function* take<T>(source: Iterable<T>, n: number): Generator<T, void, undefined> {
if (n <= 0) return;
for (const item of source) {
yield item;
if (--n === 0) return; // returning closes the source iterator too
}
}
function* naturals(): Generator<number, never, undefined> {
for (let n = 1; ; n++) yield n;
}
const root: TreeNode = {
value: 5,
left: { value: 3, left: { value: 1 }, right: { value: 4 } },
right: { value: 8, right: { value: 9 } },
};
const all = [...inOrder(root)];
if (all.join() !== "1,3,4,5,8,9") throw new Error(`bad order ${all}`);
const gen = inOrder(root);
gen.next();
if ([...gen].join() !== "3,4,5,8,9" || [...gen].length !== 0) throw new Error("generator should be one-shot");
if ([...take(naturals(), 3)].join() !== "1,2,3") throw new Error("take failed");
console.log("generators: all assertions passed");
What generators give you:
- Laziness. Values are produced only when asked for. The log filter reads up to the first error and stops. A traversal can be abandoned halfway with no wasted work.
- Infinite sequences.
order_idsandnaturalsnever end, and that's fine, because the consumer decides how many to take. - Pipelines with constant memory. Chaining generators (read lines, filter, transform, take) processes one item at a time end to end, instead of building a full list at each stage. This is how you process a multi-gigabyte file in Python without loading it.
- Recursive traversals without a manual stack.
yield from(Python) andyield*(JavaScript) delegate to a nested generator.
And their costs:
- One-shot. The demo shows a generator returning nothing on the second pass. A function that receives an iterable and loops over it twice (once to validate, once to process) will silently see an empty sequence the second time if it's handed a generator. If you need multiple passes, accept a re-iterable collection, or materialise it with
list(...). - Recursive generators cost depth. Each level of
yield fromadds a frame, so a value from depth d passes through d generators, and very deep trees can hit Python's recursion limit. For a degenerate (linked-list-shaped) tree, the explicit-stack version is safer. - Deferred errors. Code inside a generator, including argument validation, doesn't run until the first
next(). That's why the ring buffer validates and captures state in a normal method before returning the generator.
Java has no yield for iterators (its yield keyword is for switch expressions). The idiomatic substitutes are an explicit iterator class as above, or Stream pipelines, which are lazy too: Stream.iterate(1, n -> n + 1).limit(3) is Java's version of take(naturals(), 3).
Java's Iterator and Iterable
Java's two interfaces are small, but each method has a contract worth knowing exactly.
| Interface | Method | Contract |
|---|---|---|
Iterable<T> | iterator() | Return a new iterator each time. Implementing this is what makes for-each work. |
forEach(Consumer) | Default method: an internal iteration over all elements. | |
spliterator() | Default method used by streams and parallel streams. | |
Iterator<T> | hasNext() | True if next() would return an element. No side effects. |
next() | Return the next element, or throw NoSuchElementException. | |
remove() | Optional. Removes the last element returned by next(). The default throws UnsupportedOperationException. | |
forEachRemaining(Consumer) | Default method: apply an action to the rest. |
The enhanced for loop for (T x : coll) body is compiled to roughly for (Iterator<T> it = coll.iterator(); it.hasNext(); ) { T x = it.next(); body }. So anything that implements Iterable can be used in a for-each loop, and the loop knows nothing about the collection's internals.
Two practical rules:
- Don't leak
removeby accident. If your class wraps aListand returnslist.iterator()directly, callers can remove elements through it and bypass your invariants. ReturnCollections.unmodifiableList(list).iterator()instead, or write an iterator that doesn't supportremove. - Use
ListIteratorwhen you need to go backwards or replace in place. It addshasPrevious,previous,setandadd. Most custom collections don't need it.
In Python, the equivalents are the iterable protocol (__iter__ returns an iterator) and the iterator protocol (__next__ returns the next item or raises StopIteration, and __iter__ returns self). In JavaScript, an iterable has a [Symbol.iterator]() method, and an iterator has next() returning { value, done }. Generator objects in both languages are iterators that are also iterable (they return themselves), which is exactly why they are one-shot.
Fail-fast, snapshot and live iterators
What should happen when a collection changes while someone is iterating over it? There are three common answers, and each standard library mixes them.
Fail-fast. The iterator detects the change and throws on its next call. Java's ArrayList, HashMap and most of java.util behave this way, using a modification counter like the ring buffer above. Python's dict and set do the same for size changes, raising RuntimeError.
Snapshot. The iterator walks a copy of the data as it was when iteration began. It never throws and never sees later changes. Java's CopyOnWriteArrayList works this way, which is ideal for listener lists that are read far more often than they are written.
Live (or weakly consistent). The iterator walks the real structure and may or may not see changes made during iteration, but never throws. Java's ConcurrentHashMap iterators are documented as weakly consistent. JavaScript's Map and Set iterators visit entries added during iteration. A Python list iterator just uses an index, so removing during a loop silently skips elements.
import java.util.*;
import java.util.concurrent.CopyOnWriteArrayList;
public class FailFastDemo {
public static void main(String[] args) {
List<String> carts = new ArrayList<>(List.of("a", "b", "c", "d"));
try {
for (String c : carts) if (c.equals("a")) carts.remove(c);
assert false : "expected ConcurrentModificationException";
} catch (ConcurrentModificationException expected) { }
// Best effort only: removing the second-to-last element ends the loop silently.
List<String> quirk = new ArrayList<>(List.of("a", "b", "c"));
for (String c : quirk) if (c.equals("b")) quirk.remove(c);
assert quirk.equals(List.of("a", "c")); // "c" was never visited, and nothing was thrown
// Correct ways to remove while iterating.
List<String> items = new ArrayList<>(List.of("a", "b", "c", "d"));
for (Iterator<String> it = items.iterator(); it.hasNext(); ) {
if (it.next().equals("b")) it.remove();
}
items.removeIf(s -> s.equals("d"));
assert items.equals(List.of("a", "c"));
// Snapshot: never throws, and doesn't see elements added during the loop.
List<String> listeners = new CopyOnWriteArrayList<>(List.of("x", "y"));
int visited = 0;
for (String s : listeners) { listeners.add(s + "!"); visited++; }
assert visited == 2 && listeners.size() == 4;
System.out.println("fail-fast: all assertions passed");
}
}
prices = {"apple": 3, "pear": 4}
try:
for name in prices:
prices[name + "-organic"] = 5
raise AssertionError("expected RuntimeError")
except RuntimeError as e:
assert "changed size during iteration" in str(e)
nums = [1, 2, 2, 3]
for n in nums:
if n == 2:
nums.remove(n)
assert nums == [1, 2, 3] # no error, but the second 2 was skipped
nums = [1, 2, 2, 3]
nums = [n for n in nums if n != 2] # correct: build a new list
assert nums == [1, 3]
for name in list(prices): # or iterate over a snapshot of the keys
if name == "pear":
del prices[name]
assert "pear" not in prices
print("fail-fast: all assertions passed")
// Map iterators are live: entries added during the loop are visited.
const m = new Map<string, number>([["a", 1]]);
const seen: string[] = [];
for (const [k] of m) {
seen.push(k);
if (m.size < 3) m.set(k + "!", 0);
}
if (seen.join() !== "a,a!,a!!") throw new Error(`unexpected ${seen}`);
// Deleting the current entry during iteration is safe for Map and Set.
const s = new Set([1, 2, 3, 4]);
for (const n of s) if (n % 2 === 0) s.delete(n);
if ([...s].join() !== "1,3") throw new Error("set delete failed");
console.log("live iterators: all assertions passed");
Note the second Java case. Fail-fast is best effort, not a guarantee. The ArrayList iterator checks the counter in next(), but hasNext() only compares the cursor with the current size. Removing the second-to-last element shrinks the list so that hasNext() returns false, the loop ends, and the last element is silently skipped. The Java documentation says as much: fail-fast behaviour exists to catch bugs, and programs shouldn't rely on it for correctness.
Which should your own collection do? For a single-threaded domain collection, fail-fast is usually right: modifying while iterating is almost always a bug, and failing loudly finds it. For a collection read by many threads and written rarely, snapshot iteration avoids locking during reads. For high-throughput concurrent maps, weakly consistent iteration is the trade-off the standard libraries make. Whatever you choose, document it, because callers can't guess.
None of these make an ordinary iterator thread-safe. A fail-fast iterator is a bug detector, not a lock. If one thread iterates while another writes, either lock around the whole traversal, iterate over a copy, or use a concurrent collection.
Real-world uses
- Language-level loops. Java's enhanced for loop works on any
Iterable. Python'sfor,list(),sum(), unpacking and comprehensions all use the iterator protocol. JavaScript'sfor...of, spread syntax, destructuring,Array.fromandPromise.allaccept any iterable. - Standard collections. Every Java collection implements
Iterable;ArrayList,HashMapand friends have fail-fast iterators, andCopyOnWriteArrayListhas snapshot iterators. - Python's standard library. File objects iterate line by line,
itertoolsprovides lazy building blocks (islice,chain,groupby,count), anddict.items()returns a view you can iterate. - Database cursors. JDBC's
ResultSetis a cursor you advance withnext(), and Python's DB-API cursors are iterable, so you can loop over rows without loading the whole result. - Async iteration. JavaScript has async iterators and
for await...of; Node.js readable streams are async iterable, so you can loop over chunks of a file or a network response. Python has the matchingasync forwith__aiter__and__anext__. - Paginated APIs. SDKs often wrap "fetch page, follow the next-page token" in an iterator, so callers loop over items and never see pages. boto3's paginators are a well-known example.
When NOT to use it
- When a built-in collection already does the job. If your class holds a
List, expose a read-only view (List.copyOf,Collections.unmodifiableList, a tuple in Python, aReadonlyArrayin TypeScript) instead of writing an iterator class. - When callers need random access or the size. An iterator gives sequential access only. If the use case is "the 50th element" or "how many are there?", provide those methods directly.
- When a one-shot traversal would surprise callers. Returning a generator from a method that callers will loop over twice causes silent bugs. Return a list, or a re-iterable object whose
__iter__creates a fresh generator each time. - When materialising is simpler and the data is small. A ten-element list doesn't need lazy evaluation. Laziness costs debuggability (stack traces from deep inside a generator chain) and makes the timing of side effects harder to reason about.
Related patterns
Composite. Composite builds trees, and Iterator walks them. A tree that provides depth-first and breadth-first iterators lets clients loop over every node without writing recursion themselves.
Visitor. Both separate an operation from the structure, but they divide the work differently. An iterator hands elements to the client one at a time and the client decides what to do. A visitor pushes a type-specific operation into each element, using double dispatch. Use an iterator when the elements are of one kind, or the client treats them uniformly. Use a visitor when each element type needs different handling.
Factory Method. iterator() is a factory method: each collection decides which concrete iterator class to create, and clients depend only on the interface.
Memento. An iterator's position is a kind of memento. A pagination token (an opaque cursor such as "after id 4812") lets a client resume a traversal later without knowing how the server stores its data.
Observer. The two are duals. With an iterator, the consumer pulls the next value when it's ready. With an observer (or an RxJS Observable), the producer pushes values when they happen. Async iterators sit between the two: the consumer pulls, but each value may arrive later.
The smell that suggests it
- A class exposes its internal array, list, indices or node pointers (
getItems(),getHead(),getNext()) so callers can loop. - The same traversal loop, including index arithmetic or recursion, appears in several callers.
- A method builds a full list only so the caller can loop over it once, especially for large or unbounded data such as files, query results or paginated APIs.
- Callers know whether the collection is a tree, a ring or a linked list. They shouldn't need to.
- "Reset" and "hasNext" methods on the collection itself, which means only one traversal can happen at a time.
Interview questions
-
"What's the difference between Iterable and Iterator?" An iterable is something you can traverse; each call to
iterator()(or__iter__, or[Symbol.iterator]()) gives a fresh, independent cursor. An iterator is a cursor: it holds a position and is used up after one pass. Generators are iterators, which is why iterating one twice gives nothing the second time. -
"Why does removing from an ArrayList inside a for-each throw ConcurrentModificationException?" The list counts structural changes in
modCount. The iterator records that count when it's created and checks it innext().list.removechanges the count behind the iterator's back, so the nextnext()throws. Useiterator.remove()orremoveIf, which keep the iterator in sync. -
"Is fail-fast behaviour guaranteed?" No. It's best effort for catching bugs. For example, removing the second-to-last element makes
hasNext()return false, so the loop ends quietly and skips the last element. And it's not a thread-safety mechanism: concurrent writes need locking, copying or a concurrent collection. -
"How would you write an iterator for a binary tree?" With generators, a recursive in-order function using
yield fromoryield*. Without them, an explicit stack: push the leftmost path; onnext(), pop a node, push the leftmost path of its right child, and return the node. Each element is pushed and popped once, so a full traversal is O(n) with O(h) extra space for tree height h. -
"What are the benefits of generators?" Laziness (compute only what's consumed), infinite sequences, constant-memory pipelines, and recursive traversals without manual state. The costs are one-shot use, deferred execution of validation and side effects, and recursion depth for deep structures.
-
"How do you make a custom collection usable in a for-each loop?" Java: implement
Iterable<T>and return a new iterator fromiterator(). Python: implement__iter__, usually as a method that returns a generator. TypeScript or JavaScript: implement[Symbol.iterator](). -
"Your class wraps a List. What's wrong with returning
list.iterator()?" It exposesremove(), so callers can change your internal list and break its invariants. Return an iterator over an unmodifiable view, or a defensive copy if the caller needs a snapshot. -
"Internal vs external iteration?" External: the client drives the loop with
hasNext/nextand can stop, pause or interleave traversals. Internal: the collection drives the loop and calls the client's function for each element, such asforEachor streams. Internal iteration is shorter and lets the library optimise or parallelise, but makes early exit and lock-step traversal of two collections awkward. -
"How would you iterate over a paginated API?" Wrap it in an iterator (or async iterator) that holds the current page and the next-page token, yields items from the page, and fetches the next page only when the current one runs out. Callers see a flat sequence of items, and nothing is fetched until it's needed.
Further reading
- Behavioral patterns overview: the other behavioral patterns at a glance.
- Composite pattern: the tree structures iterators most often walk.
- Visitor pattern: the alternative when each element type needs different handling.
- Race conditions: why iterating shared collections needs more than a fail-fast check.
- Pattern selection guide: where Iterator fits among the other patterns.