📝 Lesson 1.3: Iterators and Lazy Sequences

The Pull Model

A foreach loop doesn't receive a whole collection at once — it pulls items one at a time. Under the hood, IEnumerable<T> hands out an IEnumerator<T>, and the loop repeatedly calls MoveNext() and reads Current until there's nothing left.

Historically, implementing that enumerator by hand was tedious boilerplate. The yield keyword lets the compiler write it for you — you just describe what to produce, and in what order.

yield return

An iterator method uses yield return to hand back the next value. Execution pauses there and resumes on the following pull:

public static IEnumerable<int> Countdown(int from)
{
    for (int i = from; i >= 1; i--)
    {
        yield return i;      // produce i, then pause here until the next pull
    }
    yield return 0;          // and finally 0
}

foreach (int n in Countdown(3))
{
    Console.Write($"{n} ");
}
// 3 2 1 0

Use yield break to stop the sequence early — it ends the iteration, like return in a normal method:

public static IEnumerable<int> TakeWhilePositive(IEnumerable<int> source)
{
    foreach (int n in source)
    {
        if (n <= 0) yield break;   // stop entirely at the first non-positive
        yield return n;
    }
}

// From { 3, 7, 2, -1, 9 } → yields 3, 7, 2 then stops

Lazy Evaluation

The defining feature of iterators is laziness: none of the method body runs until you start enumerating, and each item is produced only when pulled. This is the same deferred execution you saw with LINQ in Intermediate — now you understand its source.

public static IEnumerable<int> Numbers()
{
    Console.WriteLine("  [producing 1]"); yield return 1;
    Console.WriteLine("  [producing 2]"); yield return 2;
    Console.WriteLine("  [producing 3]"); yield return 3;
}

Console.WriteLine("Before foreach");
var seq = Numbers();               // nothing printed yet — body hasn't run
Console.WriteLine("Created; now iterating");
foreach (int n in seq)
{
    Console.WriteLine($"Got {n}");
}

Before foreach
Created; now iterating
  [producing 1]
Got 1
  [producing 2]
Got 2
  [producing 3]
Got 3

The Hidden State Machine

How can a method "pause" and "resume"? The compiler rewrites your iterator into a hidden class — a state machine — that remembers where it left off (which line, and the values of local variables) between pulls.

// You write this...
public static IEnumerable<int> TwoValues()
{
    yield return 10;
    yield return 20;
}

// ...the compiler generates (conceptually) a class that tracks a 'state'
// field: state 0 → return 10 and remember "next time, go to state 1";
// state 1 → return 20; state 2 → done. MoveNext() advances the state.

💡 The mental model: each yield return is a bookmark. When the enumerator's MoveNext() is called, the state machine jumps back to the last bookmark, runs until the next yield, and pauses again — carrying your local variables along.

Infinite Sequences

Because items are produced on demand, an iterator can describe a sequence with no end — you just take as many as you need. A finite List could never do this:

public static IEnumerable<int> Naturals()
{
    int n = 1;
    while (true)          // infinite — but that's fine, it's lazy!
    {
        yield return n++;
    }
}

// Take just the first 5 — the loop only runs 5 times
foreach (int n in Naturals().Take(5))
{
    Console.Write($"{n} ");
}
// 1 2 3 4 5

A classic example — an infinite Fibonacci sequence, consumed lazily with LINQ:

public static IEnumerable<long> Fibonacci()
{
    long a = 0, b = 1;
    while (true)
    {
        yield return a;
        (a, b) = (b, a + b);   // tuple deconstruction to advance
    }
}

var firstTen = Fibonacci().Take(10).ToList();
Console.WriteLine(string.Join(", ", firstTen));
// 0, 1, 1, 2, 3, 5, 8, 13, 21, 34

Pitfalls of Deferred Iterators

var results = ExpensiveQuery();   // deferred
var count = results.Count();      // runs the query once
var first = results.First();      // runs it AGAIN

// Fix: materialize once
var list = ExpensiveQuery().ToList();
var count2 = list.Count;          // no re-run
var first2 = list[0];

Exercise & Quiz

foreach (var n in Powers(2).Take(6)) Console.Write($"{n} ");   // 1 2 4 8 16 32
Console.WriteLine();
Console.WriteLine(string.Join(", ", Range(1, 10).EveryOther())); // 1, 3, 5, 7, 9

static IEnumerable<int> Range(int start, int count)
{
    // TODO: yield count values starting at start
}

static IEnumerable<int> Powers(int baseValue)
{
    // TODO: infinite — yield baseValue^0, ^1, ^2, ...
}

public static class SeqExtensions
{
    public static IEnumerable<T> EveryOther<T>(this IEnumerable<T> source)
    {
        // TODO: yield items at index 0, 2, 4, ...
    }
}

foreach (var n in Powers(2).Take(6)) Console.Write($"{n} ");   // 1 2 4 8 16 32
Console.WriteLine();
Console.WriteLine(string.Join(", ", Range(1, 10).EveryOther())); // 1, 3, 5, 7, 9

static IEnumerable<int> Range(int start, int count)
{
    for (int i = 0; i < count; i++)
    {
        yield return start + i;
    }
}

static IEnumerable<int> Powers(int baseValue)
{
    long current = 1;
    while (true)
    {
        yield return (int)current;
        current *= baseValue;
    }
}

public static class SeqExtensions
{
    public static IEnumerable<T> EveryOther<T>(this IEnumerable<T> source)
    {
        int index = 0;
        foreach (T item in source)
        {
            if (index % 2 == 0)
            {
                yield return item;
            }
            index++;
        }
    }
}

Summary

📚 Additional Resources

• yield statement — C# reference
• Iterators — Microsoft Docs
• IEnumerable<T> — API reference

🚀 What's Next?

That completes Module 1! You've mastered advanced language features. In Module 2, we tackle running code on many threads. First up: Lesson 2.1: Threads, the Thread Pool, and Tasks — the foundation of concurrency.