Yineleyiciler (C#)Iterators (C#)

Listeler ve diziler gibi koleksiyonlarda adım atmak için bir yineleyici kullanılabilir.An iterator can be used to step through collections such as lists and arrays.

Bir yineleyici yöntemi get veya erişimcisi bir koleksiyon üzerinde özel bir yineleme gerçekleştirir.An iterator method or get accessor performs a custom iteration over a collection. Yineleyici yöntemi, her öğeyi birer birer döndürmek için verim iade deyimini kullanır.An iterator method uses the yield return statement to return each element one at a time. Bir yield return bildirime ulaşıldığında, koddaki geçerli konum hatırlanır.When a yield return statement is reached, the current location in code is remembered. Yürütme, yineleyici işlevi bir sonraki çağrıldığında bu konumdan yeniden başlatılır.Execution is restarted from that location the next time the iterator function is called.

Her bir forher deyimi kullanarak veya bir LINQ sorgusu kullanarak istemci kodundan bir yineleyici tüketirsiniz.You consume an iterator from client code by using a foreach statement or by using a LINQ query.

Aşağıdaki örnekte, döngünün ilk yinelemesi, ilk foreach SomeNumbers yield return ifadeye ulaşılına kadar yürütmenin yineleyici yönteminde ilerlemesine neden olur.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. Bu yineleme 3 değerini döndürür ve yineleyici yöntemindeki geçerli konum korunur.This iteration returns a value of 3, and the current location in the iterator method is retained. Döngünün bir sonraki yinelemesinde, yineleyici yöntemindeki yürütme kaldığı yerden devam ediyor ve bir yield return bildirime ulaştığında yine durur.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. Bu yineleme 5 değerini döndürür ve yineleyici yöntemindeki geçerli konum yine korunur.This iteration returns a value of 5, and the current location in the iterator method is again retained. Yineleme yönteminin sonuna ulaşıldığında döngü tamamlanır.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;
}

Bir yineleyici yönteminin get veya erişime neden IEnumerableolan IEnumerable<T> IEnumeratorbir IEnumerator<T>yöntemin dönüş türü , , , veya .The return type of an iterator method or get accessor can be IEnumerable, IEnumerable<T>, IEnumerator, or IEnumerator<T>.

Yinelemeyi sona yield break erdirmek için bir deyim kullanabilirsiniz.You can use a yield break statement to end the iteration.

Not

Basit Yineleme örneği dışındaki bu konuyla ilgili tüm using örnekler için, System.Collections yönergeler ve System.Collections.Generic ad alanları için kullanma içerir.For all examples in this topic except the Simple Iterator example, include using directives for the System.Collections and System.Collections.Generic namespaces.

Basit YinelemeSimple Iterator

Aşağıdaki örnekte yield return for döngüsü içinde tek bir ifade vardır.The following example has a single yield return statement that is inside a for loop. İfade Maingövdesinin foreach her yinelemesinde, bir sonraki yield return deyime devam eden yineleyici işlevine bir çağrı oluşturulur.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;
        }
    }
}

Koleksiyon Sınıfı OluşturmaCreating a Collection Class

Aşağıdaki örnekte, DaysOfTheWeek sınıf bir GetEnumerator IEnumerable yöntem gerektiren arabirimi uygular.In the following example, the DaysOfTheWeek class implements the IEnumerable interface, which requires a GetEnumerator method. Derleyici dolaylı olarak GetEnumerator yöntemi çağırır ve IEnumeratorbu yöntem bir .The compiler implicitly calls the GetEnumerator method, which returns an IEnumerator.

Yöntem GetEnumerator deyimi kullanarak yield return her dize yi birer birer döndürür.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];
        }
    }
}

Aşağıdaki örnek, bir Zoo hayvan koleksiyonu içeren bir sınıf oluşturur.The following example creates a Zoo class that contains a collection of animals.

Sınıf foreach örneğine başvuran ifadetheZoo( ) GetEnumerator dolaylı olarak yöntemi çağırır.The foreach statement that refers to the class instance (theZoo) implicitly calls the GetEnumerator method. Bu foreach Birds ifadeler ve Mammals özellikleri başvuran AnimalsForType adlandırılmış yineleyici yöntemini kullanın.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; }
    }
}

Genel Listeyle Yinelemeleri KullanmaUsing Iterators with a Generic List

Aşağıdaki örnekte, Stack<T> genel sınıf IEnumerable<T> genel arabirimi uygular.In the following example, the Stack<T> generic class implements the IEnumerable<T> generic interface. Yöntem, Push değerleri bir tür Tdizisine atar.The Push method assigns values to an array of type T. Yöntem GetEnumerator yield return deyimi kullanarak dizi değerlerini döndürür.The GetEnumerator method returns the array values by using the yield return statement.

Genel GetEnumerator yönteme ek olarak, genel GetEnumerator olmayan yöntem de uygulanmalıdır.In addition to the generic GetEnumerator method, the non-generic GetEnumerator method must also be implemented. Bunun nedeni, 'den IEnumerable<T> IEnumerablemiras olmasıdır.This is because IEnumerable<T> inherits from IEnumerable. Genel olmayan uygulama genel uygulamaya erteler.The non-generic implementation defers to the generic implementation.

