Rune Struktur

Definition

public value class Rune : IComparable, IComparable<System::Text::Rune>, IEquatable<System::Text::Rune>

public value class Rune : IComparable<System::Text::Rune>, IEquatable<System::Text::Rune>

public struct Rune : IComparable, IComparable<System.Text.Rune>, IEquatable<System.Text.Rune>

public struct Rune : IComparable<System.Text.Rune>, IEquatable<System.Text.Rune>

type Rune = struct

Public Structure Rune
Implements IComparable, IComparable(Of Rune), IEquatable(Of Rune)

Public Structure Rune
Implements IComparable(Of Rune), IEquatable(Of Rune)

Vererbung

Object

ValueType

Rune

Implementiert

IComparable IComparable<Rune> IEquatable<Rune>

Hinweise

Eine- Rune Instanz stellt einen Unicode-Skalarwert dar, d. h. einen beliebigen Codepunkt ohne den Ersatzbereich (U + D800 und. U + DFFF).A Rune instance represents a Unicode scalar value, which means any code point excluding the surrogate range (U+D800..U+DFFF). Die Konstruktoren und Konvertierungs Operatoren des Typs überprüfen die Eingabe, sodass Consumer die APIs abrufen können, vorausgesetzt, dass die zugrunde liegende Rune Instanz wohl geformt ist.The type's constructors and conversion operators validate the input, so consumers can call the APIs assuming that the underlying Rune instance is well formed.

Wenn Sie mit den Begriffen Unicode-Skalarwert, Codepunkt, Ersatz Zeichenbereich und wohl geformt nicht vertraut sind, finden Sie unter Einführung in die Zeichencodierung in .netWeitere Informationen.If you aren't familiar with the terms Unicode scalar value, code point, surrogate range, and well-formed, see Introduction to character encoding in .NET.

In den folgenden Abschnitten wird Folgendes erläutert:The following sections explain:

• Verwendung des Rune-TypsWhen to use the Rune type
• Wann nicht der Rune-Typ verwendet werden sollWhen not to use the Rune type
• Instanziieren einer RuneHow to instantiate a Rune
• Abfragen von Eigenschaften einer Rune-InstanzHow to query properties of a Rune instance
• Konvertieren Rune von in UTF-8 oder UTF-16Convert a Rune to UTF-8 or UTF-16
• Rune in .net im Vergleich zu anderen SprachenRune in .NET vs. other languages

Verwendung des Rune-TypsWhen to use the Rune type

Verwenden Sie ggf. den Rune Typ, wenn Ihr Code FolgendesConsider using the Rune type if your code:

• Ruft APIs auf, die Unicode-skalare Werte erfordern.Calls APIs that require Unicode scalar values
• Behandelt Ersatzpaare explizit.Explicitly handles surrogate pairs

APIs, die Unicode-skalare Werte erfordernAPIs that require Unicode scalar values

Wenn Ihr Code die- char Instanzen in einem string oder einem durch ReadOnlySpan<char> läuft, funktionieren einige der- char Methoden für- char Instanzen, die sich im Ersatzbereich befinden, nicht ordnungsgemäß.If your code iterates through the char instances in a string or a ReadOnlySpan<char>, some of the char methods won't work correctly on char instances that are in the surrogate range. Beispielsweise erfordern die folgenden APIs einen Skalarwert char , um ordnungsgemäß zu funktionieren:For example, the following APIs require a scalar value char to work correctly:

• Char.GetNumericValue
• Char.GetUnicodeCategory
• Char.IsDigit
• Char.IsLetter
• Char.IsLetterOrDigit
• Char.IsLower
• Char.IsNumber
• Char.IsPunctuation
• Char.IsSymbol
• Char.IsUpper

Das folgende Beispiel zeigt Code, der nicht ordnungsgemäß funktioniert, wenn eine der- char Instanzen Ersatz Code Punkte ist:The following example shows code that won't work correctly if any of the char instances are surrogate code points:

