Iteratory (C#)

Iterator może służyć do przechodzenia przez kolekcje, takie jak listy i tablice.

Metoda iteratora lub get akcesor wykonuje niestandardowe przechodzenie po kolekcji. Metoda iteratora używa instrukcji yield return, aby zwrócić każdy element pojedynczo. Po osiągnięciu instrukcji yield return zostanie zapamiętana bieżąca lokalizacja w kodzie. Wykonanie jest uruchamiane ponownie z tej lokalizacji przy następnym wywołaniu funkcji iteratora.

Iterator jest używany w kodzie klienta za pomocą instrukcji foreach lub zapytania LINQ.

W poniższym przykładzie pierwsza iteracja pętli foreach powoduje kontynuację w metodzie iteratora SomeNumbers aż do napotkania pierwszej instrukcji yield return. Ta iteracja zwraca wartość 3, a bieżąca lokalizacja w metodzie iteratora jest zachowywana. W następnej iteracji pętli wykonywanie w metodzie iteratora jest kontynuowane od miejsca, w którym została przerwana, ponownie zatrzymując się, gdy osiągnie instrukcję yield return . Ta iteracja zwraca wartość 5, a bieżąca lokalizacja w metodzie iteratora jest ponownie zachowywana. Pętla kończy się po osiągnięciu końca metody iteratora.

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;
}

Zwracany typ metody iteratora lub get metody dostępu może być IEnumerable, IEnumerable<T>, IEnumeratorlub IEnumerator<T>.

Możesz użyć yield break instrukcji , aby zakończyć iterację.

Uwaga / Notatka

Dla wszystkich przykładów w tym temacie, z wyjątkiem przykładu prostego iteratora, zastosuj dyrektywy using dla przestrzeni nazw System.Collections i System.Collections.Generic.

Prosty iterator

Poniższy przykład zawiera pojedynczą yield return instrukcję wewnątrz pętli for . W Main każda iteracja ciała foreach instrukcji tworzy wywołanie funkcji iteratora, która przechodzi do następnej yield return instrukcji.

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;
        }
    }
}

Tworzenie klasy kolekcji

W poniższym przykładzie klasa DaysOfTheWeek implementuje interfejs IEnumerable, który wymaga metody GetEnumerator. Kompilator niejawnie wywołuje metodę GetEnumerator, która zwraca IEnumerator.

Metoda GetEnumerator zwraca każdy ciąg pojedynczo przy użyciu instrukcji yield return .

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];
        }
    }
}

Poniższy przykład tworzy klasę Zoo zawierającą kolekcję zwierząt.

Instrukcja foreach , która odwołuje się do wystąpienia klasy (theZoo) niejawnie wywołuje metodę GetEnumerator . Instrukcje foreach, które odwołują się do właściwości Birds i Mammals, używają metody iteratora nazwanej AnimalsForType.

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; }
    }
}

Używanie iteratorów z listą ogólną

W poniższym przykładzie Stack<T> klasa generyczna implementuje IEnumerable<T> interfejs generyczny. Metoda Push przypisuje wartości do tablicy typu T. Metoda GetEnumerator zwraca wartości tablicy przy użyciu instrukcji yield return .

Oprócz metody ogólnej GetEnumerator należy również zaimplementować metodę niegeneryjną GetEnumerator . Dzieje się tak, ponieważ IEnumerable<T> dziedziczy z elementu IEnumerable. Implementacja niegeneryczna odchyli się od implementacji ogólnej.

W przykładzie użyto iteratorów nazwanych do obsługi różnych sposobów iteracji za pośrednictwem tej samej kolekcji danych. Te nazwane iteratory to właściwości TopToBottom i BottomToTop oraz metoda TopN.

Właściwość BottomToTop używa iteratora w akcesorze get.

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];
        }
    }

}

Informacje o składni

Iterator może wystąpić jako metoda lub get akcesor. Iterator nie może wystąpić w zdarzeniu, konstruktorze egzemplarza, konstruktorze statycznym lub finalizatorze statycznym.

Niejawna konwersja musi istnieć z typu wyrażenia w instrukcji yield return na argument typu IEnumerable<T>, zwracany przez iterator.

W języku C# metoda iteratora nie może mieć żadnych inparametrów , reflub out .

W języku C# yield nie jest słowem zastrzeżonym i ma specjalne znaczenie tylko wtedy, gdy jest używany przed słowem kluczowym return lub break.

Implementacja techniczna

Mimo że iterator jest zapisywany jako metoda, kompilator tłumaczy go na klasę zagnieżdżoną, która jest w efekcie maszyną stanu. Ta klasa śledzi położenie iteratora, dopóki pętla foreach w kodzie klienta będzie kontynuowana.

Aby zobaczyć, co robi kompilator, możesz użyć narzędzia Ildasm.exe, aby wyświetlić wspólny kod języka pośredniego wygenerowany dla metody iteratora.

Podczas tworzenia iteratora dla klasy lub struktury nie trzeba implementować całego IEnumerator interfejsu. Gdy kompilator wykryje iterator, automatycznie generuje metody Current, MoveNext i Dispose interfejsu IEnumerator lub IEnumerator<T>.

W każdej kolejnej iteracji pętli foreach (lub bezpośrednim wywołaniu IEnumerator.MoveNext), następny blok kodu iteratora zostaje wznowiony po poprzedniej instrukcji yield return. Następnie kontynuuje wykonywanie kolejnej instrukcji yield return aż do momentu napotkania instrukcji yield break lub do osiągnięcia końca treści iteratora.

Iteratory nie obsługują IEnumerator.Reset metody . Aby powtórzyć od początku, należy uzyskać nowy iterator. Wywołanie Reset iteratora zwróconego przez metodę iteratora zgłasza błąd NotSupportedException.

Aby uzyskać dodatkowe informacje, zobacz specyfikację języka C#.

Korzystanie z iteratorów

Iteratory umożliwiają utrzymanie prostoty pętli, gdy trzeba użyć złożonego foreach kodu do wypełnienia sekwencji listy. Może to być przydatne, jeśli chcesz wykonać następujące czynności:

• Zmodyfikuj sekwencję listy po pierwszej iteracji pętli foreach.

• Unikaj pełnego ładowania dużej listy przed pierwszą iteracją pętli foreach. Przykładem jest stronicowane pobieranie danych, aby załadować partię wierszy tabeli. Innym przykładem jest EnumerateFiles metoda, która implementuje iteratory na platformie .NET.

• Zakapsułować proces tworzenia listy w iteratorze. W metodzie iteratora można utworzyć listę, a następnie uzyskać każdy wynik w pętli.

Zobacz także

• System.Collections.Generic
• IEnumerable<T>
• foreach, in
• Typy ogólne