C# Reference · Strings and Text
StringInfo and text elements
Reference for System.Globalization.StringInfo in C#: count and slice user-perceived characters such as accented letters, flags and family emoji.
What a reader sees as one character is not always one char or even one Rune. The letter e followed by a combining acute accent is two code points drawn as one symbol, and a family emoji can be seven. These units are called grapheme clusters, and .NET exposes them as text elements through System.Globalization.StringInfo.
Use StringInfo whenever you count, truncate, reverse or index text for people to read: character limits in a form, cutting a title with an ellipsis, or moving a cursor in an editor.
var info = new StringInfo("éa"); Console.WriteLine(info.LengthInTextElements); // 2
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 class StringInfo { public StringInfo(string value); public string String { get; set; } public int LengthInTextElements { get; } public string SubstringByTextElements(int startingTextElement); public string SubstringByTextElements(int startingTextElement, int lengthInTextElements); public static TextElementEnumerator GetTextElementEnumerator(string str); public static TextElementEnumerator GetTextElementEnumerator(string str, int index); public static int[] ParseCombiningCharacters(string str); public static string GetNextTextElement(string str); public static int GetNextTextElementLength(string str); }
| Name | Description |
|---|---|
value, str |
The text to examine. |
startingTextElement |
Zero-based index counted in text elements, not chars. |
lengthInTextElements |
How many text elements to take. |
index |
A char index at which enumeration starts. |
Returns: counts, substrings, an enumerator whose Current is a string, or an array of the char indexes where each element starts.
Errors / undefined behavior: ArgumentNullException for a null string; ArgumentOutOfRangeException when an index or length is outside the text-element range.
Usage notes
- Three different lengths.
s.Lengthcounts UTF-16 units,EnumerateRunes()counts code points, andLengthInTextElementscounts what a reader sees. They agree only for simple text. - Normalization is a different problem.
caféandcaféboth have 4 text elements, but they are different strings:==returnsfalse. Compare after normalizing, or with a culture-aware comparison. Normalization in our runner is a no-op, so run that part in your own environment. - Element boundaries follow the Unicode text segmentation rules built into the runtime. Recent .NET versions follow the extended grapheme cluster rules, so ZWJ emoji sequences and flags count as one; older versions counted them as several. Check your target framework before relying on it.
- Cost. Each call to
LengthInTextElementswalks the string, so cache the result in a loop instead of calling it per iteration. - Do not use text elements for storage limits. Databases and protocols limit bytes or code units. Use
Encoding.GetByteCountfor those. - Rendering is a separate step. Whether a family sequence is drawn as one picture depends on the font. Text elements describe the text, not the glyphs.
- Allocation.
TextElementEnumerator.Currentallocates a string per element; for allocation-free scanning use theGetNextTextElementLength(ReadOnlySpan<char>)overload orRuneAPIs.