// THE FOLLOWING METHOD SHOWS INCORRECT CODE.
// DO NOT DO THIS IN A PRODUCTION APPLICATION.
int CountLettersBadExample(string s)
{
    int letterCount = 0;

    foreach (char ch in s)
    {
        if (char.IsLetter(ch))
        { letterCount++; }
    }

    return letterCount;
}

Der folgende Code entspricht dem folgenden Code ReadOnlySpan<char> :Here's equivalent code that works with a ReadOnlySpan<char>:

// THE FOLLOWING METHOD SHOWS INCORRECT CODE.
// DO NOT DO THIS IN A PRODUCTION APPLICATION.
static int CountLettersBadExample(ReadOnlySpan<char> span)
{
    int letterCount = 0;

    foreach (char ch in span)
    {
        if (char.IsLetter(ch))
        { letterCount++; }
    }

    return letterCount;
}

Der vorangehende Code funktioniert ordnungsgemäß mit einigen Sprachen, wie z. b. Englisch:The preceding code works correctly with some languages such as English:

CountLettersInString("Hello")
// Returns 5

Dies funktioniert jedoch nicht ordnungsgemäß für Sprachen außerhalb der grundlegenden mehrsprachigen Ebene, wie z. b. Osage:But it won't work correctly for languages outside the Basic Multilingual Plane, such as Osage:

CountLettersInString("𐓏𐓘𐓻𐓘𐓻𐓟 𐒻𐓟")
// Returns 0

Der Grund, warum diese Methode falsche Ergebnisse für den Osage-Text zurückgibt, ist, dass die char Instanzen für Osage-Buchstaben Ersatz Code Punkte sind.The reason this method returns incorrect results for Osage text is that the char instances for Osage letters are surrogate code points. Kein einzelner Ersatz Code Punkt verfügt über genügend Informationen, um zu bestimmen, ob es sich um einen Buchstaben handelt.No single surrogate code point has enough information to determine if it's a letter.

Wenn Sie diesen Code für die Verwendung Rune von anstelle von ändern char , funktioniert die Methode ordnungsgemäß mit Code Punkten außerhalb der grundlegenden mehrsprachigen Ebene:If you change this code to use Rune instead of char, the method works correctly with code points outside the Basic Multilingual Plane:

int CountLetters(string s)
{
    int letterCount = 0;

    foreach (Rune rune in s.EnumerateRunes())
    {
        if (Rune.IsLetter(rune))
        { letterCount++; }
    }

    return letterCount;
}

Der folgende Code entspricht dem folgenden Code ReadOnlySpan<char> :Here's equivalent code that works with a ReadOnlySpan<char>:

static int CountLetters(ReadOnlySpan<char> span)
{
    int letterCount = 0;

    foreach (Rune rune in span.EnumerateRunes())
    {
        if (Rune.IsLetter(rune))
        { letterCount++; }
    }

    return letterCount;
}

Im vorangehenden Code werden Osage-Buchstaben ordnungsgemäß gezählt:The preceding code counts Osage letters correctly:

CountLettersInString("𐓏𐓘𐓻𐓘𐓻𐓟 𐒻𐓟")
// Returns 8

Code, der Ersatzpaare explizit behandeltCode that explicitly handles surrogate pairs

Verwenden Sie ggf. den- Rune Typ, wenn der Code APIs aufruft, die explizit auf Ersatz Code Punkte angewendet werden, z. b. die folgenden Methoden:Consider using the Rune type if your code calls APIs that explicitly operate on surrogate code points, such as the following methods:

• Char.IsSurrogate
• Char.IsSurrogatePair
• Char.IsHighSurrogate
• Char.IsLowSurrogate
• Char.ConvertFromUtf32
• Char.ConvertToUtf32

Beispielsweise verfügt die folgende Methode über eine spezielle Logik, um Ersatz char Paare zu behandeln:For example, the following method has special logic to deal with surrogate char pairs:

