Custom Iterators & Enumerator

A custom iterator is a class that defines an each method and includes Enumerable , instantly gaining map, select, and dozens of other collection methods for free.

Learn Custom Iterators & Enumerator in our free Ruby course — a beginner-friendly interactive lesson with worked examples, a practice exercise and a quick…

Part of the free Ruby course at LearnCodingFast — hands-on lessons with examples you run in your browser, plus practice exercises and a quick quiz.

In this lesson you'll make your own objects iterable, return chainable Enumerator objects, and tame infinite sequences with lazy evaluation.

What You'll Learn in This Lesson

1️⃣ each + Enumerable = Free Superpowers

The deal Ruby offers is generous: write a single each method that yield s every element, include Enumerable , and your class gains map , select , count , include? , min_by , sort , and roughly fifty more — all implemented in terms of each .

2️⃣ Returning an Enumerator (No Block)

Ruby's own collections do something clever: when you call each with no block, they return an Enumerator instead of looping. That object can be chained ( .with_index , .lazy ) or stepped through manually with .next . Add return to_enum(:each) unless block_given? to give your class the same power.

3️⃣ Lazy Enumerators, each_with_object & with_index

Chaining map and select on an infinite range would hang forever — unless you call .lazy first, which pulls values one at a time only as far as you actually consume. Meanwhile each_with_object threads a result object through the loop, and with_index numbers items from any starting point.

🎯 Your Turn

One keyword is missing. Replace the ___ so each item is handed to the block, making the whole Enumerable toolkit light up.

Common Errors (and the fix)

• "undefined method 'map'" — ❌ You forgot include Enumerable . ✅ Add it inside the class; each alone is not enough.
• "undefined method 'each' for ..." — ❌ Enumerable needs an each to delegate to. ✅ Define def each; ...; yield x; end .
• Program hangs on an infinite range — ❌ (1..Float::INFINITY).map { ... } never finishes. ✅ Insert .lazy before the chain.
• each returns nil instead of chaining — ❌ No guard for a missing block. ✅ Start with return to_enum(:each) unless block_given? .
• "StopIteration" from .next — ❌ You called .next past the last element. ✅ Wrap in rescue StopIteration or use peek .

Pro Tips

• 💡 One method, fifty gifts: define each well and Enumerable does the rest — don't reimplement map by hand.
• 💡 Custom sort: Enumerable's sort / min need elements that compare; the next lessons cover keyword args and Comparable.
• 💡 Enumerator.new: for sequences with no backing array (like Fibonacci), build one directly with a yielder .

Mini-Challenge: A Fibonacci Enumerator

Build an infinite Fibonacci sequence with Enumerator.new , then use first and lazy to pull slices out of it. Run with ruby fib.rb .

📋 Quick Reference — Iterators & Enumerator

Goal

Ruby

Make a class iterable

include Enumerable + def each

Return an Enumerator

return to_enum(:each) unless block_given?

Lazy infinite chain

range.lazy.map.select.first(n)

Build a result

each_with_object(Hash.new(0))

Number items

each.with_index(1)

Sequence with no array

Enumerator.new { |y| y << x }

Frequently Asked Questions

🎉 Lesson Complete!

• ✅ Define each + include Enumerable for free collection methods
• ✅ Return to_enum(:each) so a block-less call gives an Enumerator
• ✅ .lazy makes infinite sequences safe to chain
• ✅ each_with_object builds up a result while iterating
• ✅ with_index numbers items from any start value
• ✅ Next lesson: Method Arguments — keyword, splat, and block parameters

Practice quiz

Continue this course

• Previous: Checkpoint: OOP & Stdlib
• Next: Method Arguments