System.CharEnumerator Class

Summary

Supports iterating over a String and reading its individual characters.

C# Syntax:

[Serializable] public sealed class CharEnumerator : IEnumerator, ICloneable

A CharEnumerator provides read-only access to the characters in a referenced String object. For example, the foreach statement of the Microsoft Visual Basic and C# programming languages, which iterates through the elements of a collection, retrieves a CharEnumerator from an instance of String in order to iterate through the characters in that instance.

There is no public constructor for CharEnumerator. Instead, call a String object's String.GetEnumerator method to obtain a CharEnumerator that is initialized to reference the string.

A CharEnumerator maintains an internal index to the characters in the string the CharEnumerator references. The state of the index is invalid when it references a character position logically before the first character or after the last character in the string, and valid when it references a character within the string. The index is initialized to a position logically before the first character, and is set to a position after the last character when the iteration is complete. An exception is thrown if you attempt to access a character while the index is invalid.

The CharEnumerator.MoveNext method increments the index by one, so the first and subsequent characters are accessed in turn. The CharEnumerator.Reset method sets the index to a position logically before the first character. The CharEnumerator.Current property retrieves the character currently referenced by index. The CharEnumerator.Clone method creates a copy of the CharEnumerator.

Note Several independent instances of CharEnumerator across one or more threads can have access to a single instance of String. This class is implemented to support the IEnumerator interface. For more information regarding the use of an enumerator, see the IEnumerator topic.

System Namespace | String | IEnumerator | IEnumerable | ICollection

System.CharEnumerator Member List:

Public Properties

Current

Read-only Gets the character in the enumerated string currently indexed by this instance.

Public Methods

Clone	Creates a copy of this instance.
Equals (inherited from System.Object)	See base class member description: System.Object.Equals Derived from System.Object, the primary base class for all objects.
GetHashCode (inherited from System.Object)	See base class member description: System.Object.GetHashCode Derived from System.Object, the primary base class for all objects.
GetType (inherited from System.Object)	See base class member description: System.Object.GetType Derived from System.Object, the primary base class for all objects.
MoveNext	Increments the index to the next character of the enumerated string.
Reset	Initializes the index to a position logically before the first character of the enumerated string.
ToString (inherited from System.Object)	See base class member description: System.Object.ToString Derived from System.Object, the primary base class for all objects.

Protected Methods

Finalize (inherited from System.Object)	See base class member description: System.Object.Finalize Derived from System.Object, the primary base class for all objects.
MemberwiseClone (inherited from System.Object)	See base class member description: System.Object.MemberwiseClone Derived from System.Object, the primary base class for all objects.

Hierarchy:

• System.Object
• System.CharEnumerator

System.CharEnumerator Member Details

Summary

Gets the character in the enumerated string currently indexed by this instance.

C# Syntax:

public char Current {get;}

Exceptions

Exception Type	Condition
InvalidOperationException	The index is invalid; that is, it is before the first or after the last character of the enumerated string.

This property should only be invoked when the index maintained by this instance is valid, otherwise, an exception is thrown. The index is always invalid for an empty string ("").

The index is invalid after the String.GetEnumerator or CharEnumerator.Reset method is called. After either of these methods is called, invoke the CharEnumerator.MoveNext method to adjust the index to the first character in the enumerated string. The index is valid whenever the CharEnumerator.MoveNext method returns true.

CharEnumerator.Current does not move the index, and consecutive calls to CharEnumerator.Current return the same character until CharEnumerator.MoveNext, CharEnumerator.Reset, or String.GetEnumerator is called.

Return to top

Summary

Creates a copy of this instance.

C# Syntax:

public object Clone();

Return Value:

An Object that is a copy of this instance.

Implements:

ICloneable.Clone

The return value is a copy of this instance of CharEnumerator and its current state. This is useful for saving your state while iterating through a String object.

For example, suppose your application uses an original instance of CharEnumerator to iterate through each character in a String. When some unique character is encountered, your application pauses processing and invokes the CharEnumerator.Clone method. In effect, this saves the CharEnumerator object's index in the String.

Your application uses the clone to navigate to another part of the String to perform some auxiliary processing. The side-effect of this navigation is the clone loses track of the position where processing stopped. However, when the auxiliary processing is complete, your application discards the clone and uses the original CharEnumerator instance to resume working on the String where the original processing stopped.

Note This method is implemented to support the ICloneable interface.

Return to top

Inherited
See base class member description: System.Object.Equals

C# Syntax:

public virtual bool Equals(    object obj );

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.Finalize

C# Syntax:

~CharEnumerator();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.GetHashCode

C# Syntax:

public virtual int GetHashCode();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.GetType

C# Syntax:

public Type GetType();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.MemberwiseClone

C# Syntax:

protected object MemberwiseClone();

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

Increments the index to the next character of the enumerated string.

C# Syntax:

public bool MoveNext();

Return Value:

true if the index is successfully incremented and within the enumerated string; otherwise, false.

Implements:

IEnumerator.MoveNext

The CharEnumerator.MoveNext method increments the index by one. Call CharEnumerator.MoveNext after calling String.GetEnumerator or CharEnumerator.Reset to increment the current character position to the first character in the enumerated string. Check that the return value is true to determine that the current character position is valid.

If the index is already beyond the last character of the enumerated string, the index is not changed and false is returned.

Notice that if the enumerated string is empty (""), the state of the CharEnumerator is always invalid. This is because the internal index for the CharEnumerator is initially before the first character of the enumerated string and is therefore invalid. CharEnumerator.MoveNext logically sets the index after the last (nonexistent) character of the enumerated string which is also invalid.

Return to top

Summary

Initializes the index to a position logically before the first character of the enumerated string.

C# Syntax:

public void Reset();

Implements:

IEnumerator.Reset

The index is set to the invalid state.

Return to top

Inherited
See base class member description: System.Object.ToString

C# Syntax:

public virtual string ToString();

For more information on members inherited from System.Object click on the link above.

Return to top

Top of page