C# Reference ยท Collections
The IEnumerator<T> interface
Reference for C# IEnumerator<T>: how MoveNext, Current and Dispose work, how foreach uses them, writing your own enumerator and struct enumerators.
An enumerator is the cursor that walks through a sequence. IEnumerator<T> (namespace System.Collections.Generic) has a Current property for the item under the cursor and a MoveNext() method that advances to the next one and returns false when there are no more. It also implements IDisposable, so it can release resources when the loop ends.
Normally you never touch an enumerator: foreach creates one from GetEnumerator(), calls MoveNext() repeatedly, reads Current and disposes it. You use one directly when you need to peek ahead, walk two sequences in step, or process the first element differently without a flag variable.
using IEnumerator<int> e = new List<int> { 10, 20 }.GetEnumerator(); while (e.MoveNext()) { Console.WriteLine(e.Current); }
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Syntax
public interface IEnumerator<out T> : IEnumerator, IDisposable { T Current { get; } } public interface IEnumerator { object? Current { get; } bool MoveNext(); void Reset(); }
| Member | Description |
|---|---|
MoveNext() |
Advances the cursor. Returns true if it landed on an element, false when the sequence is finished. |
Current |
The element at the cursor. Only valid after MoveNext() returned true. |
Reset() |
Intended to rewind. Many enumerators, including those from iterator methods, throw NotSupportedException. |
Dispose() |
Releases resources; foreach calls it for you, also when the loop exits early. |
Returns: MoveNext() is false at the end and keeps returning false afterwards.
Errors: InvalidOperationException from MoveNext() when the source collection was modified after the enumerator was created (versioned collections such as List<T> and Dictionary<K,V>). Reading Current before the first MoveNext() or after the end is undefined: it usually returns default, but custom types may throw.
Usage notes
- The cursor starts before the first element. Always call
MoveNext()first. Forgetting this is the classic off-by-one when writing manual loops. - Dispose it. Use
using(orforeach) so iteratorfinallyblocks run and resources such as file handles are released. - Struct enumerators and boxing.
List<T>.Enumeratoris a struct. Storing it in avarand callingMoveNext()on areadonlyfield copies it and may appear to loop forever. Do not keep mutable struct enumerators inreadonlyfields. - Implementing by hand is rarely needed. An iterator method with
yield returngenerates a correctIEnumerator<T>for you, includingDisposehandling. - One cursor per enumerator. Two
foreachloops over the same list use two enumerators and do not interfere, unless the data changes. - Not thread-safe. Do not share one enumerator between threads.
- Non-generic
IEnumeratorexists for old APIs and returnsobject?; the genericCurrenthides it, which is why custom types implement both explicitly.