yield, instruction (Visual Basic)

Article
06/23/2023

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

Syntaxe

Yield expression

Paramètres

Terme	Définition
`expression`	Obligatoire. Expression qui est implicitement convertible en type de la fonction d’itérateur ou de l’accesseur `Get` qui contient l’instruction `Yield`.

Notes

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

Vous consommez une fonction d’itérateur à partir d’une fonction en utilisant une instruction For Each... Next ou une requête LINQ. Chaque itération de la boucle For Each appelle la fonction d’itérateur. Lorsqu'une instruction Yield est atteinte dans la fonction d’itérateur, expression est retourné, et l'emplacement dans le code est conservé. L'exécution redémarrera à partir de cet emplacement la prochaine fois que la fonction d'itérateur sera appelée.

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

Utilisez une instruction Exit Function ou Return pour terminer l’itération.

« Yield » n’est pas un mot réservé et a une signification particulière uniquement lorsqu’il est utilisé dans une fonction Iterator ou un accesseur Get.

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

Fonctions d’itérateur et accesseurs Get

La déclaration d'une fonction d’itérateur ou d’un accesseur Get doit respecter les spécifications suivantes :

Elle doit inclure un modificateur Iterator.
Le type de retour doit être IEnumerable, IEnumerable<T>, IEnumerator, ou IEnumerator<T>.
Elle ne peut pas avoir de paramètres ByRef.

Une fonction d’itérateur ne peut pas être présente 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 instruction Yield peut se trouver à l’intérieur d’un bloc Try d’une instruction Try... Catch... Finally. Un bloc Try qui a une instruction Yield peut avoir des blocs Catch et peut avoir un bloc Finally.

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

Si le corps For Each (en dehors de la fonction d’itérateur) lève une exception, un bloc Catch dans la fonction d’itérateur n’est pas exécuté, mais un bloc Finally dans la fonction d’itérateur est exécuté. Un bloc Catch à 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 IEnumerable (Of String) depuis une fonction d’itérateur, puis itère au sein des éléments de IEnumerable (Of String).

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

L'appel à MyIteratorFunction n'exécute pas le corps de la fonction. À la place, l'appel retourne IEnumerable(Of String) dans la variable elements.

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

À chaque itération suivante de la boucle For Each, l'exécution du corps de l'itérateur reprend à partir de l'emplacement où elle s'est interrompue, et s'arrête encore lorsqu'elle atteint une instruction Yield. La boucle For Each se termine lorsque à la fin de la fonction d’itérateur ou un Return ou lorsqu'une instruction Exit Function est atteinte.

Exemple 1

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

Le type de retour de la méthode Iterator est IEnumerable<T>, un type interface itérateur. Lorsque la méthode Iterator est appelée, elle retourne un objet énumérable contenant les puissances 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 accesseur Get qui est un itérateur. La déclaration de propriété inclut un modificateur Iterator.

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 plus d’exemples, consultez Itérateurs.

Voir aussi

Instructions

Partager via