static void ProcessStringUseChar(string s)
{
    Console.WriteLine("Using char");

    for (int i = 0; i < s.Length; i++)
    {
        if (!char.IsSurrogate(s[i]))
        {
            Console.WriteLine($"Code point: {(int)(s[i])}");
        }
        else if (i + 1 < s.Length && char.IsSurrogatePair(s[i], s[i + 1]))
        {
            int codePoint = char.ConvertToUtf32(s[i], s[i + 1]);
            Console.WriteLine($"Code point: {codePoint}");
            i++; // so that when the loop iterates it's actually +2
        }
        else
        {
            throw new Exception("String was not well-formed UTF-16.");
        }
    }
}

Dieser Code ist einfacher, wenn er verwendet Rune , wie im folgenden Beispiel gezeigt:Such code is simpler if it uses Rune, as in the following example:

static void ProcessStringUseRune(string s)
{
    Console.WriteLine("Using Rune");

    for (int i = 0; i < s.Length;)
    {
        if (!Rune.TryGetRuneAt(s, i, out Rune rune))
        {
            throw new Exception("String was not well-formed UTF-16.");
        }

        Console.WriteLine($"Code point: {rune.Value}");
        i += rune.Utf16SequenceLength; // increment the iterator by the number of chars in this Rune
    }
}

Wann nicht zu verwenden RuneWhen not to use Rune

Sie müssen den-Typ nicht verwenden, Rune Wenn Ihr Code Folgendes:You don't need to use the Rune type if your code:

• Sucht nach genauen char Übereinstimmungen.Looks for exact char matches
• Unterteilt eine Zeichenfolge mit einem bekannten Char-Wert.Splits a string on a known char value

Die Verwendung des Rune Typs gibt möglicherweise falsche Ergebnisse zurück, wenn Ihr Code Folgendes:Using the Rune type may return incorrect results if your code:

• Zählt die Anzahl der Anzeige Zeichen in einem stringCounts the number of display characters in a string

Nach exakten char Übereinstimmungen suchenLook for exact char matches

Der folgende Code durchläuft eine string Suche nach bestimmten Zeichen und gibt den Index der ersten Übereinstimmung zurück.The following code iterates through a string looking for specific characters, returning the index of the first match. Es ist nicht erforderlich, diesen Code für die Verwendung zu ändern Rune , da der Code nach Zeichen sucht, die durch einen einzelnen dargestellt werden char .There's no need to change this code to use Rune, as the code is looking for characters that are represented by a single char.

int GetIndexOfFirstAToZ(string s)
{
    for (int i = 0; i < s.Length; i++)
    {
        char thisChar = s[i];
        if ('A' <= thisChar && thisChar <= 'Z')
        {
            return i; // found a match
        }
    }

    return -1; // didn't find 'A' - 'Z' in the input string
}

Teilen einer Zeichenfolge auf ein bekanntes charSplit a string on a known char

Es ist üblich string.Split ' ' , wie im folgenden Beispiel Trennzeichen wie (Leerzeichen) oder (Komma) aufzurufen und zu verwenden ',' :It's common to call string.Split and use delimiters such as ' ' (space) or ',' (comma), as in the following example:

string inputString = "🐂, 🐄, 🐆";
string[] splitOnSpace = inputString.Split(' ');
string[] splitOnComma = inputString.Split(',');

Hier ist die Verwendung nicht erforderlich Rune , da der Code nach Zeichen sucht, die von einem einzelnen dargestellt werden char .There is no need to use Rune here, because the code is looking for characters that are represented by a single char.

Zählen der Anzahl der Anzeige Zeichen in einem stringCount the number of display characters in a string

Die Anzahl der Rune Instanzen in einer Zeichenfolge stimmt möglicherweise nicht mit der Anzahl der Benutzer ab, die beim Anzeigen der Zeichenfolge angezeigt werden.The number of Rune instances in a string might not match the number of user-perceivable characters shown when displaying the string.

