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:
- Nothing in the body runs when the method is called; the call only creates the state machine.
- The body runs once per item, so a side effect inside it repeats on every walk, exactly as a lambda in a query does.
- A second walk starts the body again from the top, so an iterator over a file reads the file twice.
- ToList and ToArray on an iterator run it to the end once and store the items.
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
- Write an iterator that yields the lines of a string one at a time and take the first two.
- Add a Console.WriteLine after the yield break of the second program and see whether it ever runs.
- Turn the Fibonacci iterator into one with a limit and compare the two call sites.
- 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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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