Iteradores (C#)Iterators (C#)

Un iterador puede usarse para recorrer colecciones como listas y matrices.An iterator can be used to step through collections such as lists and arrays.

Un método iterador o un descriptor de acceso get realiza una iteración personalizada en una colección.An iterator method or get accessor performs a custom iteration over a collection. Un iterador usa la instrucción yield return para devolver cada elemento de uno en uno.An iterator method uses the yield return statement to return each element one at a time. Cuando se alcanza una instrucción yield return, se recuerda la ubicación actual en el código.When a yield return statement is reached, the current location in code is remembered. La ejecución se reinicia desde esa ubicación la próxima vez que se llama a la función del iterador.Execution is restarted from that location the next time the iterator function is called.

Para consumir un método iterador desde código de cliente, use una instrucción foreach o una consulta de LINQ.You consume an iterator from client code by using a foreach statement or by using a LINQ query.

En el ejemplo siguiente, la primera iteración del bucle foreach hace que continúe la ejecución del método de iterador SomeNumbers hasta que se alcance la primera instrucción yield return.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. Esta iteración devuelve un valor de 3, y la ubicación actual del método de iterador se conserva.This iteration returns a value of 3, and the current location in the iterator method is retained. En la siguiente iteración del bucle, la ejecución del método iterador continúa desde donde se dejó, deteniéndose de nuevo al alcanzar una instrucción 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. Esta iteración devuelve un valor de 5, y la ubicación actual del método de iterador se vuelve a conservar.This iteration returns a value of 5, and the current location in the iterator method is again retained. El bucle se completa al alcanzar el final del método iterador.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;
}

El tipo de valor devuelto de un método de iterador o descriptor de acceso get puede ser IEnumerable, IEnumerable<T>, IEnumerator o IEnumerator<T>.The return type of an iterator method or get accessor can be IEnumerable, IEnumerable<T>, IEnumerator, or IEnumerator<T>.

Puede usar una instrucción yield break para finalizar la iteración.You can use a yield break statement to end the iteration.

Nota

En todos los ejemplos de este tema, excepto en el ejemplo de iterador simple, incluya directivas using para los espacios de nombres System.Collections y 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 simpleSimple Iterator

El ejemplo siguiente tiene una única instrucción yield return que está dentro de un bucle for.The following example has a single yield return statement that is inside a for loop. En Main, cada iteración del cuerpo de la instrucción foreach crea una llamada a la función de iterador, que continúa a la instrucción yield return siguiente.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;
        }
    }
}

Creación de una clase de colecciónCreating a Collection Class

En el ejemplo siguiente, la clase DaysOfTheWeek implementa la interfaz IEnumerable, que requiere un método GetEnumerator.In the following example, the DaysOfTheWeek class implements the IEnumerable interface, which requires a GetEnumerator method. El compilador llama implícitamente al método GetEnumerator, que devuelve un IEnumerator.The compiler implicitly calls the GetEnumerator method, which returns an IEnumerator.

El método GetEnumerator devuelve las cadenas de una en una mediante la instrucción 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];
        }
    }
}

En el ejemplo siguiente se crea una clase Zoo que contiene una colección de animales.The following example creates a Zoo class that contains a collection of animals.

La instrucción foreach que hace referencia a la instancia de clase (theZoo) llama implícitamente al método GetEnumerator.The foreach statement that refers to the class instance (theZoo) implicitly calls the GetEnumerator method. Las instrucciones foreach que hacen referencia a las propiedades Birds y Mammals usan el método iterador con el nombre 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; }
    }
}

Uso de iteradores con una lista genéricaUsing Iterators with a Generic List

En el ejemplo siguiente, la clase genérica Stack<T> implementa la interfaz genérica IEnumerable<T>.In the following example, the Stack<T> generic class implements the IEnumerable<T> generic interface. El método Push asigna valores a una matriz de tipo T.The Push method assigns values to an array of type T. El método GetEnumerator devuelve los valores de la matriz con la instrucción yield return.The GetEnumerator method returns the array values by using the yield return statement.

Además del método GetEnumerator genérico, el método GetEnumerator no genérico también debe implementarse.In addition to the generic GetEnumerator method, the non-generic GetEnumerator method must also be implemented. Esto es porque IEnumerable<T> se hereda de IEnumerable.This is because IEnumerable<T> inherits from IEnumerable. La implementación no genérica aplaza la implementación genérica.The non-generic implementation defers to the generic implementation.

