Итераторы (C# и Visual Basic)

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

Метод итератора или метод доступа get выполняет настраиваемый проход по коллекции. Метод итератора использует оператор C# Yield (Visual Basic) или yield return для поочередного возврата каждого элемента. При достижении оператора Yield или yield return текущее расположение в коде запоминается. При следующем вызове функции итератора выполнение возобновляется с того места.

Используется итератор из клиентского кода с помощью выписки For Each… Next (Visual Basic) или foreach (C-#) или с помощью запроса LINQ.

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

Sub Main()
    For Each number As Integer In SomeNumbers()
        Console.Write(number & " ")
    Next 
    ' Output: 3 5 8
    Console.ReadKey()
End Sub 

Private Iterator Function SomeNumbers() As System.Collections.IEnumerable
    Yield 3
    Yield 5
    Yield 8
End Function

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, IEnumerator или IEnumerator.

Можно использовать оператор C# Exit Function или Return (Visual Basic) или оператор yield break, чтобы завершить итерацию.

Функция итератора Visual Basic или объявление метода доступа get включает в себя модификатор Iterator.

Итераторы были введены в C# в Visual Studio 2005 и появились в Visual Basic в Visual Studio 2012.

Содержание раздела

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

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

• Блоки "Try" в Visual Basic

• Анонимные методы в Visual Basic

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

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

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

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

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

В следующем примере имеется один оператор Yield или выписку yield return, который находится внутри цикла С# For… Next (Visual Basic) или For. В Main каждая итерация оператора For Each или foreach создает вызов функции итератора, которая выполняет следующий оператор Yield или yield return.

Sub Main()
    For Each number As Integer In EvenSequence(5, 18)
        Console.Write(number & " ")
    Next 
    ' Output: 6 8 10 12 14 16 18
    Console.ReadKey()
End Sub 

Private Iterator Function EvenSequence(
ByVal firstNumber As Integer, ByVal lastNumber As Integer) _
As System.Collections.Generic.IEnumerable(Of Integer)

    ' Yield even numbers in the range. 
    For number As Integer = firstNumber To lastNumber
        If number Mod 2 = 0 Then
            Yield number
        End If 
    Next 
End Function

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

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

Примечание

Для остальных примеров в этом разделе добавьте операторы Imports (Visual Basic) или директивы C# using для пространств имен System.Collections и System.Collections.Generic.

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

Метод GetEnumerator возвращает каждую строку поочередно с помощью оператора Yield или yield return. В коде Visual Basic, модификатор Iterator находится в объявлении функции.

Sub Main()
    Dim days As New DaysOfTheWeek()
    For Each day As String In days
        Console.Write(day & " ")
    Next 
    ' Output: Sun Mon Tue Wed Thu Fri Sat
    Console.ReadKey()
End Sub 

Private Class DaysOfTheWeek
    Implements IEnumerable

    Public days =
        New String() {"Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"}

    Public Iterator Function GetEnumerator() As IEnumerator _
        Implements IEnumerable.GetEnumerator

        ' Yield each day of the week. 
        For i As Integer = 0 To days.Length - 1
            Yield days(i)
        Next 
    End Function 
End Class

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, содержащий коллекцию животных.

Оператор For Each или foreach, который обращается к экземпляру класса (theZoo), неявно вызывает метод GetEnumerator. Операторы For Each или foreach, которые обращаются к свойствам Birds и Mammals, используют метод итератора с именем AnimalsForType.

Sub Main()
    Dim theZoo As New Zoo()

    theZoo.AddMammal("Whale")
    theZoo.AddMammal("Rhinoceros")
    theZoo.AddBird("Penguin")
    theZoo.AddBird("Warbler")

    For Each name As String In theZoo
        Console.Write(name & " ")
    Next
    Console.WriteLine()
    ' Output: Whale Rhinoceros Penguin Warbler 

    For Each name As String In theZoo.Birds
        Console.Write(name & " ")
    Next
    Console.WriteLine()
    ' Output: Penguin Warbler 

    For Each name As String In theZoo.Mammals
        Console.Write(name & " ")
    Next
    Console.WriteLine()
    ' Output: Whale Rhinoceros

    Console.ReadKey()
End Sub 

Public Class Zoo
    Implements IEnumerable

    ' Private members. 
    Private animals As New List(Of Animal)

    ' Public methods. 
    Public Sub AddMammal(ByVal name As String)
        animals.Add(New Animal With {.Name = name, .Type = Animal.TypeEnum.Mammal})
    End Sub 

    Public Sub AddBird(ByVal name As String)
        animals.Add(New Animal With {.Name = name, .Type = Animal.TypeEnum.Bird})
    End Sub 

    Public Iterator Function GetEnumerator() As IEnumerator _
        Implements IEnumerable.GetEnumerator

        For Each theAnimal As Animal In animals
            Yield theAnimal.Name
        Next 
    End Function 

    ' Public members. 
    Public ReadOnly Property Mammals As IEnumerable
        Get 
            Return AnimalsForType(Animal.TypeEnum.Mammal)
        End Get 
    End Property 

    Public ReadOnly Property Birds As IEnumerable
        Get 
            Return AnimalsForType(Animal.TypeEnum.Bird)
        End Get 
    End Property 

    ' Private methods. 
    Private Iterator Function AnimalsForType( _
    ByVal type As Animal.TypeEnum) As IEnumerable
        For Each theAnimal As Animal In animals
            If (theAnimal.Type = type) Then
                Yield theAnimal.Name
            End If 
        Next 
    End Function 

    ' Private class. 
    Private Class Animal
        Public Enum TypeEnum
            Bird
            Mammal
        End Enum 

        Public Property Name As String 
        Public Property Type As TypeEnum
    End Class 
End Class

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

Блоки "Try" в Visual Basic

Visual Basic допускает оператор Yield в блоке Try Оператор Try... Catch... Finally (Visual Basic). Блок Try, имеющий оператор Yield, может содержать блоки Catch и блок Finally.

Примечание C#
C# допускает оператор yield return в блоке try оператора try-finally.Блок try, имеющий оператор yield return, не может иметь блоков catch.

В следующем примере Visual Basic в функции итератора содержится блок Try, Catch и Finally. Блок Finally в функции итератора выполняется перед завершением итерации For Each.

Sub Main()
    For Each number As Integer In Test()
        Console.WriteLine(number)
    Next
    Console.WriteLine("For Each is done.")

    ' Output: 
    '  3 
    '  4 
    '  Something happened. Yields are done. 
    '  Finally is called. 
    '  For Each is done.
    Console.ReadKey()
End Sub 

Private Iterator Function Test() As IEnumerable(Of Integer)
    Try
        Yield 3
        Yield 4
        Throw New Exception("Something happened. Yields are done.")
        Yield 5
        Yield 6
    Catch ex As Exception
        Console.WriteLine(ex.Message)
    Finally
        Console.WriteLine("Finally is called.")
    End Try 
End Function

Оператор Yield не может быть внутри блока Catch или блока Finally.

Если содержимое в For Each (вместо метода итератора) вызывает исключение, то блок Catch в функции итератора не выполняется, но выполняется блок Finally в функции итератора. Блок Catch внутри функции итератора перехватывает только исключения, происходящие внутри функции итератора.

Анонимные методы в Visual Basic

В Visual Basic (но не в C#) анонимная функция может быть функцией итератора. Это показано в приведенном ниже примере.

Dim iterateSequence = Iterator Function() _
                      As IEnumerable(Of Integer)
                          Yield 1
                          Yield 2
                      End Function 

For Each number As Integer In iterateSequence()
    Console.Write(number & " ")
Next 
' Output: 1 2
Console.ReadKey()

В следующем примере Visual Basic содержится метод не итератора, который проверяет аргументы. Метод возвращает результат анонимного итератора, который описывает элементы коллекции.

Sub Main()
    For Each number As Integer In GetSequence(5, 10)
        Console.Write(number & " ")
    Next 
    ' Output: 5 6 7 8 9 10
    Console.ReadKey()
End Sub 

Public Function GetSequence(ByVal low As Integer, ByVal high As Integer) _
As IEnumerable
    ' Validate the arguments. 
    If low < 1 Then 
        Throw New ArgumentException("low is too low")
    End If 
    If high > 140 Then 
        Throw New ArgumentException("high is too high")
    End If 

    ' Return an anonymous iterator function. 
    Dim iterateSequence = Iterator Function() As IEnumerable
                              For index = low To high
                                  Yield index
                              Next 
                          End Function 
    Return iterateSequence()
End Function

Если вместо этого проверка находится внутри функции итератора, то эту проверку невозможно выполнить до начала первой итерации For Each.

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

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

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

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

Свойство BottomToTop использует итератор в методе доступа get. В коде Visual Basic объявление свойства содержит ключевое слово Iterator.

Sub Main()
    Dim theStack As New Stack(Of Integer)

    ' Add items to the stack. 
    For number As Integer = 0 To 9
        theStack.Push(number)
    Next 

    ' Retrieve items from the stack. 
    ' For Each is allowed because theStack implements 
    ' IEnumerable(Of Integer). 
    For Each number As Integer In theStack
        Console.Write("{0} ", number)
    Next
    Console.WriteLine()
    ' Output: 9 8 7 6 5 4 3 2 1 0 

    ' For Each is allowed, because theStack.TopToBottom 
    ' returns IEnumerable(Of Integer). 
    For Each number As Integer In theStack.TopToBottom
        Console.Write("{0} ", number)
    Next
    Console.WriteLine()
    ' Output: 9 8 7 6 5 4 3 2 1 0 

    For Each number As Integer In theStack.BottomToTop
        Console.Write("{0} ", number)
    Next
    Console.WriteLine()
    ' Output: 0 1 2 3 4 5 6 7 8 9  

    For Each number As Integer In theStack.TopN(7)
        Console.Write("{0} ", number)
    Next
    Console.WriteLine()
    ' Output: 9 8 7 6 5 4 3

    Console.ReadKey()
End Sub 

Public Class Stack(Of T)
    Implements IEnumerable(Of T)

    Private values As T() = New T(99) {}
    Private top As Integer = 0

    Public Sub Push(ByVal t As T)
        values(top) = t
        top = top + 1
    End Sub 

    Public Function Pop() As T
        top = top - 1
        Return values(top)
    End Function 

    ' This function implements the GetEnumerator method. It allows 
    ' an instance of the class to be used in a For Each statement. 
    Public Iterator Function GetEnumerator() As IEnumerator(Of T) _
        Implements IEnumerable(Of T).GetEnumerator

        For index As Integer = top - 1 To 0 Step -1
            Yield values(index)
        Next 
    End Function 

    Public Iterator Function GetEnumerator1() As IEnumerator _
        Implements IEnumerable.GetEnumerator

        Yield GetEnumerator()
    End Function 

    Public ReadOnly Property TopToBottom() As IEnumerable(Of T)
        Get 
            Return Me 
        End Get 
    End Property 

    Public ReadOnly Iterator Property BottomToTop As IEnumerable(Of T)
        Get 
            For index As Integer = 0 To top - 1
                Yield values(index)
            Next 
        End Get 
    End Property 

    Public Iterator Function TopN(ByVal itemsFromTop As Integer) _
        As IEnumerable(Of T)

        ' Return less than itemsFromTop if necessary. 
        Dim startIndex As Integer =
            If(itemsFromTop >= top, 0, top - itemsFromTop)

        For index As Integer = top - 1 To startIndex Step -1
            Yield values(index)
        Next 
    End Function 
End Class

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. Итератор не может произойти в событии, конструкторе экземпляра, статическом конструкторе или статическом деструкторе.

Должно существовать неявное преобразование из выражения типа в операторе C# Yield (Visual Basic) или yield return к возвращаемому типу итератора.

В Visual Basic методы с модификатором Iterator не могут иметь параметры ByRef. В C# методы с модификатором Iterator не могут иметь параметры ref или out.

В Visual Basic "Yield" не является зарезервированным словом и имеет специальное значение, только если он используется в методе Iterator или методе доступа get. В C#, "yield" не является зарезервированным словом и имеет специальное значение, только если он используется перед ключевым словом return или break.

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

Хотя итератор создается как метод, компилятор переводит его во вложенный класс, который фактически является конечным автоматом. Данный класс отслеживает положения итератора, пока в клиентском коде выполняется цикл For Each...Next или foreach.

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

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

На каждой последовательной итерации цикла For Each…Next или foreach (или непосредственного вызова метода IEnumerator.MoveNext) код тела следующего итератора начинает выполнение после предыдущего оператора Yield или yield return. Затем он выполняется до следующего оператора Yield или yield return до тех пор, пока не будет достигнут конец тела итератора или пока не будет обнаружен оператор Visual Basic Exit Function или Return, или оператор C# yield break.

Итераторы не поддерживают метод IEnumerator.Reset. Для повторной итерации сначала необходимо получить новый итератор.

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

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

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

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

• Избежании полной загрузки большого списка перед первой итерацией цикла For Each. Например, постраничная загрузка пакета строк таблицы. Другой пример — метод EnumerateFiles, который реализует итераторы в платформе .NET Framework.

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

Следующие C# блоги содержат дополнительные сведения об использовании итераторов.

• Создание элегантного кода с использованием анонимных методов, итераторов и разделяемых классов

• Все об итераторах

• Настраиваемые итераторы

См. также

Ссылки

Оператор For Each... Next (Visual Basic)

foreach, in (Справочник по C#)

Оператор Yield (Visual Basic)

yield (справочник по C#)

Итератор (Visual Basic)

Использование оператора foreach с массивами (Руководство по программированию на C#)

Универсальные шаблоны (Руководство по программированию на C#)

System.Collections.Generic

IEnumerable