Type: System.Globalization.TextElementEnumerator

System.Globalization.TextElementEnumerator Class

Assembly: Mscorlib.dll
Namespace: System.Globalization

Summary: Enumerates the text elements of a string.

C# Syntax:

[Serializable]
public class TextElementEnumerator : IEnumerator

Remarks

The .NET Framework defines a text element as a unit of text that is displayed as a single character; that is, a grapheme. A text element can be a base character, a surrogate pair, or a combining character sequence. The Unicode Standard defines a surrogate pair as a coded character representation for a single abstract character that consists of a sequence of two code units, where the first unit of the pair is a high-surrogate and the second is a low-surrogate. The Unicode Standard defines a combining character sequence as a combination of a base character and one or more combining characters. A surrogate pair can represent a base character or a combining character. For more information on surrogate pairs and combining character sequences, see The Unicode Standard at http://www.unicode.org.

Text element enumerators are intended to be used only to read data in the string. Enumerators cannot be used to modify the underlying string.

The enumerator does not have exclusive access to the string.

When an enumerator is created, it takes a snapshot of the current state of the string. If changes are made to the string, such as adding, modifying, or deleting text elements, the snapshot gets out of sync and the enumerator throws an InvalidOperationException. Two enumerators created from the same string at the same time can have different snapshots of the string.

The enumerator is in an invalid state if it is positioned before the first text element in the string or after the last text element in the string. Whenever the enumerator is in an invalid state, calling TextElementEnumerator.Current throws an exception.

Initially, the enumerator is positioned before the first text element in the string. TextElementEnumerator.Reset also brings the enumerator back to this position. Therefore, after an enumerator is created or after a TextElementEnumerator.Reset, TextElementEnumerator.MoveNext must be called to advance the enumerator to the first text element of the string before reading the value of TextElementEnumerator.Current.

TextElementEnumerator.Current returns the same object until either TextElementEnumerator.MoveNext or TextElementEnumerator.Reset is called.

After the end of the string is passed, the enumerator is again in an invalid state and calling TextElementEnumerator.MoveNext returns false. Calling TextElementEnumerator.Current throws an exception if the last call to TextElementEnumerator.MoveNext returned false.

System.Globalization.TextElementEnumerator Member List:

Public Properties

Current	Read-only Gets the current text element in the string.
ElementIndex	Read-only Gets the index of the text element that the enumerator is currently positioned over.

Public Methods

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.
GetTextElement	Gets the current text element in the string.
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	Advances the enumerator to the next text element of the string.
Reset	Sets the enumerator to its initial position, which is before the first text element in the 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.Globalization.TextElementEnumerator

System.Globalization.TextElementEnumerator Member Details

Property: Current (read-only)

Summary: Gets the current text element in the string.

C# Syntax:


            public object Current {get;}

Exceptions

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

Implements:: IEnumerator.Current

Remarks

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

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

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

Return to top

Property: ElementIndex (read-only)

Summary: Gets the index of the text element that the enumerator is currently positioned over.

C# Syntax:


            public int ElementIndex {get;}

Exceptions

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

Remarks

Return to top

Method: Equals(
object obj
)

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

Method: Finalize()

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

C# Syntax:


            ~TextElementEnumerator();

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

Return to top

Method: GetHashCode()

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

Method: GetTextElement()

Summary: Gets the current text element in the string.

C# Syntax:


            public string GetTextElement();

Return Value:: A new string containing the current text element in the string being read.

Exceptions

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

Remarks

This method returns the same text element as the TextElementEnumerator.Current property.

Return to top

Method: GetType()

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

Method: MemberwiseClone()

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

Method: MoveNext()

Summary: Advances the enumerator to the next text element of the string.

C# Syntax:


            public bool MoveNext();

Return Value:: true if the enumerator was successfully advanced to the next text element; false if the enumerator has passed the end of the string.

Exceptions

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

Implements:: IEnumerator.MoveNext

Remarks

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

If the string is modified after this enumerator was created, TextElementEnumerator.MoveNext throws an exception.

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

See also:
TextElementEnumerator.Current | TextElementEnumerator.Reset

Return to top

Method: Reset()

Summary: Sets the enumerator to its initial position, which is before the first text element in the string.

C# Syntax:


            public void Reset();

Exceptions

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

Implements:: IEnumerator.Reset

Remarks

TextElementEnumerator.Reset moves the enumerator to the beginning of the string, before the first text element. After TextElementEnumerator.Reset, TextElementEnumerator.MoveNext must be called to advance the enumerator to the first text element of the string before reading the value of TextElementEnumerator.Current.

Return to top

Method: ToString()

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.