Skip to content
Tutorials Center
My learning

Topics

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.

C#
using IEnumerator<int> e = new List<int> { 10, 20 }.GetEnumerator();
while (e.MoveNext())
{
    Console.WriteLine(e.Current);
}

Try it

C# Driving an enumerator by hand

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.

C# Writing your own enumerator

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

C#
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 (or foreach) so iterator finally blocks run and resources such as file handles are released.
  • Struct enumerators and boxing. List<T>.Enumerator is a struct. Storing it in a var and calling MoveNext() on a readonly field copies it and may appear to loop forever. Do not keep mutable struct enumerators in readonly fields.
  • Implementing by hand is rarely needed. An iterator method with yield return generates a correct IEnumerator<T> for you, including Dispose handling.
  • One cursor per enumerator. Two foreach loops 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 IEnumerator exists for old APIs and returns object?; the generic Current hides it, which is why custom types implement both explicitly.