Iteradores (C#)Iterators (C#)

Um iterador pode ser usado para percorrer coleções, como listas e matrizes.An iterator can be used to step through collections such as lists and arrays.

Um método iterador ou um acessador get realiza uma iteração personalizada em uma coleção.An iterator method or get accessor performs a custom iteration over a collection. Um método iterador usa a instrução yield return para retornar um elemento de cada vez.An iterator method uses the yield return statement to return each element one at a time. Quando uma instrução yield return for atingida, o local atual no código será lembrado.When a yield return statement is reached, the current location in code is remembered. A execução será reiniciada desse local na próxima vez que a função iteradora for chamada.Execution is restarted from that location the next time the iterator function is called.

Um iterador é consumido no código cliente, usando uma instrução foreach ou usando uma consulta LINQ.You consume an iterator from client code by using a foreach statement or by using a LINQ query.

No exemplo a seguir, a primeira iteração do loop foreach faz a execução continue no método iterador SomeNumbers até que a primeira instrução yield return seja alcançada.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. Essa iteração retorna um valor de 3 e o local atual no método iterador é mantido.This iteration returns a value of 3, and the current location in the iterator method is retained. Na próxima iteração do loop, a execução no método iterador continuará de onde parou, parando novamente quando alcançar uma instrução 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. Essa iteração retorna um valor de 5 e o local atual no método iterador é mantido novamente.This iteration returns a value of 5, and the current location in the iterator method is again retained. O loop terminará quando o final do método iterador for alcançado.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;  
}  

O tipo de retorno de um método iterador ou acessador get pode ser 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>.

Você pode usar uma instrução yield break para terminar a iteração.You can use a yield break statement to end the iteration.

Os iteradores foram introduzidos no C# no Visual Studio 2005.Iterators were introduced in C# in Visual Studio 2005.

Neste tópicoIn this topic

Observação

Todos os exemplos neste tópico, exceto o exemplo Iterador Simples, incluem diretivas using para os namespaces System.Collections e 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.

Iterador simplesSimple Iterator

O exemplo a seguir contém uma única instrução yield return que está dentro de um loop for.The following example has a single yield return statement that is inside a for loop. Em Main, cada iteração do corpo da instrução foreach cria uma chamada à função iteradora, que avança para a próxima instrução yield return.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;  
        }  
    }  
}  

Criando uma classe de coleçãoCreating a Collection Class

No exemplo a seguir, a classe DaysOfTheWeek implementa a interface IEnumerable, que requer um método GetEnumerator.In the following example, the DaysOfTheWeek class implements the IEnumerable interface, which requires a GetEnumerator method. O compilador chama implicitamente o método GetEnumerator, que retorna um IEnumerator.The compiler implicitly calls the GetEnumerator method, which returns an IEnumerator.

O método GetEnumerator retorna cada cadeia de caracteres, uma de cada vez, usando a instrução 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];  
        }  
    }  
}  

O exemplo a seguir cria uma classe Zoo que contém uma coleção de animais.The following example creates a Zoo class that contains a collection of animals.

A instrução foreach, que faz referência à instância de classe (theZoo), chama implicitamente o método GetEnumerator.The foreach statement that refers to the class instance (theZoo) implicitly calls the GetEnumerator method. As instruções foreach, que fazem referência às propriedades Birds e Mammals, usam o método iterador nomeado 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; }  
    }  
}  

Usando iteradores com uma lista genéricaUsing Iterators with a Generic List

No exemplo a seguir, a classe Stack(Of T) genérica implementa a interface genérica IEnumerable<T>.In the following example, the Stack(Of T) generic class implements the IEnumerable<T> generic interface. O método Push atribui valores a uma matriz do tipo T.The Push method assigns values to an array of type T. O método GetEnumerator retorna os valores da matriz usando a instrução yield return.The GetEnumerator method returns the array values by using the yield return statement.

Além do método GetEnumerator genérico, o método GetEnumerator não genérico também deve ser implementado.In addition to the generic GetEnumerator method, the non-generic GetEnumerator method must also be implemented. Isso ocorre porque IEnumerable<T> herda de IEnumerable.This is because IEnumerable<T> inherits from IEnumerable. A implementação não genérica adia a implementação genérica.The non-generic implementation defers to the generic implementation.

