Custom Iterators

Analogy categoryAnalogies

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.

ruby

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.

ruby

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.

ruby

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 .next can pause and resume iteration across separate calls.
Always combine infinite sequences with .lazy before 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?

Enumerable Deep Dive

Related Study Notes in Programming

Browse all study notes

Programming

Apache Spark Study Notes

Programming · 30 topics

Programming

Apache Flink Study Notes

Programming · 30 topics

Programming

Hadoop Study Notes

Programming · 30 topics

Programming

Snowflake Study Notes

Programming · 30 topics

Programming

Apache Airflow Study Notes

Programming · 30 topics

Programming

dbt (Data Build Tool) Study Notes

Programming · 30 topics

Topics covered

#Ruby#RubyStudyNotes#Programming#CustomIterators#Custom#Iterators#Writing#Iterator#Loops#StudyNotes#SkillVeris

Custom Iterators