gof-iterator

One-line summary

Provide a way to access the elements of an aggregate object sequentially without exposing its underlying representation.

When to use this skill

• Multiple aggregate types must be traversed uniformly even though they use different internal structures (one uses an array, another a hash map, a third a linked list).
• A method consumes a collection but should not depend on which concrete collection type it is.
• Implementing a custom collection that needs to be traversable in client code (a tree, a graph, a paginated remote dataset).

When NOT to use this skill

• The language already gives you iteration over standard collections (every modern language does) and you're not designing a custom collection — just use the language's for-each / iteration.
• The "iteration" is really a transform or filter pipeline — that's a higher-level concept; reach for the language's streams / sequences.
• You need random access, not sequential access — Iterator is sequential by definition.

Core content

The pattern separates two concerns:

• The Aggregate owns the data and knows its internal structure.
• The Iterator knows how to walk that structure one element at a time.

The aggregate provides a method (typically iterator()) that returns a fresh Iterator. The Iterator implements the standard interface (hasNext(), next(), occasionally remove()).

Multiple iterators may exist over the same aggregate at the same time, each tracking its own position — that's why iteration state belongs to the Iterator, not the aggregate.

The pattern is so foundational that virtually every modern language has it built into the language and standard library. Kotlin, Java, C#, Python, Swift, Rust, JavaScript — all have Iterator or Iterable interfaces and for loops that consume them.

Decision heuristics

• For built-in collections, never roll your own Iterator — the language provides one.
• When designing a custom collection or stream, implement the language's standard Iterator interface so client code can use idiomatic iteration (Kotlin for over Iterable, Java for-each, Python for x in y).
• For a one-time traversal that filters or transforms, prefer a stream / sequence over a stateful iterator.

Anti-patterns

• Exposing the underlying collection (getInternalList()) and letting callers iterate it directly — defeats encapsulation; callers depend on the concrete type.
• Iterators that mutate the aggregate during traversal in ways the aggregate didn't sanction — usually causes concurrent-modification bugs.
• Custom iterators that don't match the language's standard interface — forces client code into bespoke patterns.

See also

• gof-composite — Iterator is the natural way to walk a Composite structure.
• gof-kotlin-idioms — Sequence, Iterable, the Iterator<T> interface, and iterator { yield(x) } builders are first-class; rolling your own iterator class is rarely the right move.

References

• Head First Design Patterns (2nd ed), Ch. 9 ("Well-Managed Collections: the Iterator and Composite Patterns") — the canonical chapter, framed around two restaurants merging menus stored in different data structures.