C# IEnumerator, IEnumerable, and Yield

這篇是因為工作上同事對於 yield return 的疑問，所以開始寫這篇文章，順便整理一下自己的經驗並且複習。

Iterator Pattern

在開始之前，稍稍提及迭代設計模式（Iterator Pattern），此模式目的是提供一組介面，能夠有順序得存取聚合物件（Aggregate objects）裡的元素（Elements），而不用知道該聚合物件的內部內容。聚合物件例如常使用的 Array 或是 List。

在 Net Framework 中，已經為此設計模式定義好介面（Interface）：IEnumerator 存取元素的迭代器，以及 IEnumerable 產生該迭代器。

更多關於 Iterator Pattern 可以參考 Reference 的連結或是書籍。

IEnumerator

IEnumerator，迭代器，是一個巡迴容器（聚合物件）的介面：

// namespace System.Collections
public interface IEnumerator
{
   object Current { get; }
   bool MoveNext();
   void Reset();
}

使用方法很簡單，在一個迴圈中呼叫 MoveNext，檢查是否還有可列舉的元素，利用 Current 來取得目前的元素：

for (var itr = something.GetEnumerator(); itr.MoveNext(); )
{
   Console.Write(itr.Current);
}

此外有泛型（Generic）的迭代器 IEnumerator，需多實做用於釋放資源的 Dispose 的介面：

// namespace System.Collections.Generic
using System.Collections;

public interface IEnumerator<T> : IDisposable, IEnumerator
{
   T Current { get; }
   bool MoveNext();
   void Reset();
   void Dispose();
}

使用上，建議在列舉完元素後，呼叫 Dispose 來釋放迭代器的資源，可以使用 using 使得程式碼更易讀：

using (var itr = something.GetEnumerator())
{
   while (itr.MoveNext())
   {
      Console.Write(itr.Current);
   }
}

IEnumerable

IEnumerable，提供一個取得迭代器方法，用該迭代器來列舉元素：

// namespace System.Collections
public interface IEnumerable
{
   IEnumerator GetEnumerator();
}

另有定義較常使用的泛型的版本：

// namespace System.Collections.Generic
using System.Collections;

public interface IEnumerable<T> : IEnumerable
{
   IEnumerator GetEnumerator<T>();
}

在 C# 中，陣列 (Array) 以及大多的容器 (System.Collections 或是 System.Collections.Generic) 都有實做 IEnumerable 介面，意思是可以透過 GetEnumerator() 來列舉該容器中的元素。例如 List、int[] 或是 string，都可以使用其迭代器來列舉容器中的元素。

以下是使用 C# 語法 foreach 來列舉 List 容器中的元素：

List<int> numbers = new List<int> { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 };
foreach (var number in numbers)
{
   Console.Write(number);  // Output: 0123456789
}

該 foreach 在編譯實作上，使用 IEnumerable 來取得 IEnumerator，透過迭代器列舉元素，可轉換程式碼如下：

List<int> numbers = new List<int> { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 };
using(var itr = numbers.GetEnumerator())
{
   while (itr.MoveNext())
   {
      var number = itr.Current;
      Console.Write(number);  // Output: 0123456789
   }
}

也可以自訂不同的迭代器，來製作出自定的列舉方法，例如下面定義對於 List 容器的 Reverse 迭代器，將元素順序反轉輸出：

struct ReverseListEnumerable<T> : IEnumerable<T>
{
   List<T> data;

   public ReverseListEnumerable(List<T> data)
   {
      this.data = data;
   }

   public IEnumerator<T> GetEnumerator()
   {
      return new Enumerator(this.data);
   }

   IEnumerator IEnumerable.GetEnumerator()
   {
      return this.GetEnumerator();
   }

   struct Enumerator : IEnumerator<T>
   {
      int index;
      List<T> data;

      public Enumerator(List<T> data)
      {
         this.data = data;
         this.index = data.Count;
      }

      public T Current
      {
         get
         {
            return this.data[this.index];
         }
      }

      object IEnumerator.Current
      {
         get
         {
            return this.Current;
         }
      }

      public void Dispose()
      {
         // 這裡把 data 設定 null，當作釋放資源，之後就無法再使用
         this.data = null;
      }

      public bool MoveNext()
      {
         this.index -= 1;
         return this.index >= 0;
      }

      public void Reset()
      {
         // 重置 Index
         this.index = this.data.Count;
      }
   }
}

List<int> numbers = new List<int> { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 };
foreach(var number in new ReverseListEnumerable<int>(numbers))
{
   Console.Write(number);   // Output: 9876543210
}

沒錯！自定義迭代器怎麼可以這麼又臭又長…，但 C# 提供一項語法，可以讓上述自定義迭代器的程式碼，變得相當容易撰寫又好閱讀，那就是 yield。

Yield

上節的 Reverse 例子使用 yield 可以改成：

IEnumerable<T> ReverseListEnumerable<T>(List<T> data)
{
   for (var index = data.Count - 1; index >= 0; index--)
   {
      yield return data[index];
   }
}

List<int> numbers = new List<int> { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 };
foreach(var number in ReverseListEnumerable(numbers))
{
   Console.Write(number);   // Output: 9876543210
}

沒有搞錯，就是如此簡單明瞭，C# 編譯器會把它處理成上節的那一個樣子，如果有興趣可以參考 Reference 的文章連結 The implementation of iterators in C# and its consequences。

當第一次呼叫迭代器的 MoveNext 時，程式會一直執行，直到 yield return，此時 yield return 的元素回傳，並保留程式位置以及狀態，當下一次呼叫 MoveNext() 時，會從該保留位置以及狀態繼續執行。

此外也可以使用 yield break 強制中斷迭代器列舉。下面例子，當列舉元素為 3 的倍數時就中斷迭代：

IEnumerable<int> MyEnumerable(IEnumerable<int> enumerable)
{
   foreach (var itr in enumerable)
   {
      if (itr % 3 == 0)
      {
         yield break;
      }

      yield return itr;
   }
}

List<int> numbers = new List<int> { 1, 2, 3, 4, 5, 6, 7, 8, 9 };
foreach(var number in MyEnumerable(numbers))
{
   Console.Write(number);   // Output: 12
}

延伸閱讀 System.Linq

前兩節中，範例實做 List 容器中 Reverse 迭代器，這功能在 System.Linq 中已經有所實做。System.Linq 提供許多對於 IEnumerable 物件的迭代器處理擴充，有哪些可以使用，可以參考官方文件。以下是使用 System.Linq 來完成 Reverse 功能：

using System.Collections.Generic;
using System.Linq;

List numbers = new List { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 };
foreach(var number in numbers.Reverse())
{
   Console.Write(number);  // Output: 9876543210
}