Iteradores (C#)
Um iterador pode ser usado para percorrer coleções como listas e matrizes.
Um método iterador ou get acessador executa uma iteração personalizada em uma coleção. Um método iterador usa a instrução yield return para retornar cada elemento, um de cada vez. Quando uma yield return instrução é alcançada, o local atual no código é lembrado. A execução é reiniciada a partir desse local na próxima vez que a função iterador for chamada.
Você consome um iterador do código do cliente usando uma instrução foreach ou usando uma consulta LINQ.
No exemplo a seguir, a primeira iteração do loop faz com que a foreachSomeNumbers execução prossiga no método iterator até que a primeira yield return instrução seja atingida. Essa iteração retorna um valor de 3 e o local atual no método iterador é mantido. Na próxima iteração do loop, a execução no método iterator continua de onde parou, parando novamente quando atinge uma yield return instrução. Essa iteração retorna um valor de 5 e o local atual no método iterador é novamente mantido. O loop é concluído quando o final do método iterador é atingido.
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 get acessador pode ser IEnumerable, IEnumerable<T>, IEnumerator, ou IEnumerator<T>.
Você pode usar uma yield break instrução para encerrar a iteração.
Nota
Para todos os exemplos neste tópico, exceto o exemplo do Iterador Simples, inclua o uso de diretivas para os System.Collections namespaces e System.Collections.Generic .
Iterador simples
O exemplo a seguir tem uma única yield return instrução que está dentro de um loop for . No Main, cada iteração do foreach corpo da instrução cria uma chamada para a função iterador, que prossegue para a próxima yield return instrução.
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ção
No exemplo a seguir, a DaysOfTheWeek classe implementa a IEnumerable interface, que requer um GetEnumerator método. O compilador chama implicitamente o GetEnumerator método, que retorna um IEnumeratorarquivo .
O GetEnumerator método retorna cada cadeia de caracteres, uma de cada vez, usando a yield return instrução.
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 Zoo classe que contém uma coleção de animais.
A foreach instrução que se refere à instância de classe (theZoo) chama implicitamente o GetEnumerator método. As foreach instruções que se referem às Birds propriedades e Mammals usam o AnimalsForType método iterador nomeado.
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érica
No exemplo a seguir, a Stack<T> classe generic implementa a IEnumerable<T> interface genérica. O Push método atribui valores a uma matriz do tipo T. O GetEnumerator método retorna os valores de matriz usando a yield return instrução.
Além do método genérico GetEnumerator , o método não genérico GetEnumerator também deve ser implementado. Isso ocorre porque IEnumerable<T> herda de IEnumerable. A implementação não genérica adia para a implementação genérica.
O exemplo usa iteradores nomeados para dar suporte a várias maneiras de iteração através da mesma coleção de dados. Esses iteradores nomeados são as propriedades e BottomToTop e TopToBottom o TopN método.
A BottomToTop propriedade usa um iterador em um get acessador.
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 sintaxe
Um iterador pode ocorrer como um método ou get acessador. Um iterador não pode ocorrer em um evento, construtor de instância, construtor estático ou finalizador estático.
Uma conversão implícita deve existir do tipo de expressão na yield return instrução para o argumento type para o IEnumerable<T> retornado pelo iterador.
Em C#, um método iterador não pode ter nenhum in, refou out parâmetros.
Em C#, yield não é uma palavra reservada e tem significado especial apenas quando é usada antes de uma return ou break palavra-chave.
Implementação Técnica
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. Essa classe mantém o controle da posição do iterador enquanto o foreach loop no código do cliente continua.
Para ver o que o compilador faz, você pode usar a ferramenta Ildasm.exe para exibir o código de linguagem intermediária comum que é gerado para um método iterador.
Quando você cria um iterador para uma classe ou struct, não é necessário implementar a interface inteira IEnumerator . Quando o compilador deteta o iterador, ele gera automaticamente o Current, MoveNexte Dispose métodos da IEnumerator interface ou IEnumerator<T> .
Em cada iteração sucessiva do loop (ou a chamada direta para IEnumerator.MoveNext), o próximo corpo de foreach código do iterador é retomado após a instrução anterioryield return. Em seguida, continua para a próxima yield return instrução até que o final do corpo iterador seja atingido, ou até que uma yield break instrução seja encontrada.
Os iteradores não suportam o IEnumerator.Reset método. Para reiterar desde o início, você deve obter um novo iterador. Chamar Reset o iterador retornado por um método iterador lança um NotSupportedException.
Para obter informações adicionais, consulte a Especificação da linguagem C#.
Uso de iteradores
Os iteradores permitem que você mantenha a simplicidade de um foreach loop quando precisar usar código complexo para preencher uma sequência de lista. Isso pode ser útil quando você deseja fazer o seguinte:
Modifique a sequência da lista após a primeira
foreachiteração de loop.Evite carregar totalmente uma lista grande antes da primeira iteração de um
foreachloop. Um exemplo é uma busca paginada para carregar um lote de linhas de tabela. Outro exemplo é o EnumerateFiles método, que implementa iteradores no .NET.Encapsular a criação da lista no iterador. No método iterator, você pode criar a lista e, em seguida, produzir cada resultado em um loop.
