System.Collections.IEnumerator Interface

Summary

Supports a simple iteration over a collection.

C# Syntax:

public interface IEnumerator

IEnumerator is the base interface for all enumerators.

Enumerators only allow reading the data in the collection. Enumerators cannot be used to modify the underlying collection.

Initially, the enumerator is positioned before the first element in the collection. IEnumerator.Reset also brings the enumerator back to this position. At this position, calling IEnumerator.Current throws an exception. Therefore, you must call IEnumerator.MoveNext to advance the enumerator to the first element of the collection before reading the value of IEnumerator.Current.

IEnumerator.Current returns the same object until either IEnumerator.MoveNext or IEnumerator.Reset is called. IEnumerator.MoveNext sets IEnumerator.Current to the next element.

After the end of the collection is passed, the enumerator is positioned after the last element in the collection, and calling IEnumerator.MoveNext returns false. If the last call to IEnumerator.MoveNext returned false, calling IEnumerator.Current throws an exception. To set IEnumerator.Current to the first element of the collection again, you can call IEnumerator.Reset followed by IEnumerator.MoveNext.

An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying or deleting elements, the enumerator is irrecoverably invalidated and the next call to IEnumerator.MoveNext or IEnumerator.Reset throws an InvalidOperationException. If the collection is modified between IEnumerator.MoveNext and IEnumerator.Current, IEnumerator.Current will return the element that it is set to, even if the enumerator is already invalidated.

The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads could still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads.

System.Collections Namespace | IEnumerable | ICollection

System.Collections.IEnumerator Member List:

Public Properties

Current

Read-only Gets the current element in the collection.

Public Methods

MoveNext	Advances the enumerator to the next element of the collection.
Reset	Sets the enumerator to its initial position, which is before the first element in the collection.

System.Collections.IEnumerator Member Details

Summary

Gets the current element in the collection.

C# Syntax:

object Current {get;}

Exceptions

Exception Type	Condition
InvalidOperationException	The enumerator is positioned before the first element of the collection or after the last element.

After an enumerator is created or after a IEnumerator.Reset, IEnumerator.MoveNext must be called to advance the enumerator to the first element of the collection before reading the value of IEnumerator.Current; otherwise, IEnumerator.Current is undefined.

IEnumerator.Current also throws an exception if the last call to IEnumerator.MoveNext returned false, which indicates the end of the collection.

IEnumerator.Current does not move the position of the enumerator and consecutive calls to IEnumerator.Current return the same object until either IEnumerator.MoveNext or IEnumerator.Reset is called.

An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying or deleting elements, the enumerator is irrecoverably invalidated and the next call to IEnumerator.MoveNext or IEnumerator.Reset throws an InvalidOperationException. If the collection is modified between IEnumerator.MoveNext and IEnumerator.Current, IEnumerator.Current will return the element that it is set to, even if the enumerator is already invalidated.

Return to top

Summary

Advances the enumerator to the next element of the collection.

C# Syntax:

bool MoveNext();

Return Value:

true if the enumerator was successfully advanced to the next element; false if the enumerator has passed the end of the collection.

Exceptions

Exception Type	Condition
InvalidOperationException	The collection was modified after the enumerator was created.

After an enumerator is created or after a call to IEnumerator.Reset, an enumerator is positioned before the first element of the collection, and the first call to IEnumerator.MoveNext moves the enumerator over the first element of the collection.

After the end of the collection is passed, subsequent calls to IEnumerator.MoveNext return false until IEnumerator.Reset is called.

An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying or deleting elements, the enumerator is irrecoverably invalidated and the next call to IEnumerator.MoveNext or IEnumerator.Reset throws an InvalidOperationException.

Return to top

Summary

Sets the enumerator to its initial position, which is before the first element in the collection.

C# Syntax:

void Reset();

Exceptions

Exception Type	Condition
InvalidOperationException	The collection was modified after the enumerator was created.

An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying or deleting elements, the enumerator is irrecoverably invalidated and the next call to IEnumerator.MoveNext or IEnumerator.Reset throws an InvalidOperationException.

Notes to implementors:

All calls to IEnumerator.Reset must result in the same state for the enumerator. The preferred implementation is to move the enumerator to the beginning of the collection, before the first element. This invalidates the enumerator if the collection has been modified since the enumerator was created, which is consistent with IEnumerator.MoveNext and IEnumerator.Current.

Return to top

Top of page