Yield Statement (Visual Basic)

Envoie l’élément suivant d’une collection à une For Each...Next instruction.

Syntaxe

Yield expression  

Paramètres

Remarques

L’instruction Yield retourne un élément d’une collection à la fois. L’instruction Yield est incluse dans une fonction d’itérateur ou Get un accesseur, qui effectuent des itérations personnalisées sur une collection.

Vous utilisez une fonction d’itérateur à l’aide d’une fonction For Each... Instruction suivante ou requête LINQ. Chaque itération de la For Each boucle appelle la fonction itérateur. Lorsqu’une Yield instruction est atteinte dans la fonction itérateur, expression elle est retournée et l’emplacement actuel dans le code est conservé. L’exécution est redémarrée à partir de cet emplacement la prochaine fois que la fonction itérateur est appelée.

Une conversion implicite doit exister du type de expression l’instruction Yield au type de retour de l’itérateur.

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

« Rendement » n’est pas un mot réservé et a une signification spéciale uniquement lorsqu’il est utilisé dans une fonction ou Get un Iterator accesseur.

Pour plus d’informations sur les fonctions d’itérateur et Get les accesseurs, consultez Itérateurs.

Fonctions d’itérateur et obtention d’accesseurs

La déclaration d’une fonction itérateur ou Get d’un accesseur doit répondre aux exigences suivantes :

• Il doit inclure un modificateur d’itérateur .

• Le type de retour doit être IEnumerable, IEnumerable<T>ou IEnumeratorIEnumerator<T>.

• Il ne peut pas avoir de ByRef paramètres.

Une fonction d’itérateur ne peut pas se produire dans un événement, un constructeur d’instance, un constructeur statique ou un destructeur statique.

Une fonction d’itérateur peut être une fonction anonyme. Pour plus d'informations, consultez Itérateurs.

Gestion des exceptions

Une Yield instruction peut se trouver à l’intérieur d’un Try bloc d’un Try... Catch... Enfin, instruction. Un Try bloc qui a une Yield instruction peut contenir des blocs Catch et un bloc Finally.

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

Si le For Each corps (en dehors de la fonction itérateur) lève une exception, un Catch bloc dans la fonction d’itérateur n’est pas exécuté, mais un Finally bloc dans la fonction 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 d’itérateur.

Implémentation technique

Le code suivant retourne une IEnumerable (Of String) fonction d’itérateur, puis effectue une itération dans les éléments du IEnumerable (Of String).

Dim elements As IEnumerable(Of String) = MyIteratorFunction()  
    …  
For Each element As String In elements  
Next  

L’appel à MyIteratorFunction ne pas exécuter le corps de la fonction. Au lieu de cela, l’appel retourne une IEnumerable(Of String) variable elements .

Sur une itération de la For Each boucle, la MoveNext méthode est appelée .elements Cet appel exécute le corps de MyIteratorFunction jusqu’à ce que l’instruction suivante Yield soit atteinte. L’instruction Yield retourne une expression qui détermine non seulement la valeur de la element variable à consommer par le corps de la boucle, mais également la Current propriété des éléments, qui est un IEnumerable (Of String).

Sur chaque itération suivante de la For Each boucle, l’exécution du corps de l’itérateur continue à partir de l’endroit où elle s’est arrêtée, puis s’arrête à nouveau lorsqu’elle atteint une Yield instruction. La For Each boucle se termine lorsque la fin de la fonction itérateur ou d’une Return instruction Exit Function est atteinte.

Exemple 1

L’exemple suivant contient une Yield instruction qui se trouve à l’intérieur d’un For... Boucle suivante . Chaque itération du corps de l’instruction For Each crée Main un appel à la Power fonction itérateur. Chaque appel à la fonction itérateur passe à l’exécution suivante de l’instruction Yield , qui se produit pendant l’itération suivante de la For…Next boucle.

Le type de retour de la méthode itérateur est IEnumerable<T>, un type d’interface itérateur. Lorsque la méthode itérateur est appelée, elle retourne un objet énumérable qui contient les pouvoirs d’un nombre.

Sub Main()
    For Each number In Power(2, 8)
        Console.Write(number & " ")
    Next
    ' Output: 2 4 8 16 32 64 128 256
    Console.ReadKey()
End Sub

Private Iterator Function Power(
ByVal base As Integer, ByVal highExponent As Integer) _
As System.Collections.Generic.IEnumerable(Of Integer)

    Dim result = 1

    For counter = 1 To highExponent
        result = result * base
        Yield result
    Next
End Function

Exemple 2

L’exemple suivant illustre un Get accesseur qui est un itérateur. La déclaration de propriété inclut un Iterator modificateur.

Sub Main()
    Dim theGalaxies As New Galaxies
    For Each theGalaxy In theGalaxies.NextGalaxy
        With theGalaxy
            Console.WriteLine(.Name & "  " & .MegaLightYears)
        End With
    Next
    Console.ReadKey()
End Sub

Public Class Galaxies
    Public ReadOnly Iterator Property NextGalaxy _
    As System.Collections.Generic.IEnumerable(Of Galaxy)
        Get
            Yield New Galaxy With {.Name = "Tadpole", .MegaLightYears = 400}
            Yield New Galaxy With {.Name = "Pinwheel", .MegaLightYears = 25}
            Yield New Galaxy With {.Name = "Milky Way", .MegaLightYears = 0}
            Yield New Galaxy With {.Name = "Andromeda", .MegaLightYears = 3}
        End Get
    End Property
End Class

Public Class Galaxy
    Public Property Name As String
    Public Property MegaLightYears As Integer
End Class

Pour obtenir des exemples supplémentaires, consultez Itérateurs.

Voir aussi

• Instructions