Da- Rune Instanzen Unicode-Skalarwerte darstellen, können Komponenten, die den Unicode-Text Segmentierungs Richtlinien folgen, Rune als Baustein zum zählen von Anzeige Zeichen verwenden.Since Rune instances represent Unicode scalar values, components that follow the Unicode text segmentation guidelines can use Rune as a building block for counting display characters.

Der- StringInfo Typ kann zum zählen von Anzeige Zeichen verwendet werden, aber in anderen .net-Implementierungen als .net 5 wird er nicht in allen Szenarien ordnungsgemäß gezählt.The StringInfo type can be used to count display characters, but in implementations of .NET other than .NET 5 it doesn't count correctly in all scenarios.

Weitere Informationen finden Sie unter Grapheme-Cluster.For more information, see Grapheme clusters.

Vorgehensweise beim Instanziieren eines RuneHow to instantiate a Rune

Es gibt mehrere Möglichkeiten, um eine-Instanz zu erhalten Rune .There are several ways to get a Rune instance. Sie können einen Konstruktor verwenden, um Rune direkt aus zu erstellen:You can use a constructor to create a Rune directly from:

• Ein Codepunkt.A code point.

  Rune a = new Rune(0x0061); // LATIN SMALL LETTER A
  Rune b = new Rune(0x10421); // DESERET CAPITAL LETTER ER
  

• Eine einzelne char.A single char.

  Rune c = new Rune('a');
  

• Ein Ersatz Zeichen char Paar.A surrogate char pair.

  Rune d = new Rune('\ud83d', '\udd2e'); // U+1F52E CRYSTAL BALL
  

Alle Konstruktoren lösen eine aus, ArgumentException Wenn die Eingabe keinen gültigen Unicode-Skalarwert darstellt.All of the constructors throw an ArgumentException if the input doesn't represent a valid Unicode scalar value.

Es stehen Rune.TryCreate Methoden für Aufrufer zur Verfügung, die keine Ausnahmen bei einem Fehler auslösen möchten.There are Rune.TryCreate methods available for callers who don't want exceptions to be thrown on failure.

Rune Instanzen können auch aus vorhandenen Eingabe Sequenzen gelesen werden.Rune instances can also be read from existing input sequences. Wenn Beispiels ReadOnlySpan<char> Weise ein-Wert mit UTF-16-Daten darstellt, gibt die- Rune.DecodeFromUtf16 Methode die erste Rune Instanz am Anfang der Eingabe Spanne zurück.For instance, given a ReadOnlySpan<char> that represents UTF-16 data, the Rune.DecodeFromUtf16 method returns the first Rune instance at the beginning of the input span. Die- Rune.DecodeFromUtf8 Methode funktioniert ähnlich und akzeptiert einen ReadOnlySpan<byte> Parameter, der UTF-8-Daten darstellt.The Rune.DecodeFromUtf8 method operates similarly, accepting a ReadOnlySpan<byte> parameter that represents UTF-8 data. Es gibt äquivalente Methoden zum Lesen vom Ende der Spanne anstelle des Anfangs der Spanne.There are equivalent methods to read from the end of the span instead of the beginning of the span.

Abfrage Eigenschaften eines RuneQuery properties of a Rune

Um den ganzzahligen Code Punkt Wert einer-Instanz zu erhalten Rune , verwenden Sie die- Rune.Value Eigenschaft.To get the integer code point value of a Rune instance, use the Rune.Value property.

Rune rune = new Rune('\ud83d', '\udd2e'); // U+1F52E CRYSTAL BALL
int codePoint = rune.Value; // = 128302 decimal (= 0x1F52E)