Örnek, aynı veri toplama yoluyla yineleme çeşitli yollarını desteklemek için adlandırılmış yineleyiciler kullanır.The example uses named iterators to support various ways of iterating through the same collection of data. Bu adlandırılmış TopToBottom yineleyiciler BottomToTop ve özellikleri TopN ve yöntemi vardır.These named iterators are the TopToBottom and BottomToTop properties, and the TopN method.

Özellik, BottomToTop bir aksesuarda bir get yineleyici kullanır.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];
        }
    }

}

Sözdizimi BilgileriSyntax Information

Bir yineleyici bir yöntem veya get erişimci olarak oluşabilir.An iterator can occur as a method or get accessor. Bir olay, örnek oluşturucu, statik oluşturucu veya statik sonlandırıcı bir olay meydana gelemez.An iterator cannot occur in an event, instance constructor, static constructor, or static finalizer.

yield return Örtük bir dönüştürme, deyimdeki ifade türünden yineleyici IEnumerable<T> tarafından döndürülen tür bağımsız değişkenine kadar olmalıdır.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.

C#'da, bir yineleyici yöntemi, in refherhangi out bir , veya parametre olamaz.In C#, an iterator method cannot have any in, ref, or out parameters.

C#'da yield ayrılmış bir sözcük değildir ve yalnızca bir return veya break anahtar kelimeden önce kullanıldığında özel bir anlamı vardır.In C#, yield is not a reserved word and has special meaning only when it is used before a return or break keyword.

Teknik UygulamaTechnical Implementation

Bir yöntem olarak bir yineleyici yazmanıza rağmen, derleyici bunu aslında bir durum makinesi olan iç içe geçmiş bir sınıfa çevirir.Although you write an iterator as a method, the compiler translates it into a nested class that is, in effect, a state machine. Bu sınıf, istemci kodundaki foreach döngü devam ettikçe yineleyicinin konumunu izler.This class keeps track of the position of the iterator as long the foreach loop in the client code continues.

Derleyicinin ne yaptığını görmek için, yineleyici yöntemi için oluşturulan Microsoft ara dil kodunu görüntülemek için Ildasm.exe aracını kullanabilirsiniz.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.

Bir sınıf veya yapıiçin bir yineleyici oluşturduğunuzda, tüm IEnumerator arabirimi uygulamanız gerekmez.When you create an iterator for a class or struct, you don't have to implement the whole IEnumerator interface. Derleyici yineleyiciyi algıladığında, otomatik Currentolarak , ve MoveNext Dispose yöntemleri veya IEnumerator arabirimi IEnumerator<T> oluşturur.When the compiler detects the iterator, it automatically generates the Current, MoveNext, and Dispose methods of the IEnumerator or IEnumerator<T> interface.

Döngünün (veya doğrudan foreach çağrının) birbirini izleyen IEnumerator.MoveNexther yinelemesinde, bir sonraki yineleyici yield return kodu gövdesi önceki deyimden sonra devam eder.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. Daha sonra, yineleme yield return gövdesinin sonuna ulaşılınceye veya bir ifadeyle yield break karşılaşına kadar bir sonraki ifadeye devam edilir.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.

Yineleyiciler IEnumerator.Reset yöntemi desteklemez.Iterators don't support the IEnumerator.Reset method. Baştan yinelemek için, yeni bir yineleyici edinmeniz gerekir.To reiterate from the start, you must obtain a new iterator. Bir Reset yineleyici yöntemi yle döndürülen yineleyiciyi çağırmak NotSupportedExceptionbir .Calling Reset on the iterator returned by an iterator method throws a NotSupportedException.

Daha fazla bilgi için C# Dil Belirtimi'nebakın.For additional information, see the C# Language Specification.

Yinelemelerin KullanımıUse of Iterators

Yineleyiciler, liste sırasını doldurmak için foreach karmaşık kod kullanmanız gerektiğinde döngünün basitliğini korumanızı sağlar.Iterators enable you to maintain the simplicity of a foreach loop when you need to use complex code to populate a list sequence. Aşağıdakileri yapmak istediğinizde bu yararlı olabilir:This can be useful when you want to do the following:

  • İlk foreach döngü yinelemeden sonra liste sırasını değiştirin.Modify the list sequence after the first foreach loop iteration.

  • Bir foreach döngünün ilk yinelemesinden önce büyük bir listeyi tam olarak yüklemekten kaçının.Avoid fully loading a large list before the first iteration of a foreach loop. Bir örnek, bir tablo satırı toplu yüklemek için çağrılı getir.An example is a paged fetch to load a batch of table rows. Başka bir EnumerateFiles örnek, .NET Çerçevesi içinde yineleyicileri uygulayan yöntemdir.Another example is the EnumerateFiles method, which implements iterators within the .NET Framework.

  • Listeyi yineleyicide oluşturmayı kapsüller.Encapsulate building the list in the iterator. Yineleyici yönteminde, listeyi oluşturabilir ve sonra her sonucu bir döngüde verebilirsiniz.In the iterator method, you can build the list and then yield each result in a loop.

Ayrıca bkz.See also