Custom Iterators
Ruby's collection classes feel powerful because they expose a rich vocabulary of iteration methods — each, map, select, reduce — all built on top of a single primitive: yield. When you write your own classes that represent a collection or a sequence (a linked list, a tree, a paginated API result set, a range of dates), you can give them that same expressive power by defining your own iterator methods. A custom iterator is simply a method that yields values, one at a time, to a block supplied by the caller. Once you understand that yield is the entire mechanism, writing iterators for your own data structures becomes straightforward, and mixing in the Enumerable module turns a single each method into dozens of free methods.
Cricket analogy: A ball-by-ball commentary feed is the primitive, yield, that every derived stat, run rate, wagon wheel, partnership graph, is built from, just as Ruby's rich collection methods are all built on the single primitive yield.
Writing a basic iterator with yield
The simplest custom iterator loops over an internal data structure and calls yield with each element. The caller supplies a block, and Ruby pauses your method's execution, jumps into the block with the yielded value, then resumes your method where it left off. This is the same mechanism Array#each and Hash#each use internally — they are not magic, just ordinary Ruby methods written in C (or Ruby) that call yield repeatedly.
Cricket analogy: A scorer reading out one delivery at a time and pausing after each so the commentator can react, then resuming to read the next ball, mirrors exactly how a custom each method yields to a block and resumes afterward.
class Playlist
def initialize(tracks)
@tracks = tracks
end
def each
return enum_for(:each) unless block_given?
@tracks.each { |track| yield track }
end
end
playlist = Playlist.new(%w[Intro Verse Chorus Outro])
playlist.each { |track| puts "Now playing: #{track}" }
# Without a block, each returns an Enumerator (lazy, chainable)
enumerator = playlist.each
puts enumerator.next #=> "Intro"
puts enumerator.next #=> "Verse"The idiom return enum_for(:each) unless block_given? (or its alias to_enum) is what makes built-in methods like Array#map return an Enumerator when called without a block. Adopting it in your own iterators lets callers chain .with_index, .lazy, or .next just like they would on a real Array.
Gaining each/map/select/reduce for free with Enumerable
Once a class defines an each method that yields elements, you can include Enumerable and instantly gain dozens of methods — map, select, reject, sort_by, reduce, min, max, group_by, and more — all implemented in terms of that single each. This is one of Ruby's best examples of the Template Method pattern: Enumerable supplies the algorithms, your class supplies the one primitive operation they all depend on.
Cricket analogy: A cricket board that only defines how to record one ball at a time can plug into a league-wide analytics system that supplies strike-rate sorting and grouping algorithms; the board provides the raw primitive, a Template Method arrangement.
class Playlist
include Enumerable
def initialize(tracks)
@tracks = tracks
end
def each
return enum_for(:each) unless block_given?
@tracks.each { |track| yield track }
end
end
playlist = Playlist.new(%w[Intro Verse Chorus Outro])
playlist.map(&:upcase) #=> ["INTRO", "VERSE", "CHORUS", "OUTRO"]
playlist.select { |t| t.start_with?("C") } #=> ["Chorus"]
playlist.count #=> 4
playlist.sort #=> ["Chorus", "Intro", "Outro", "Verse"]Enumerator.new for external iteration and infinite sequences
Sometimes you want to construct an iterator without defining a whole class — Enumerator.new takes a block that receives a special yielder object. Calling yielder << value or yielder.yield(value) produces the next element on demand. Combined with .lazy, this lets you describe infinite sequences (like the Fibonacci numbers or an endless counter) that only compute as many values as the caller actually consumes.
Cricket analogy: A ball-by-ball live feed generator that only produces the next delivery when a subscriber requests it, rather than pre-computing an entire innings, mirrors Enumerator.new with .lazy describing an infinite over-by-over sequence.
fibonacci = Enumerator.new do |yielder|
a, b = 0, 1
loop do
yielder << a
a, b = b, a + b
end
end
fibonacci.first(8) #=> [0, 1, 1, 2, 3, 5, 8, 13]
fibonacci.lazy.select(&:even?).first(4) #=> [0, 2, 8, 34]Calling .first(n) or .take(n) on a plain (non-lazy) infinite Enumerator built with a loop do ... end block works fine because Enumerator internally uses fibers to pause execution — but chaining eager methods like .select or .map directly on an infinite Enumerator without .lazy will hang forever, since those methods try to realize the entire sequence before returning.
- A custom iterator is any method that calls yield to hand values to a caller-supplied block.
- Use
return enum_for(:each) unless block_given?so your iterator returns a chainable Enumerator when no block is given. - Including Enumerable and defining a single each method unlocks map, select, reduce, sort_by, and dozens more for free.
- Enumerator.new with a yielder block lets you build ad-hoc iterators, including infinite lazy sequences.
- Enumerator objects use fibers internally, which is why
.nextcan pause and resume iteration across separate calls. - Always combine infinite sequences with
.lazybefore applying eager methods like map or select.
Practice what you learned
1. What is the core mechanism that all custom Ruby iterators are built on?
2. What does `include Enumerable` require a class to define in order to work?
3. What idiom allows an iterator method to return an Enumerator when called without a block?
4. Why is it safe to call `.first(8)` on an Enumerator built from an infinite `loop do ... end` block, but unsafe to call `.select` directly on it without `.lazy`?
5. In `Enumerator.new { |yielder| yielder << 1 }`, what does the `<<` operator do?
Was this page helpful?
You May Also Like
Enumerable Deep Dive
Go beyond map and select to explore Enumerable's full toolkit — sort_by, group_by, partition, each_with_object, lazy enumerators, and more — for expressive collection processing.
yield and block_given?
Understand how `yield` invokes an implicit block passed to a method, and how `block_given?` lets methods branch based on whether a block was supplied.
each, map, and select
Master the three most commonly used Enumerable methods — each for side effects, map for transformation, and select for filtering — and when to reach for which.
Blocks, Procs, and Lambdas
Explore Ruby's three flavors of closures -- blocks, Procs, and lambdas -- and how they differ in argument strictness, return semantics, and reusability.
Related Reading
Related Study Notes in Programming
Browse all study notesApache Spark Study Notes
Programming · 30 topics
ProgrammingApache Flink Study Notes
Programming · 30 topics
ProgrammingHadoop Study Notes
Programming · 30 topics
ProgrammingSnowflake Study Notes
Programming · 30 topics
ProgrammingApache Airflow Study Notes
Programming · 30 topics
Programmingdbt (Data Build Tool) Study Notes
Programming · 30 topics