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.
foreach (Rune r in "a๐".EnumerateRunes()) { Console.WriteLine($"{r} U+{r.Value:X4}"); }
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 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
eplus a combining accent is several runes. For what a reader perceives as one symbol, seeStringInfo. - Static helpers mirror
char.Rune.IsLetter,IsDigit,IsWhiteSpace,ToUpperInvariantandGetUnicodeCategoryexist, and unlikechar.IsLetterthey work for supplementary characters. - Conversion.
(int)or.Valuegives the code point,ToString()makes a one- or two-char string, andrune.EncodeToUtf16(span)orEncodeToUtf8(span)write into a buffer. - Counting.
s.Lengthis UTF-16 units; useCount()onEnumerateRunes()for scalar values, orEncoding.UTF8.GetByteCount(s)for bytes. - Ordering. Runes compare by code point value (
CompareTo,<,>). - Performance.
Runeis a 4-byte struct with no allocation; enumeration over a span is as cheap as acharloop.