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 statement to return each element one at a time. When aYield 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 aFor Each…Next statement, or by using a LINQ query.

In the following example, the first iteration of theFor Each loop causes execution to proceed in theSomeNumbers iterator method until the firstYield 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 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.

Sub Main()    For Each number As Integer In SomeNumbers()        Console.Write(number & " ")    Next    ' Output: 3 5 8    Console.ReadKey()End SubPrivate Iterator Function SomeNumbers() As System.Collections.IEnumerable    Yield 3    Yield 5    Yield 8End Function

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

You can use anExit Function orReturn statement to end the iteration.

A Visual Basic iterator function orget accessor declaration includes anIterator modifier.

Iterators were introduced in Visual Basic in Visual Studio 2012.

Simple Iterator

The following example has a singleYield statement that is inside aFor…Next loop. InMain, each iteration of theFor Each statement body creates a call to the iterator function, which proceeds to the nextYield statement.

Sub Main()    For Each number As Integer In EvenSequence(5, 18)        Console.Write(number & " ")    Next    ' Output: 6 8 10 12 14 16 18    Console.ReadKey()End SubPrivate Iterator Function EvenSequence(ByVal firstNumber As Integer, ByVal lastNumber As Integer) _As System.Collections.Generic.IEnumerable(Of Integer)    ' Yield even numbers in the range.    For number As Integer = firstNumber To lastNumber        If number Mod 2 = 0 Then            Yield number        End If    NextEnd Function

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 statement, and anIterator modifier is in the function declaration.

Sub Main()    Dim days As New DaysOfTheWeek()    For Each day As String In days        Console.Write(day & " ")    Next    ' Output: Sun Mon Tue Wed Thu Fri Sat    Console.ReadKey()End SubPrivate Class DaysOfTheWeek    Implements IEnumerable    Public days =        New String() {"Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"}    Public Iterator Function GetEnumerator() As IEnumerator _        Implements IEnumerable.GetEnumerator        ' Yield each day of the week.        For i As Integer = 0 To days.Length - 1            Yield days(i)        Next    End FunctionEnd Class

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

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

Sub Main()    Dim theZoo As New Zoo()    theZoo.AddMammal("Whale")    theZoo.AddMammal("Rhinoceros")    theZoo.AddBird("Penguin")    theZoo.AddBird("Warbler")    For Each name As String In theZoo        Console.Write(name & " ")    Next    Console.WriteLine()    ' Output: Whale Rhinoceros Penguin Warbler    For Each name As String In theZoo.Birds        Console.Write(name & " ")    Next    Console.WriteLine()    ' Output: Penguin Warbler    For Each name As String In theZoo.Mammals        Console.Write(name & " ")    Next    Console.WriteLine()    ' Output: Whale Rhinoceros    Console.ReadKey()End SubPublic Class Zoo    Implements IEnumerable    ' Private members.    Private animals As New List(Of Animal)    ' Public methods.    Public Sub AddMammal(ByVal name As String)        animals.Add(New Animal With {.Name = name, .Type = Animal.TypeEnum.Mammal})    End Sub    Public Sub AddBird(ByVal name As String)        animals.Add(New Animal With {.Name = name, .Type = Animal.TypeEnum.Bird})    End Sub    Public Iterator Function GetEnumerator() As IEnumerator _        Implements IEnumerable.GetEnumerator        For Each theAnimal As Animal In animals            Yield theAnimal.Name        Next    End Function    ' Public members.    Public ReadOnly Property Mammals As IEnumerable        Get            Return AnimalsForType(Animal.TypeEnum.Mammal)        End Get    End Property    Public ReadOnly Property Birds As IEnumerable        Get            Return AnimalsForType(Animal.TypeEnum.Bird)        End Get    End Property    ' Private methods.    Private Iterator Function AnimalsForType( _    ByVal type As Animal.TypeEnum) As IEnumerable        For Each theAnimal As Animal In animals            If (theAnimal.Type = type) Then                Yield theAnimal.Name            End If        Next    End Function    ' Private class.    Private Class Animal        Public Enum TypeEnum            Bird            Mammal        End Enum        Public Property Name As String        Public Property Type As TypeEnum    End ClassEnd Class

Try Blocks

Visual Basic allows aYield statement in theTry block of aTry...Catch...Finally Statement. ATry block that has aYield statement can haveCatch blocks, and can have aFinally block.

The following example includesTry,Catch, andFinally blocks in an iterator function. TheFinally block in the iterator function executes before theFor Each iteration finishes.

Sub Main()    For Each number As Integer In Test()        Console.WriteLine(number)    Next    Console.WriteLine("For Each is done.")    ' Output:    '  3    '  4    '  Something happened. Yields are done.    '  Finally is called.    '  For Each is done.    Console.ReadKey()End SubPrivate Iterator Function Test() As IEnumerable(Of Integer)    Try        Yield 3        Yield 4        Throw New Exception("Something happened. Yields are done.")        Yield 5        Yield 6    Catch ex As Exception        Console.WriteLine(ex.Message)    Finally        Console.WriteLine("Finally is called.")    End TryEnd Function

AYield statement cannot be inside aCatch block or aFinally block.

If theFor Each body (instead of the iterator method) throws an exception, aCatch block in the iterator function is not executed, but aFinally block in the iterator function is executed. ACatch block inside an iterator function catches only exceptions that occur inside the iterator function.

Anonymous Methods

In Visual Basic, an anonymous function can be an iterator function. The following example illustrates this.

Dim iterateSequence = Iterator Function() _                      As IEnumerable(Of Integer)                          Yield 1                          Yield 2                      End FunctionFor Each number As Integer In iterateSequence()    Console.Write(number & " ")Next' Output: 1 2Console.ReadKey()

The following example has a non-iterator method that validates the arguments. The method returns the result of an anonymous iterator that describes the collection elements.

Sub Main()    For Each number As Integer In GetSequence(5, 10)        Console.Write(number & " ")    Next    ' Output: 5 6 7 8 9 10    Console.ReadKey()End SubPublic Function GetSequence(ByVal low As Integer, ByVal high As Integer) _As IEnumerable    ' Validate the arguments.    If low < 1 Then        Throw New ArgumentException("low is too low")    End If    If high > 140 Then        Throw New ArgumentException("high is too high")    End If    ' Return an anonymous iterator function.    Dim iterateSequence = Iterator Function() As IEnumerable                              For index = low To high                                  Yield index                              Next                          End Function    Return iterateSequence()End Function

If validation is instead inside the iterator function, the validation cannot be performed until the start of the first iteration of theFor Each body.

Using Iterators with a Generic List

In the following example, theStack(Of 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 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 declaration includes theIterator keyword.

Sub Main()    Dim theStack As New Stack(Of Integer)    ' Add items to the stack.    For number As Integer = 0 To 9        theStack.Push(number)    Next    ' Retrieve items from the stack.    ' For Each is allowed because theStack implements    ' IEnumerable(Of Integer).    For Each number As Integer In theStack        Console.Write("{0} ", number)    Next    Console.WriteLine()    ' Output: 9 8 7 6 5 4 3 2 1 0    ' For Each is allowed, because theStack.TopToBottom    ' returns IEnumerable(Of Integer).    For Each number As Integer In theStack.TopToBottom        Console.Write("{0} ", number)    Next    Console.WriteLine()    ' Output: 9 8 7 6 5 4 3 2 1 0    For Each number As Integer In theStack.BottomToTop        Console.Write("{0} ", number)    Next    Console.WriteLine()    ' Output: 0 1 2 3 4 5 6 7 8 9    For Each number As Integer In theStack.TopN(7)        Console.Write("{0} ", number)    Next    Console.WriteLine()    ' Output: 9 8 7 6 5 4 3    Console.ReadKey()End SubPublic Class Stack(Of T)    Implements IEnumerable(Of T)    Private values As T() = New T(99) {}    Private top As Integer = 0    Public Sub Push(ByVal t As T)        values(top) = t        top = top + 1    End Sub    Public Function Pop() As T        top = top - 1        Return values(top)    End Function    ' This function implements the GetEnumerator method. It allows    ' an instance of the class to be used in a For Each statement.    Public Iterator Function GetEnumerator() As IEnumerator(Of T) _        Implements IEnumerable(Of T).GetEnumerator        For index As Integer = top - 1 To 0 Step -1            Yield values(index)        Next    End Function    Public Iterator Function GetEnumerator1() As IEnumerator _        Implements IEnumerable.GetEnumerator        Yield GetEnumerator()    End Function    Public ReadOnly Property TopToBottom() As IEnumerable(Of T)        Get            Return Me        End Get    End Property    Public ReadOnly Iterator Property BottomToTop As IEnumerable(Of T)        Get            For index As Integer = 0 To top - 1                Yield values(index)            Next        End Get    End Property    Public Iterator Function TopN(ByVal itemsFromTop As Integer) _        As IEnumerable(Of T)        ' Return less than itemsFromTop if necessary.        Dim startIndex As Integer =            If(itemsFromTop >= top, 0, top - itemsFromTop)        For index As Integer = top - 1 To startIndex Step -1            Yield values(index)        Next    End FunctionEnd Class

Syntax Information

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

An implicit conversion must exist from the expression type in theYield statement to the return type of the iterator.

In Visual Basic, an iterator method cannot have anyByRef parameters.

In Visual Basic, "Yield" is not a reserved word and has special meaning only when it is used in anIterator method orget accessor.

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 theFor Each...Next 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 is generated for an iterator method.

When you create an iterator for aclass orstruct, you do not 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 theFor Each…Next loop (or the direct call toIEnumerator.MoveNext), the next iterator code body resumes after the previousYield statement. It then continues to the nextYield statement until the end of the iterator body is reached, or until anExit Function orReturn statement is encountered.

Iterators do not support theIEnumerator.Reset method. To re-iterate from the start, you must obtain a new iterator.

For additional information, see theVisual Basic Language Specification.

Use of Iterators

Iterators enable you to maintain the simplicity of aFor Each 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 firstFor Each loop iteration.

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

• 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>
• For Each...Next Statement
• Yield Statement
• Iterator