Iterators and yield

yield return

A method that returns IEnumerable<T> and uses yield return is an iterator: the compiler turns the body into a state machine that produces one item per call to MoveNext. There is no list anywhere, and no return statement at the end:

var squares = Squares(4); Console.WriteLine("created"); foreach (var square in squares) { Console.WriteLine(square); } Console.WriteLine("done"); static IEnumerable<int> Squares(int count) { for (var i = 1; i <= count; i++) { Console.WriteLine($" yielding {i}"); yield return i * i; } }

dotnet run

created
  yielding 1
1
  yielding 2
4
  yielding 3
9
  yielding 4
16
done

created printed before the first item, and done after the last: the method body started at the first MoveNext, not at the call. The loop in the body stopped at each yield return and resumed there on the next step, which is why the two prints interleave.

When the body runs

An iterator is the clearest case of deferred execution in the language, and the rules follow from it:

yield break

yield break ends the sequence early, like a break that the caller also sees. The program below stops at the first word longer than three characters and never looks at the rest:

foreach (var word in Short(new[] { "a", "bb", "ccc", "dddd", "ee" }, 3)) { Console.WriteLine(word); } Console.WriteLine("end"); static IEnumerable<string> Short(IEnumerable<string> words, int max) { foreach (var word in words) { if (word.Length > max) { yield break; } yield return word; } }

dotnet run

a
bb
ccc
end

dddd was the reason to stop, and neither it nor ee was read. That is what makes an iterator over a huge source cheap: the work stops when the caller stops asking, so First() on a million-line iterator reads the first line.

An endless sequence

A while (true) with a yield return inside is an infinite sequence, which is only usable because the caller decides where to stop:

var first = Fibonacci().Take(10); var even = Fibonacci().Where(n => n % 2 == 0).Take(5); Console.WriteLine(string.Join(",", first)); Console.WriteLine(string.Join(",", even)); static IEnumerable<long> Fibonacci() { long a = 0; long b = 1; while (true) { yield return a; (a, b) = (b, a + b); } }

dotnet run

0,1,1,2,3,5,8,13,21,34
0,2,8,34,144

The first line is the first ten numbers; the second filtered the same endless sequence for even values and took five, and the two queries do not share state because each call to Fibonacci() made a new state machine. The tuple assignment (a, b) = (b, a + b) computes the right side before it writes either variable, so the swap is correct without a temporary.

Exercises

  1. Write an iterator that yields the lines of a string one at a time and take the first two.
  2. Add a Console.WriteLine after the yield break of the second program and see whether it ever runs.
  3. Turn the Fibonacci iterator into one with a limit and compare the two call sites.
  4. Walk the squares iterator twice and count the lines it prints.

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. When does the body of an iterator method start running?

    Answer

    At the first MoveNext, not at the call

    The call creates a state machine; the body runs as the caller pulls items.

  2. What does yield return do?

    Answer

    Produces one item and pauses until the next item is asked for

    The body resumes after the yield on the next step, which is what makes it lazy.

  3. What does this program print? foreach (var n in N()) Console.Write(n); Console.WriteLine(); static IEnumerable<int> N() { yield return 1; yield return 2; }

    Answer

    12

    The two yields produce the two items in order, and Write does not add a newline.

  4. What does yield break do?

    Answer

    Ends the sequence, and the caller sees no more items

    It is the early exit of an iterator, visible to the caller as the end of the sequence.

  5. How many items of an endless iterator does Take(10) pull?

    Answer

    Ten

    Take stops asking after ten, and the iterator never runs past that point.

  6. What does this program print? Console.WriteLine(S().First()); static IEnumerable<int> S() { Console.WriteLine("body"); yield return 5; Console.WriteLine("more"); yield return 6; }

    Answer

    body and then 5

    First pulls one item, so the body runs to the first yield and stops there.

  7. What is a second walk of an iterator?

    Answer

    A new run of the body from the first line

    Each enumeration calls GetEnumerator and gets a fresh state machine.

  8. What does this program print? foreach (var n in E()) Console.WriteLine(n); static IEnumerable<int> E() { yield return 1; yield break; yield return 2; }

    Answer

    1

    The second yield is never reached, and the compiler allows it in an iterator.

  9. Why is an iterator over a file cheap for a short walk?

    Answer

    The body reads only the lines the caller asks for

    Lazy evaluation stops the body where the caller stops asking.

  10. Which methods can an iterator method have?

    Answer

    IEnumerable<T> or IEnumerator<T> as the return type

    yield return needs one of those two return types, and CS1624 reports anything else.

The code on this page was built with the .NET SDK 10.0.303 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev