Aniterator can be used to step through collections such as lists and arrays.

An iterator method orget accessor performs a custom iteration over a collection. An iterator method uses theyield return statement to return each element one at a time. When ayield return statement is reached, the current location in code is remembered. Execution is restarted from that location the next time the iterator function is called.

You consume an iterator from client code by using aforeach statement or by using a LINQ query.

In the following example, the first iteration of theforeach loop causes execution to proceed in theSomeNumbers iterator method until the firstyield return statement is reached. This iteration returns a value of 3, and the current location in the iterator method is retained. On the next iteration of the loop, execution in the iterator method continues from where it left off, again stopping when it reaches ayield return statement. This iteration returns a value of 5, and the current location in the iterator method is again retained. The loop completes when the end of the iterator method is reached.

static void Main(){    foreach (int number in SomeNumbers())    {        Console.Write(number.ToString() + " ");    }    // Output: 3 5 8    Console.ReadKey();}public static System.Collections.IEnumerable SomeNumbers(){    yield return 3;    yield return 5;    yield return 8;}

The return type of an iterator method orget accessor can beIEnumerable,IEnumerable<T>,IEnumerator, orIEnumerator<T>.

You can use ayield break statement to end the iteration.

Simple Iterator

The following example has a singleyield return statement that is inside afor loop. InMain, each iteration of theforeach statement body creates a call to the iterator function, which proceeds to the nextyield return statement.

static void Main(){    foreach (int number in EvenSequence(5, 18))    {        Console.Write(number.ToString() + " ");    }    // Output: 6 8 10 12 14 16 18    Console.ReadKey();}public static System.Collections.Generic.IEnumerable<int>    EvenSequence(int firstNumber, int lastNumber){    // Yield even numbers in the range.    for (int number = firstNumber; number <= lastNumber; number++)    {        if (number % 2 == 0)        {            yield return number;        }    }}

Creating a Collection Class

In the following example, theDaysOfTheWeek class implements theIEnumerable interface, which requires aGetEnumerator method. The compiler implicitly calls theGetEnumerator method, which returns anIEnumerator.

TheGetEnumerator method returns each string one at a time by using theyield return statement.

static void Main(){    DaysOfTheWeek days = new DaysOfTheWeek();    foreach (string day in days)    {        Console.Write(day + " ");    }    // Output: Sun Mon Tue Wed Thu Fri Sat    Console.ReadKey();}public class DaysOfTheWeek : IEnumerable{    private string[] days = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];    public IEnumerator GetEnumerator()    {        for (int index = 0; index < days.Length; index++)        {            // Yield each day of the week.            yield return days[index];        }    }}

The following example creates aZoo class that contains a collection of animals.

Theforeach statement that refers to the class instance (theZoo) implicitly calls theGetEnumerator method. Theforeach statements that refer to theBirds andMammals properties use theAnimalsForType named iterator method.

static void Main(){    Zoo theZoo = new Zoo();    theZoo.AddMammal("Whale");    theZoo.AddMammal("Rhinoceros");    theZoo.AddBird("Penguin");    theZoo.AddBird("Warbler");    foreach (string name in theZoo)    {        Console.Write(name + " ");    }    Console.WriteLine();    // Output: Whale Rhinoceros Penguin Warbler    foreach (string name in theZoo.Birds)    {        Console.Write(name + " ");    }    Console.WriteLine();    // Output: Penguin Warbler    foreach (string name in theZoo.Mammals)    {        Console.Write(name + " ");    }    Console.WriteLine();    // Output: Whale Rhinoceros    Console.ReadKey();}public class Zoo : IEnumerable{    // Private members.    private List<Animal> animals = new List<Animal>();    // Public methods.    public void AddMammal(string name)    {        animals.Add(new Animal { Name = name, Type = Animal.TypeEnum.Mammal });    }    public void AddBird(string name)    {        animals.Add(new Animal { Name = name, Type = Animal.TypeEnum.Bird });    }    public IEnumerator GetEnumerator()    {        foreach (Animal theAnimal in animals)        {            yield return theAnimal.Name;        }    }    // Public members.    public IEnumerable Mammals    {        get { return AnimalsForType(Animal.TypeEnum.Mammal); }    }    public IEnumerable Birds    {        get { return AnimalsForType(Animal.TypeEnum.Bird); }    }    // Private methods.    private IEnumerable AnimalsForType(Animal.TypeEnum type)    {        foreach (Animal theAnimal in animals)        {            if (theAnimal.Type == type)            {                yield return theAnimal.Name;            }        }    }    // Private class.    private class Animal    {        public enum TypeEnum { Bird, Mammal }        public string Name { get; set; }        public TypeEnum Type { get; set; }    }}

Using Iterators with a Generic List

In the following example, theStack<T> generic class implements theIEnumerable<T> generic interface. ThePush method assigns values to an array of typeT. TheGetEnumerator method returns the array values by using theyield return statement.

In addition to the genericGetEnumerator method, the non-genericGetEnumerator method must also be implemented. This is becauseIEnumerable<T> inherits fromIEnumerable. The non-generic implementation defers to the generic implementation.

The example uses named iterators to support various ways of iterating through the same collection of data. These named iterators are theTopToBottom andBottomToTop properties, and theTopN method.

TheBottomToTop property uses an iterator in aget accessor.

static void Main(){    Stack<int> theStack = new Stack<int>();    //  Add items to the stack.    for (int number = 0; number <= 9; number++)    {        theStack.Push(number);    }    // Retrieve items from the stack.    // foreach is allowed because theStack implements IEnumerable<int>.    foreach (int number in theStack)    {        Console.Write("{0} ", number);    }    Console.WriteLine();    // Output: 9 8 7 6 5 4 3 2 1 0    // foreach is allowed, because theStack.TopToBottom returns IEnumerable(Of Integer).    foreach (int number in theStack.TopToBottom)    {        Console.Write("{0} ", number);    }    Console.WriteLine();    // Output: 9 8 7 6 5 4 3 2 1 0    foreach (int number in theStack.BottomToTop)    {        Console.Write("{0} ", number);    }    Console.WriteLine();    // Output: 0 1 2 3 4 5 6 7 8 9    foreach (int number in theStack.TopN(7))    {        Console.Write("{0} ", number);    }    Console.WriteLine();    // Output: 9 8 7 6 5 4 3    Console.ReadKey();}public class Stack<T> : IEnumerable<T>{    private T[] values = new T[100];    private int top = 0;    public void Push(T t)    {        values[top] = t;        top++;    }    public T Pop()    {        top--;        return values[top];    }    // This method implements the GetEnumerator method. It allows    // an instance of the class to be used in a foreach statement.    public IEnumerator<T> GetEnumerator()    {        for (int index = top - 1; index >= 0; index--)        {            yield return values[index];        }    }    IEnumerator IEnumerable.GetEnumerator()    {        return GetEnumerator();    }    public IEnumerable<T> TopToBottom    {        get { return this; }    }    public IEnumerable<T> BottomToTop    {        get        {            for (int index = 0; index <= top - 1; index++)            {                yield return values[index];            }        }    }    public IEnumerable<T> TopN(int itemsFromTop)    {        // Return less than itemsFromTop if necessary.        int startIndex = itemsFromTop >= top ? 0 : top - itemsFromTop;        for (int index = top - 1; index >= startIndex; index--)        {            yield return values[index];        }    }}

Syntax Information

An iterator can occur as a method orget accessor. An iterator cannot occur in an event, instance constructor, static constructor, or static finalizer.

An implicit conversion must exist from the expression type in theyield return statement to the type argument for theIEnumerable<T> returned by the iterator.

In C#, an iterator method cannot have anyin,ref, orout parameters.

In C#,yield is not a reserved word and has special meaning only when it is used before areturn orbreak keyword.

Technical Implementation

Although you write an iterator as a method, the compiler translates it into a nested class that is, in effect, a state machine. This class keeps track of the position of the iterator as long theforeach loop in the client code continues.

To see what the compiler does, you can use the Ildasm.exe tool to view the common intermediate language code that's generated for an iterator method.

When you create an iterator for aclass orstruct, you don't have to implement the wholeIEnumerator interface. When the compiler detects the iterator, it automatically generates theCurrent,MoveNext, andDispose methods of theIEnumerator orIEnumerator<T> interface.

On each successive iteration of theforeach loop (or the direct call toIEnumerator.MoveNext), the next iterator code body resumes after the previousyield return statement. It then continues to the nextyield return statement until the end of the iterator body is reached, or until ayield break statement is encountered.

Iterators don't support theIEnumerator.Reset method. To reiterate from the start, you must obtain a new iterator. CallingReset on the iterator returned by an iterator method throws aNotSupportedException.

For additional information, see theC# Language Specification.

Use of Iterators

Iterators enable you to maintain the simplicity of aforeach loop when you need to use complex code to populate a list sequence. This can be useful when you want to do the following:

• Modify the list sequence after the firstforeach loop iteration.

• Avoid fully loading a large list before the first iteration of aforeach loop. An example is a paged fetch to load a batch of table rows. Another example is theEnumerateFiles method, which implements iterators in .NET.

• Encapsulate building the list in the iterator. In the iterator method, you can build the list and then yield each result in a loop.

See also

• System.Collections.Generic
• IEnumerable<T>
• foreach, in
• Generics