Viele der statischen APIs, die für den char Typ verfügbar sind, sind auch für den- Rune Typ verfügbar.Many of the static APIs available on the char type are also available on the Rune type. Beispielsweise Rune.IsWhiteSpace sind und Rune.GetUnicodeCategory Entsprechungen zu Char.IsWhiteSpace -und- Char.GetUnicodeCategory Methoden.For instance, Rune.IsWhiteSpace and Rune.GetUnicodeCategory are equivalents to Char.IsWhiteSpace and Char.GetUnicodeCategory methods. Die Rune Methoden behandeln Ersatzpaare ordnungsgemäß.The Rune methods correctly handle surrogate pairs.

Der folgende Beispielcode nimmt ReadOnlySpan<char> sowohl als Eingabe als auch als sowohl aus dem Anfang als auch dem Ende der Spanne jede, bei der es Rune sich nicht um einen Buchstaben oder eine Ziffer handelt.The following example code takes a ReadOnlySpan<char> as input and trims from both the start and the end of the span every Rune that isn't a letter or a digit.

static ReadOnlySpan<char> TrimNonLettersAndNonDigits(ReadOnlySpan<char> span)
{
    // First, trim from the front.
    // If any Rune can't be decoded
    // (return value is anything other than "Done"),
    // or if the Rune is a letter or digit,
    // stop trimming from the front and
    // instead work from the end.
    while (Rune.DecodeFromUtf16(span, out Rune rune, out int charsConsumed) == OperationStatus.Done)
    {
        if (Rune.IsLetterOrDigit(rune))
        { break; }
        span = span[charsConsumed..];
    }

    // Next, trim from the end.
    // If any Rune can't be decoded,
    // or if the Rune is a letter or digit,
    // break from the loop, and we're finished.
    while (Rune.DecodeLastFromUtf16(span, out Rune rune, out int charsConsumed) == OperationStatus.Done)
    {
        if (Rune.IsLetterOrDigit(rune))
        { break; }
        span = span[..^charsConsumed];
    }

    return span;
}

Es gibt einige API-Unterschiede zwischen char und Rune .There are some API differences between char and Rune. Beispiel:For example:

• Es gibt keine Rune Entsprechung Char.IsSurrogate(Char) von, da Rune Instanzen definitionsgemäß nie Ersatz Code Punkte sein können.There is no Rune equivalent to Char.IsSurrogate(Char), since Rune instances by definition can never be surrogate code points.
• Rune.GetUnicodeCategoryGibt nicht immer dasselbe Ergebnis wie zurück Char.GetUnicodeCategory .The Rune.GetUnicodeCategory doesn't always return the same result as Char.GetUnicodeCategory. Er gibt den gleichen Wert wie zurück CharUnicodeInfo.GetUnicodeCategory .It does return the same value as CharUnicodeInfo.GetUnicodeCategory. Weitere Informationen finden Sie in den hinweisen zu Char.GetUnicodeCategory .For more information, see the Remarks on Char.GetUnicodeCategory.

Konvertieren Rune von in UTF-8 oder UTF-16Convert a Rune to UTF-8 or UTF-16

Da ein Rune ein Unicode-Skalarwert ist, kann er in UTF-8-, UTF-16-oder UTF-32-Codierung konvertiert werden.Since a Rune is a Unicode scalar value, it can be converted to UTF-8, UTF-16, or UTF-32 encoding. Der Rune -Typ verfügt über integrierte Unterstützung für die Konvertierung in UTF-8 und UTF-16.The Rune type has built-in support for conversion to UTF-8 and UTF-16.

Rune.EncodeToUtf16Konvertiert eine- Rune Instanz in- char Instanzen.The Rune.EncodeToUtf16 converts a Rune instance to char instances. Verwenden Sie die-Eigenschaft, um die Anzahl von Instanzen abzufragen, die sich char aus der Umstellung einer- Rune Instanz in UTF-16 ergeben würden Rune.Utf16SequenceLength .To query the number of char instances that would result from converting a Rune instance to UTF-16, use the Rune.Utf16SequenceLength property. Ähnliche Methoden sind für die UTF-8-Konvertierung vorhanden.Similar methods exist for UTF-8 conversion.

Im folgenden Beispiel wird eine- Rune Instanz in ein- char Array konvertiert.The following example converts a Rune instance to a char array. Der Code setzt voraus, dass Sie über eine- Rune Instanz in der- rune Variable verfügenThe code assumes you have a Rune instance in the rune variable:

char[] chars = new char[rune.Utf16SequenceLength];
int numCharsWritten = rune.EncodeToUtf16(chars);

Da eine string eine Sequenz von UTF-16-Zeichen ist, wird im folgenden Beispiel auch eine- Rune Instanz in UTF-16 konvertiert:Since a string is a sequence of UTF-16 chars, the following example also converts a Rune instance to UTF-16:

string theString = rune.ToString();

Im folgenden Beispiel wird eine- Rune Instanz in ein UTF-8 Bytearray konvertiert:The following example converts a Rune instance to a UTF-8 byte array:

byte[] bytes = new byte[rune.Utf8SequenceLength];
int numBytesWritten = rune.EncodeToUtf8(bytes);

Die Rune.EncodeToUtf16 - Rune.EncodeToUtf8 Methode und die-Methode geben die tatsächliche Anzahl der geschriebenen Elemente zurück.The Rune.EncodeToUtf16 and Rune.EncodeToUtf8 methods return the actual number of elements written. Sie lösen eine Ausnahme aus, wenn der Ziel Puffer zu kurz ist, um das Ergebnis zu enthalten.They throw an exception if the destination buffer is too short to contain the result. Es gibt auch nicht auslösende TryEncodeToUtf8 Methoden und für Aufrufer EncodeToUtf16 , die Ausnahmen vermeiden möchten.There are non-throwing TryEncodeToUtf8 and EncodeToUtf16 methods as well for callers who want to avoid exceptions.

Rune in .net im Vergleich zu anderen SprachenRune in .NET vs. other languages

Der Begriff "Rune" ist im Unicode-Standard nicht definiert.The term "rune" is not defined in the Unicode Standard. Der Begriff ist zurück auf die Erstellung von UTF-8.The term dates back to the creation of UTF-8. Rob Pike und Ken Thompson suchten nach einem Begriff, der beschreibt, was schließlich als Codepunkt bezeichnet wird.Rob Pike and Ken Thompson were looking for a term to describe what would eventually become known as a code point. Sie sind auf den Begriff "Rune" festgelegt, und der spätere Einfluss von Rob Pike auf die go-Programmiersprache half dabei, den Begriff zu popularisieren.They settled on the term "rune", and Rob Pike's later influence over the Go programming language helped popularize the term.

Der .net- Rune Typ ist jedoch nicht das Äquivalent zum Go- rune Typ.However, the .NET Rune type is not the equivalent of the Go rune type. In Go ist der rune Typ ein Alias für int32 .In Go, the rune type is an alias for int32. Eine Go-Rune ist für die Darstellung eines Unicode-Code Punkts gedacht, kann jedoch ein beliebiger 32-Bit-Wert sein, einschließlich Ersatz Code Punkten und Werten, die keine zulässigen Unicode-Code Punkte sind.A Go rune is intended to represent a Unicode code point, but it can be any 32-bit value, including surrogate code points and values that are not legal Unicode code points.

Informationen zu ähnlichen Typen in anderen Programmiersprachen finden Sie unter der primitive char Typ von Rust oder der SWIFT- Unicode.Scalar Typ, die beide Unicode-Skalarwerte darstellen.For similar types in other programming languages, see Rust's primitive char type or Swift's Unicode.Scalar type, both of which represent Unicode scalar values. Sie bieten ähnliche Funktionen wie. Der Rune Netzwerktyp, und Sie können keine Instanziierung von Werten zulassen, die keine zulässigen Unicode-Skalarwerte sind.They provide functionality similar to .NET's Rune type, and they disallow instantiation of values that are not legal Unicode scalar values.

Konstruktoren

Eigenschaften

Methoden

Operatoren

Explizite Schnittstellenimplementierungen

Gilt für: