Itérateurs (Visual Basic)

Un itérateur peut être utilisé pour parcourir des collections, comme des listes et des tableaux.

Une méthode d’itérateur ou un accesseur get effectue une itération personnalisée sur une collection. Une méthode Iterator utilise l’instruction yield pour retourner chaque élément un par un. Quand une instruction Yield est atteinte, l’emplacement actuel dans le code est mémorisé. L’exécution est redémarrée à partir de cet emplacement lors de l’appel suivant de la fonction d’itérateur.

Vous consommez un itérateur à partir du code client à l’aide d’un for each... Instruction Next , ou à l’aide d’une requête LINQ.

Dans l’exemple suivant, la première itération de la boucle For Each fait que l’exécution continue dans la méthode d’itérateur SomeNumbers, jusqu’à ce que la première instruction Yield soit atteinte. Cette itération retourne la valeur 3, et l’emplacement actif dans la méthode d’itérateur est mémorisé. Dans l’itération suivante de la boucle, l’exécution de la méthode d’itérateur continue là où elle s’était arrêtée, et s’arrête de nouveau quand elle atteint une instruction Yield. Cette itération retourne la valeur 5, et l’emplacement actif dans la méthode d’itérateur est mémorisé. La boucle se termine quand la fin de la méthode d’itérateur est atteinte.

Sub Main()
    For Each number As Integer In SomeNumbers()
        Console.Write(number & " ")
    Next
    ' Output: 3 5 8
    Console.ReadKey()
End Sub

Private Iterator Function SomeNumbers() As System.Collections.IEnumerable
    Yield 3
    Yield 5
    Yield 8
End Function

Le type de retour d’une méthode d’itérateur ou de l’accesseur get peut être IEnumerable, IEnumerable<T>, IEnumerator ou IEnumerator<T>.

Vous pouvez utiliser une Exit Function Return instruction ou pour terminer l’itération.

Une Visual Basic une fonction d’itérateur ou une get déclaration d’accesseur comprend un modificateur d' itérateur .

Les itérateurs ont été introduits dans Visual Basic dans Visual Studio 2012.

Dans cette rubrique

Notes

Pour tous les exemples de la rubrique, à l’exception de l’exemple d’itérateur simple, incluez les instructions Imports pour les System.Collections System.Collections.Generic espaces de noms et.

Itérateur simple

L’exemple suivant contient une Yield instruction unique qui se trouve à l’intérieur d’une instruction for... Next . Dans Main, chaque itération du corps d’instruction For Each crée un appel à la fonction d’itérateur, qui poursuit avec l’instruction Yield suivante.

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 Sub

Private 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
    Next
End Function

Création d’une classe de collection

Dans l’exemple suivant, la classe DaysOfTheWeek implémente l’interface IEnumerable, ce qui nécessite la méthode GetEnumerator. Le compilateur appelle implicitement la méthode GetEnumerator, qui retourne un IEnumerator.

La GetEnumerator méthode retourne chaque chaîne l’une après l’autre à l’aide de l' Yield instruction, et un Iterator modificateur est dans la déclaration de la fonction.

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 Sub

Private 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 Function
End Class

L’exemple suivant crée une classe Zoo qui contient une collection d’animaux.

L’instruction For Each qui fait référence à l’instance de classe (theZoo) appelle implicitement la méthode GetEnumerator. Les instructions For Each qui font référence aux propriétés Birds et Mammals utilisent la méthode d’itérateur nommée AnimalsForType.

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 Sub

Public 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 Class
End Class

Blocs try

Visual Basic autorise une Yield instruction dans le Try bloc d’une instruction try... Catch... Finally, instruction. Un Try bloc qui a une Yield instruction peut avoir des Catch blocs et peut avoir un Finally bloc.

L’exemple suivant comprend Try des Catch blocs, et Finally dans une fonction d’itérateur. Le Finally bloc de la fonction Iterator s’exécute avant la For Each fin de l’itération.

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 Sub

Private 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 Try
End Function

Une Yield instruction ne peut pas être à l’intérieur d’un Catch bloc ou d’un Finally bloc.

Si le For Each corps (au lieu de la méthode Iterator) lève une exception, un Catch bloc de la fonction d’itérateur n’est pas exécuté, mais un Finally bloc dans la fonction d’itérateur est exécuté. Un Catch bloc à l’intérieur d’une fonction d’itérateur intercepte uniquement les exceptions qui se produisent à l’intérieur de la fonction Iterator.

Méthodes anonymes

Dans Visual Basic, une fonction anonyme peut être une fonction d’itérateur. L'exemple suivant illustre ce comportement.

Dim iterateSequence = Iterator Function() _
                      As IEnumerable(Of Integer)
                          Yield 1
                          Yield 2
                      End Function

For Each number As Integer In iterateSequence()
    Console.Write(number & " ")
Next
' Output: 1 2
Console.ReadKey()

L’exemple suivant a une méthode non itérateur qui valide les arguments. La méthode retourne le résultat d’un itérateur anonyme qui décrit les éléments de la collection.

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 Sub

Public 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

Si la validation est à l’intérieur de la fonction Iterator, la validation ne peut pas être effectuée avant le début de la première itération du For Each corps.

Utilisation d’itérateurs avec une liste générique

Dans l’exemple suivant, la classe générique Stack(Of T) implémente l'interface générique IEnumerable<T>. La méthode Push affecte des valeurs à un tableau de type T. La méthode GetEnumerator retourne les valeurs de tableau à l’aide de l’instruction Yield.

Outre la méthode GetEnumerator générique, la méthode GetEnumerator non générique doit également être implémentée. C’est parce que IEnumerable<T> hérite de IEnumerable. L’implémentation non générique s’en remet à l’implémentation générique.

L’exemple utilise des itérateurs nommés pour prendre en charge différentes façons d’itérer au sein de la même collection de données. Ces itérateurs nommés sont les propriétés TopToBottom et BottomToTop, et la méthode TopN.

La BottomToTop déclaration de propriété comprend le Iterator mot clé.

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 Sub

Public 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 Function
End Class

Informations de syntaxe

Un itérateur peut être une méthode ou un accesseur get. Un itérateur ne peut pas être présent dans un événement, un constructeur d’instance, un constructeur statique ou un destructeur statique.

Une conversion implicite doit exister depuis le type d’expression dans l’instruction Yield vers le type de retour de l’itérateur.

Dans Visual Basic, une méthode d’itérateur ne peut pas avoir de ByRef paramètres.

Dans Visual Basic, « yield » n’est pas un mot réservé et a une signification spéciale uniquement lorsqu’il est utilisé dans une Iterator méthode ou un get accesseur.

Implémentation technique

Bien que vous écriviez un itérateur comme une méthode, le compilateur le traduit en une classe imbriquée, qui est en réalité une machine à états. Cette classe fait le suivi de la position de l’itérateur tant que la boucle For Each...Next du code client se poursuit.

Pour voir ce que fait le compilateur, vous pouvez utiliser l’outil Ildasm.exe pour afficher le code du langage intermédiaire Microsoft généré pour une méthode d’itérateur.

Lorsque vous créez un itérateur pour une classe ou un struct, vous n’avez pas à implémenter l' IEnumerator interface entière. Quand le compilateur détecte l’itérateur, il génère automatiquement les méthodes Current, MoveNext et Dispose de l’interface IEnumerator ou IEnumerator<T>.

À chaque itération successive de la boucle For Each…Next (ou de l’appel direct à IEnumerator.MoveNext), le corps du code de l’itérateur suivant reprend après l’instruction Yield précédente. Il continue ensuite à l’instruction suivante jusqu’à ce Yield que la fin du corps de l’itérateur soit atteinte, ou jusqu’à ce qu’une Exit Function Return instruction ou soit rencontrée.

Les itérateurs ne prennent pas en charge la IEnumerator.Reset méthode. Pour réitérer à partir du début, vous devez obtenir un nouvel itérateur.

Pour plus d’informations, consultez la spécification du langage Visual Basic.

Utilisation d’itérateurs

Les itérateurs vous permettent de conserver la simplicité d’une boucle For Each quand vous avez besoin d’utiliser un code complexe pour remplir la séquence d’une liste. Ceci peut être utile quand vous voulez faire les opérations suivantes :

  • Modifier la séquence de la liste après la première itération de la boucle For Each.

  • Éviter de charger entièrement une grande liste avant la première itération d’une boucle For Each. Une extraction paginée pour charger un lot de lignes d’une table est un exemple. Un autre exemple est la méthode EnumerateFiles , qui implémente les itérateurs dans le .NET Framework.

  • Encapsuler la création de la liste dans l’itérateur. Dans la méthode d’itérateur, vous pouvez créer la liste et générer ensuite chaque résultat dans une boucle.

Voir aussi