Skip to content
Tutorials Center
My learning

Topics

C# Reference ยท Strings and Text

The Rune struct

Reference for System.Text.Rune in C#: iterate real Unicode characters, handle surrogate pairs and emoji, and convert between runes, chars and strings.

A Rune is one Unicode scalar value: any code point from U+0000 to U+10FFFF except the surrogate range U+D800 to U+DFFF. A .NET char is only a 16-bit UTF-16 code unit, so characters outside the Basic Multilingual Plane, such as most emoji, are stored in a string as two char values (a surrogate pair). Rune gives you the whole character as one value.

A Rune is a small readonly struct, so it costs nothing to pass around. You can only create one from a valid scalar value, which means a lone surrogate can never hide inside a Rune.

C#
foreach (Rune r in "a๐Ÿ˜€".EnumerateRunes())
{
    Console.WriteLine($"{r} U+{r.Value:X4}");
}

Try it

C# chars versus runes

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# Creating and testing runes

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 readonly struct Rune : IComparable<Rune>, IEquatable<Rune>
{
    public Rune(char ch);
    public Rune(int value);
    public Rune(uint value);
    public Rune(char highSurrogate, char lowSurrogate);

    public int Value { get; }
    public bool IsAscii { get; }
    public bool IsBmp { get; }
    public int Utf16SequenceLength { get; }
    public int Utf8SequenceLength { get; }

    public static bool IsValid(int value);
    public static bool TryCreate(int value, out Rune result);
    public static OperationStatus DecodeFromUtf16(ReadOnlySpan<char> source, out Rune result, out int charsConsumed);
}
Name Description
value The code point as an integer. Must be 0 to 0x10FFFF and not a surrogate.
ch A single char that is not a surrogate.
highSurrogate, lowSurrogate Two chars that form a valid pair.

Returns: constructors build the rune; TryCreate returns false for invalid values; DecodeFromUtf16 returns an OperationStatus (Done, InvalidData, NeedMoreData).

Errors / undefined behavior: the constructors throw ArgumentOutOfRangeException for a surrogate or an out-of-range value. Decoding a lone surrogate gives InvalidData and the replacement rune U+FFFD.

Usage notes

  • Use EnumerateRunes() to walk text. foreach (char c in s) splits emoji and other supplementary characters into two meaningless halves. EnumerateRunes() yields complete scalar values, and substitutes U+FFFD for an unpaired surrogate.
  • A rune is not a visible character. A flag emoji or an e plus a combining accent is several runes. For what a reader perceives as one symbol, see StringInfo.
  • Static helpers mirror char. Rune.IsLetter, IsDigit, IsWhiteSpace, ToUpperInvariant and GetUnicodeCategory exist, and unlike char.IsLetter they work for supplementary characters.
  • Conversion. (int) or .Value gives the code point, ToString() makes a one- or two-char string, and rune.EncodeToUtf16(span) or EncodeToUtf8(span) write into a buffer.
  • Counting. s.Length is UTF-16 units; use Count() on EnumerateRunes() for scalar values, or Encoding.UTF8.GetByteCount(s) for bytes.
  • Ordering. Runes compare by code point value (CompareTo, <, >).
  • Performance. Rune is a 4-byte struct with no allocation; enumeration over a span is as cheap as a char loop.