Skip to content
Tutorials Center
My learning

Topics

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.

C#
var info = new StringInfo("éa");
Console.WriteLine(info.LengthInTextElements); // 2

Try it

C# Three ways to count

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# Enumerating and truncating safely

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 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.Length counts UTF-16 units, EnumerateRunes() counts code points, and LengthInTextElements counts what a reader sees. They agree only for simple text.
  • Normalization is a different problem. café and café both have 4 text elements, but they are different strings: == returns false. 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 LengthInTextElements walks 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.GetByteCount for 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.Current allocates a string per element; for allocation-free scanning use the GetNextTextElementLength(ReadOnlySpan<char>) overload or Rune APIs.