O exemplo usa iteradores nomeados para dar suporte a várias maneiras de iterar na mesma coleção de dados.The example uses named iterators to support various ways of iterating through the same collection of data. Esses iteradores nomeados são as propriedades TopToBottom e BottomToTop e o método TopN.These named iterators are the TopToBottom and BottomToTop properties, and the TopN method.

A propriedade BottomToTop usa um iterador em um acessador 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];  
        }  
    }  

}  

Informações de sintaxeSyntax Information

Um iterador pode ocorrer como um método ou como um acessador get.An iterator can occur as a method or get accessor. Um iterador não pode ocorrer em um evento, um construtor de instância, um construtor estático ou um finalizador estático.An iterator cannot occur in an event, instance constructor, static constructor, or static finalizer.

Deve existir uma conversão implícita do tipo de expressão na instrução yield return, para o tipo de retorno do iterador.An implicit conversion must exist from the expression type in the yield return statement to the return type of the iterator.

Em C#, um método iterador não pode ter os parâmetros in, ref nem out.In C#, an iterator method cannot have any in, ref, or out parameters.

No C#, a "yield" não é uma palavra reservada e, só terá um significado especial, quando for usada antes de uma palavra-chave 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.

Implementação técnicaTechnical Implementation

Embora você escreva um iterador como um método, o compilador o traduz em uma classe aninhada que é, na verdade, uma máquina de estado.Although you write an iterator as a method, the compiler translates it into a nested class that is, in effect, a state machine. Essa classe mantém o controle da posição do iterador enquanto o loop foreach no código cliente continuar.This class keeps track of the position of the iterator as long the foreach loop in the client code continues.

Para ver o que o compilador faz, você pode usar a ferramenta Ildasm.exe para exibir o código Microsoft Intermediate Language que é gerado para um método iterador.To see what the compiler does, you can use the Ildasm.exe tool to view the Microsoft intermediate language code that is generated for an iterator method.

Quando você cria um iterador para uma classe ou struct, não é necessário implementar toda a interface IEnumerator.When you create an iterator for a class or struct, you don't have to implement the whole IEnumerator interface. Quando o compilador detecta o iterador, ele gera automaticamente os métodos Current, MoveNext e Dispose da 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.

A cada iteração sucessiva do loop foreach (ou a chamada direta ao IEnumerator.MoveNext), o próximo corpo de código do iterador continua, depois da instrução yield return anterior.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. Em seguida, ele continuará até a próxima instrução yield return, até que o final do corpo do iterador seja alcançado ou até que uma instrução yield break seja encontrada.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.

Iteradores não dão suporte ao método IEnumerator.Reset.Iterators don't support the IEnumerator.Reset method. Para iterar novamente desde o início, você deve obter um novo iterador.To re-iterate from the start, you must obtain a new iterator.

Para obter informações adicionais, consulte a Especificação da linguagem C#.For additional information, see the C# Language Specification.

Uso de iteradoresUse of Iterators

Os iteradores permitem que você mantenha a simplicidade de um loop foreach quando for necessário usar um código complexo para preencher uma sequência de lista.Iterators enable you to maintain the simplicity of a foreach loop when you need to use complex code to populate a list sequence. Isso pode ser útil quando você quiser fazer o seguinte:This can be useful when you want to do the following:

  • Modificar a sequência de lista após a primeira iteração de loop foreach.Modify the list sequence after the first foreach loop iteration.

  • Evitar o carregamento completo de uma grande lista antes da primeira iteração de um loop foreach.Avoid fully loading a large list before the first iteration of a foreach loop. Um exemplo é uma busca paginada para carregar um lote de linhas da tabela.An example is a paged fetch to load a batch of table rows. Outro exemplo é o método EnumerateFiles, que implementa os iteradores dentro do .NET Framework.Another example is the EnumerateFiles method, which implements iterators within the .NET Framework.

  • Encapsular a criação da lista no iterador.Encapsulate building the list in the iterator. No método iterador, você pode criar a lista e, em seguida, gerar cada resultado em um loop.In the iterator method, you can build the list and then yield each result in a loop.

Consulte tambémSee Also

System.Collections.Generic
IEnumerable<T>
foreach, inforeach, in
yieldyield
Usando foreach com matrizesUsing foreach with Arrays
GenéricosGenerics