Chapter 27 Iterators

1enumerator object that encapsulates the code specified in the iterator block, and execution of the code in the

2iterator block occurs when the enumerator object’s MoveNext method is invoked. An enumerable object has

3the following characteristics:

4• It implements IEnumerable and IEnumerable<T>, where T is the yield type of the iterator block.

5• It is initialized with a copy of the argument values (if any) and instance value passed to the function

6member.

7An enumerable object is typically an instance of a compiler-generated enumerable class that encapsulates the

8code in the iterator block and implements the enumerable interfaces, but other methods of implementation

9are possible. If an enumerable class is generated by the compiler, that class shall be nested, directly or

10indirectly, in the class containing the function member, it shall have private accessibility, and it shall have a

11name reserved for compiler use (§9.4.2).

12[Note: An enumerable object can implement more interfaces than those specified above. In particular, an

13enumerable object can also implement IEnumerator and IEnumerator<T>, enabling it to serve as both

14an enumerable and an enumerator. In that type of implementation, the first time an enumerable object’s

15GetEnumerator method is invoked, the enumerable object itself is returned. Subsequent invocations of the

16enumerable object’s GetEnumerator, if any, return a copy of the enumerable object. Thus, each returned

17enumerator has its own state, and changes in one enumerator will not affect another. end note]

1827.3.1 The GetEnumerator method

19An enumerable object provides an implementation of the GetEnumerator methods of the IEnumerable

20and IEnumerable<T> interfaces. The two GetEnumerator methods share a common implementation that

21acquires and returns an available enumerator object. The enumerator object is initialized with the argument

22values and instance value saved when the enumerable object was initialized, but otherwise the enumerator

23object functions as described in §27.2.

2427.4 Implementation example

25[Note: This section describes a possible implementation of iterators in terms of standard C# constructs. The

26implementation described here is by no means a mandated implementation or the only one possible.

27The following Stack<T> class implements its GetEnumerator method using an iterator. The iterator

28enumerates the elements of the stack in top to bottom order.

29using System;

30using System.Collections;

31using System.Collections.Generic;

32class Stack<T>: IEnumerable<T>

33{

427

3}

4}

5The GetEnumerator method can be translated into an instantiation of a compiler-generated enumerator

6class that encapsulates the code in the iterator block, as shown in the following.

7class Stack<T>: IEnumerable<T>

8{

52}

53}

54In the preceding translation, the code in the iterator block is turned into a state machine and placed in the

55MoveNext method of the enumerator class. Furthermore, the local variable i is turned into a field in the

56enumerator object so it can continue to exist across invocations of MoveNext.

57The following example prints a simple multiplication table of the integers 1 through 10. The FromTo

58method in the example returns an enumerable object and is implemented using an iterator.

59using System;

60using System.Collections.Generic;

428

Chapter 27 Iterators

1class Test

2{

14}

15}

16The FromTo method can be translated into an instantiation of a compiler-generated enumerable class that

17encapsulates the code in the iterator block, as shown in the following.

18using System;

19using System.Threading;

20using System.Collections;

21using System.Collections.Generic;

22class Test

23{

429

21}

22}

23The enumerable class implements both the enumerable interfaces and the enumerator interfaces, enabling it

24to serve as both an enumerable and an enumerator. The first time the GetEnumerator method is invoked,

25the enumerable object itself is returned. Subsequent invocations of the enumerable object’s

26GetEnumerator, if any, return a copy of the enumerable object. Thus, each returned enumerator has its

27own state and changes in one enumerator will not affect another. The Interlocked.CompareExchange

28method is used to ensure thread-safe operation.

29The from and to parameters are turned into fields in the enumerable class. Because from is modified in the

30iterator block, an additional __from field is introduced to hold the initial value given to from in each

31enumerator.

32The MoveNext method throws an InvalidOperationException if it is called when __state is 0. This

33protects against use of the enumerable object as an enumerator object without first calling GetEnumerator.

34The following example shows a simple tree class. The Tree<T> class implements its GetEnumerator

35method using an iterator. The iterator enumerates the elements of the tree in infix order.

36using System;

37using System.Collections.Generic;

38class Tree<T>: IEnumerable<T>

39{

52}

53}

430

Chapter 27 Iterators

1class Program

2{

25}

26}

27The GetEnumerator method can be translated into an instantiation of a compiler-generated enumerator

28class that encapsulates the code in the iterator block, as shown in the following.

29class Tree<T>: IEnumerable<T>

30{

431

48}

49}

50The compiler generated temporaries used in the foreach statements are lifted into the __left and __right

51fields of the enumerator object. The __state field of the enumerator object is carefully updated so that the

52correct Dispose() method will be called correctly if an exception is thrown. Note that it is not possible to

53write the translated code with simple foreach statements. end note]

432