Itérateurs (C#)Iterators (C#)

Un itérateur peut être utilisé pour parcourir des collections, comme des listes et des tableaux.An iterator can be used to step through collections such as lists and arrays.

Une méthode d’itérateur ou un accesseur get effectue une itération personnalisée sur une collection.An iterator method or get accessor performs a custom iteration over a collection. Une méthode d’itérateur utilise l’instruction yield return pour retourner chaque élément un par un.An iterator method uses the yield return statement to return each element one at a time. Quand une instruction yield return est atteinte, l’emplacement actif dans le code est mémorisé.When a yield return statement is reached, the current location in code is remembered. L’exécution est redémarrée à partir de cet emplacement lors de l’appel suivant de la fonction d’itérateur.Execution is restarted from that location the next time the iterator function is called.

Vous consommez un itérateur à partir du code client en utilisant une instruction foreach ou une requête LINQ.You consume an iterator from client code by using a foreach statement or by using a LINQ query.

Dans l’exemple suivant, la première itération de la boucle foreach fait que l’exécution continue dans la méthode d’itérateur SomeNumbers, jusqu’à ce que la première instruction yield return soit atteinte.In the following example, the first iteration of the foreach loop causes execution to proceed in the SomeNumbers iterator method until the first yield return statement is reached. Cette itération retourne la valeur 3, et l’emplacement actif dans la méthode d’itérateur est mémorisé.This iteration returns a value of 3, and the current location in the iterator method is retained. 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 return.On the next iteration of the loop, execution in the iterator method continues from where it left off, again stopping when it reaches a yield return statement. Cette itération retourne la valeur 5, et l’emplacement actif dans la méthode d’itérateur est mémorisé.This iteration returns a value of 5, and the current location in the iterator method is again retained. La boucle se termine quand la fin de la méthode d’itérateur est atteinte.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;
}

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>.The return type of an iterator method or get accessor can be IEnumerable, IEnumerable<T>, IEnumerator, or IEnumerator<T>.

Utilisez une instruction yield break pour terminer l'itération.You can use a yield break statement to end the iteration.

Notes

Tous les exemples de cette rubrique, à l’exception de l’exemple de l’itérateur simple, incluent des directives using pour les espaces de noms System.Collections et System.Collections.Generic.For all examples in this topic except the Simple Iterator example, include using directives for the System.Collections and System.Collections.Generic namespaces.

Itérateur simpleSimple Iterator

L’exemple suivant comprend une seule instruction yield return qui se trouve dans une boucle for.The following example has a single yield return statement that is inside a for loop. Dans Main, chaque itération du corps d’instruction foreach crée un appel à la fonction d’itérateur, qui poursuit avec l’instruction yield return suivante.In Main, each iteration of the foreach statement body creates a call to the iterator function, which proceeds to the next yield 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;
        }
    }
}

Création d’une classe de collectionCreating a Collection Class

Dans l’exemple suivant, la classe DaysOfTheWeek implémente l’interface IEnumerable, ce qui nécessite la méthode GetEnumerator.In the following example, the DaysOfTheWeek class implements the IEnumerable interface, which requires a GetEnumerator method. Le compilateur appelle implicitement la méthode GetEnumerator, qui retourne un IEnumerator.The compiler implicitly calls the GetEnumerator method, which returns an IEnumerator.

La méthode GetEnumerator retourne chaque chaîne une à la fois en utilisant l’instruction yield return.The GetEnumerator method returns each string one at a time by using the yield 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];
        }
    }
}

L’exemple suivant crée une classe Zoo qui contient une collection d’animaux.The following example creates a Zoo class that contains a collection of animals.

L’instruction foreach qui fait référence à l’instance de classe (theZoo) appelle implicitement la méthode GetEnumerator.The foreach statement that refers to the class instance (theZoo) implicitly calls the GetEnumerator method. Les instructions foreach qui font référence aux propriétés Birds et Mammals utilisent la méthode d’itérateur nommée AnimalsForType.The foreach statements that refer to the Birds and Mammals properties use the AnimalsForType 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; }
    }
}

Utilisation d’itérateurs avec une liste génériqueUsing Iterators with a Generic List

Dans l’exemple suivant, la classe générique Stack<T> implémente l'interface générique IEnumerable<T>.In the following example, the Stack<T> generic class implements the IEnumerable<T> generic interface. La méthode Push affecte des valeurs à un tableau de type T.The Push method assigns values to an array of type T. La méthode GetEnumerator retourne les valeurs de tableau à l’aide de l’instruction yield return.The GetEnumerator method returns the array values by using the yield return statement.