El ejemplo usa iteradores con nombre para admitir distintas formas de recorrer en iteración la misma colección de datos.The example uses named iterators to support various ways of iterating through the same collection of data. Estos iteradores con nombre son las propiedades TopToBottom y BottomToTop, y el método TopN.These named iterators are the TopToBottom and BottomToTop properties, and the TopN method.

La propiedad BottomToTop usa un iterador en un descriptor de acceso 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];
        }
    }

}

Información sobre la sintaxisSyntax Information

Un iterador se puede producir como un método o como un descriptor de acceso get.An iterator can occur as a method or get accessor. Un iterador no puede aparecer en un evento, un constructor de instancia, un constructor estático o un finalizador estático.An iterator cannot occur in an event, instance constructor, static constructor, or static finalizer.

Debe existir una conversión implícita del tipo de expresión en la instrucción yield return al argumento de tipo para el IEnumerable<T> devuelto por el iterador.An implicit conversion must exist from the expression type in the yield return statement to the type argument for the IEnumerable<T> returned by the iterator.

En C#, un método iterador no puede tener ningún parámetro in, ref o out.In C#, an iterator method cannot have any in, ref, or out parameters.

En C#, "yield" no es una palabra reservada y solo tiene un significado especial cuando se usa antes de una palabra clave return o break.In C#, "yield" is not a reserved word and has special meaning only when it is used before a return or break keyword.

Implementación técnicaTechnical Implementation

Aunque un iterador se escribe como un método, el compilador lo traduce a una clase anidada que es, en realidad, una máquina de estados.Although you write an iterator as a method, the compiler translates it into a nested class that is, in effect, a state machine. Esta clase realiza el seguimiento de la posición del iterador mientras el bucle foreach continúe en el código de cliente.This class keeps track of the position of the iterator as long the foreach loop in the client code continues.

Para ver lo que hace el compilador, puede usar la herramienta Ildasm.exe para ver el código de lenguaje intermedio de Microsoft que se genera para un método de iterador.To see what the compiler does, you can use the Ildasm.exe tool to view the Microsoft intermediate language code that's generated for an iterator method.

Cuando crea un iterador para una clase o struct, no necesita implementar la interfaz IEnumerator completa.When you create an iterator for a class or struct, you don't have to implement the whole IEnumerator interface. Cuando el compilador detecta el iterador, genera automáticamente los métodos Current, MoveNext y Dispose de la interfaz IEnumerator o IEnumerator<T>.When the compiler detects the iterator, it automatically generates the Current, MoveNext, and Dispose methods of the IEnumerator or IEnumerator<T> interface.

En cada iteración sucesiva del bucle foreach (o la llamada directa a IEnumerator.MoveNext), el cuerpo de código del iterador siguiente se reanuda después de la instrucción 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. Después continúa con la siguiente instrucción yield return hasta que se alcanza el final del cuerpo del iterador, o hasta que se encuentra una instrucción yield break.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.

Los iteradores no admiten el método IEnumerator.Reset.Iterators don't support the IEnumerator.Reset method. Para volver a recorrer en iteración desde el principio, se debe obtener un nuevo iterador.To reiterate from the start, you must obtain a new iterator. Una llamada a Reset en el iterador devuelto por un método de iterador inicia una excepción NotSupportedException.Calling Reset on the iterator returned by an iterator method throws a NotSupportedException.

Para obtener más información, vea la Especificación del lenguaje C#.For additional information, see the C# Language Specification.

Uso de iteradoresUse of Iterators

Los iteradores permiten mantener la simplicidad de un bucle foreach cuando se necesita usar código complejo para rellenar una secuencia 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. Esto puede ser útil si quiere hacer lo siguiente:This can be useful when you want to do the following:

  • Modificar la secuencia de lista después de la primera iteración del bucle foreach.Modify the list sequence after the first foreach loop iteration.

  • Evitar que se cargue totalmente una lista grande antes de la primera iteración de un bucle foreach.Avoid fully loading a large list before the first iteration of a foreach loop. Un ejemplo es una búsqueda paginada para cargar un lote de filas de tabla.An example is a paged fetch to load a batch of table rows. Otro ejemplo es el método EnumerateFiles, que implementa iteradores en .NET Framework.Another example is the EnumerateFiles method, which implements iterators within the .NET Framework.

  • Encapsular la creación de la lista en el iterador.Encapsulate building the list in the iterator. En el método iterador, puede crear la lista y después devolver cada resultado en un bucle.In the iterator method, you can build the list and then yield each result in a loop.

Vea tambiénSee also