Итераторы (C#)

Итератор можно использовать для пошагового выполнения коллекций, таких как списки и массивы.

Метод итератора или get аксессор выполняет настраиваемую итерацию по коллекции. Метод итератора использует оператор yield return для возврата каждого элемента по одному. После достижения инструкции запоминается текущее yield return расположение в коде. Выполнение перезапускается из этого расположения при следующем вызове функции итератора.

Вы используете итератор из клиентского кода с помощью инструкции foreach или с помощью запроса LINQ.

В следующем примере первая итерация foreach цикла приводит к тому, что выполнение продолжается в методе итератора SomeNumbers до того, как будет достигнута первая yield return инструкция. Эта итерация возвращает значение 3, а текущее расположение в методе итератора сохраняется. В следующей итерации цикла выполнение в методе итератора продолжается с того места, где он остался, снова остановившись при достижении инструкции yield return . Эта итерация возвращает значение 5, а текущее расположение в методе итератора снова сохраняется. Цикл завершается после достижения конца метода итератора.

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

Возвращаемый тип метода итератора или аксессора get может быть IEnumerable, IEnumerable<T>, IEnumerator или IEnumerator<T>.

Вы можете использовать выражение yield break для завершения итерации.

Замечание

Для всех примеров в этом разделе, кроме примера Простого итератора, включите директивы using для пространств имен System.Collections и System.Collections.Generic.

Простой итератор

В следующем примере имеется один оператор yield return, который находится внутри цикла for. В Mainкаждом итерации текста инструкции foreach создается вызов функции итератора, которая переходит к следующей yield return инструкции.

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

Создание класса коллекции

В следующем примере DaysOfTheWeek класс реализует IEnumerable интерфейс, для которого требуется GetEnumerator метод. Компилятор неявно вызывает GetEnumerator метод, который возвращает IEnumerator.

Метод GetEnumerator возвращает каждую строку по одному за раз с помощью инструкции 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];
        }
    }
}

В следующем примере создается Zoo класс, содержащий коллекцию животных.

Оператор foreach, ссылающийся на экземпляр класса (theZoo), неявно вызывает метод GetEnumerator. Инструкции foreach, ссылающиеся на свойства Birds и Mammals, используют метод именованного итератора 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; }
    }
}

Использование итераторов с универсальным списком

В следующем примере универсальный Stack<T> класс реализует универсальный IEnumerable<T> интерфейс. Метод Push назначает значения массиву типов T. Метод GetEnumerator возвращает значения массива с помощью инструкции yield return .

В дополнение к обобщенному методу GetEnumerator, также должен быть реализован не обобщенный метод GetEnumerator. Это связано с тем, что IEnumerable<T> наследует от IEnumerable. Не универсальная реализация откладывает универсальную реализацию.

В примере используются именованные итераторы для поддержки различных способов итерации по одной коллекции данных. Эти именованные итераторы — TopToBottom и свойства BottomToTop, а также метод TopN.

Свойство BottomToTop использует итератор в аксесcоре 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];
        }
    }

}

Сведения о синтаксисе

Итератор может выполняться как метод или get метод доступа. Итератор не может использоваться в событии, конструкторе экземпляра, статическом конструкторе или статическом финализаторе.

Неявное преобразование должно существовать из типа выражения в yield return операторе в аргумент типа для IEnumerable<T> возвращаемого итератора.

В C# метод итератора не может иметь никаких inref или out параметров.

В C# yield не является зарезервированным словом и имеет особое значение, только если используется перед ключевым словом return или break.

Техническая реализация

Хотя вы пишете итератор в качестве метода, компилятор преобразует его в вложенный класс, который, в действительности, является компьютером состояния. Этот класс отслеживает положение итератора до тех пор, пока foreach цикл в клиентском коде продолжается.

Чтобы узнать, что делает компилятор, можно использовать средство Ildasm.exe для просмотра кода общего промежуточного языка, созданного для метода итератора.

При создании итератора для класса или структуры не требуется реализовать весь IEnumerator интерфейс. Когда компилятор обнаруживает итератор, он автоматически создает методы Current, MoveNext и Dispose интерфейса IEnumerator или IEnumerator<T>.

При каждой последовательной foreach итерации цикла (или прямого вызова IEnumerator.MoveNext), следующий текст кода итератора возобновляется после предыдущей yield return инструкции. Затем он продолжается до следующего yield return оператора до конца текста итератора или до тех пор yield break , пока не будет обнаружен оператор.

Итераторы не поддерживают метод IEnumerator.Reset. Чтобы повторить с самого начала, необходимо получить новый итератор. Вызов Reset итератора, возвращаемого методом итератора, вызывает NotSupportedExceptionисключение.

Дополнительные сведения см. в спецификации языка C#.

Использование итераторов

Итераторы позволяют поддерживать простоту foreach цикла, если необходимо использовать сложный код для заполнения последовательности списков. Это может быть полезно, если вы хотите сделать следующее:

• Измените последовательность списков после первой foreach итерации цикла.

• Избегайте полной загрузки большого foreach списка перед первой итерацией цикла. Примером является постраничная выборка для пакетной загрузки строк таблицы. Другим примером EnumerateFiles является метод, реализующий итераторы в .NET.

• Инкапсулируйте процесс создания списка в итераторе. В методе итератора можно создать список, а затем получить каждый результат в цикле.

См. также

• System.Collections.Generic
• IEnumerable<T>
• foreach в
• Обобщения