Outre la méthode GetEnumerator générique, la méthode GetEnumerator non générique doit également être implémentée.In addition to the generic GetEnumerator method, the non-generic GetEnumerator method must also be implemented. C’est parce que IEnumerable<T> hérite de IEnumerable.This is because IEnumerable<T> inherits from IEnumerable. L’implémentation non générique s’en remet à l’implémentation générique.The non-generic implementation defers to the generic implementation.

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.The example uses named iterators to support various ways of iterating through the same collection of data. Ces itérateurs nommés sont les propriétés TopToBottom et BottomToTop, et la méthode TopN.These named iterators are the TopToBottom and BottomToTop properties, and the TopN method.

La propriété BottomToTop utilise un itérateur dans un accesseur get.The BottomToTop property uses an iterator in a get 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];
        }
    }

}

Informations sur la syntaxeSyntax Information

Un itérateur peut être une méthode ou un accesseur get.An iterator can occur as a method or get accessor. Un itérateur ne peut pas être présent dans un événement, un constructeur d’instance, un constructeur statique ou un finaliseur statique.An iterator cannot occur in an event, instance constructor, static constructor, or static finalizer.

Il doit y avoir une conversion implicite entre le type d’expression dans l’instruction yield return et l’argument de type pour l’IEnumerable<T> retourné par l’itérateur.An implicit conversion must exist from the expression type in the yield return statement to the type argument for the IEnumerable<T> returned by the iterator.

En C#, une méthode d’itérateur ne peut avoir aucun paramètre in, ref ou out.In C#, an iterator method cannot have any in, ref, or out parameters.

En C#, « yield » n’est pas un mot réservé ; il a une signification spéciale seulement quand il est utilisé avant un mot clé return ou break.In C#, "yield" is not a reserved word and has special meaning only when it is used before a return or break keyword.

Implémentation techniqueTechnical Implementation

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.Although you write an iterator as a method, the compiler translates it into a nested class that is, in effect, a state machine. Cette classe fait le suivi de la position de l’itérateur tant que la boucle foreach du code client se poursuit.This class keeps track of the position of the iterator as long the foreach loop in the client code continues.

Pour voir ce que fait le compilateur, vous pouvez utiliser l’outil Ildasm.exe et afficher le code du langage intermédiaire Microsoft généré pour une méthode d’itérateur.To see what the compiler does, you can use the Ildasm.exe tool to view the Microsoft intermediate language code that's generated for an iterator method.

Quand vous créez un itérateur pour une classe ou un struct, vous n’avez pas besoin d’implémenter l’ensemble de l’interface IEnumerator.When you create an iterator for a class or struct, you don't have to implement the whole IEnumerator interface. 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>.When the compiler detects the iterator, it automatically generates the Current, MoveNext, and Dispose methods of the IEnumerator or IEnumerator<T> interface.

À chaque itération successive de la boucle foreach (ou de l’appel direct à IEnumerator.MoveNext), le corps du code de l’itérateur suivant reprend après l’instruction yield return précédente.On each successive iteration of the foreach loop (or the direct call to IEnumerator.MoveNext), the next iterator code body resumes after the previous yield return statement. Il continue ensuite jusqu’à l’instruction yield return suivante, jusqu’à atteindre la fin du corps de l’itérateur ou jusqu’à rencontrer une instruction yield break.It then continues to the next yield return statement until the end of the iterator body is reached, or until a yield break statement is encountered.

Les itérateurs ne prennent pas en charge la méthode IEnumerator.Reset.Iterators don't support the IEnumerator.Reset method. Pour réitérer à partir du début, vous devez obtenir un nouvel itérateur.To reiterate from the start, you must obtain a new iterator. L’appel de Reset sur l’itérateur retourné par une méthode d’itérateur lève un NotSupportedException.Calling Reset on the iterator returned by an iterator method throws a NotSupportedException.

Pour plus d’informations, consultez la spécification du langage C#.For additional information, see the C# Language Specification.

Utilisation d’itérateursUse of Iterators

Les itérateurs vous permettent de conserver la simplicité d’une boucle foreach quand vous avez besoin d’utiliser un code complexe pour remplir la séquence d’une liste.Iterators enable you to maintain the simplicity of a foreach loop when you need to use complex code to populate a list sequence. Ceci peut être utile quand vous voulez faire les opérations suivantes :This can be useful when you want to do the following:

  • Modifier la séquence de la liste après la première itération de la boucle foreach.Modify the list sequence after the first foreach loop iteration.

  • Éviter de charger entièrement une grande liste avant la première itération d’une boucle foreach.Avoid fully loading a large list before the first iteration of a foreach loop. Une extraction paginée pour charger un lot de lignes d’une table est un exemple.An example is a paged fetch to load a batch of table rows. Un autre exemple est la méthode EnumerateFiles , qui implémente les itérateurs dans le .NET Framework.Another example is the EnumerateFiles method, which implements iterators within the .NET Framework.

  • Encapsuler la création de la liste dans l’itérateur.Encapsulate building the list in the iterator. Dans la méthode d’itérateur, vous pouvez créer la liste et générer ensuite chaque résultat dans une boucle.In the iterator method, you can build the list and then yield each result in a loop.

Voir aussiSee also