Rune Struktura

Definice

Obor názvů:

System.Text

Sestavení:

System.Runtime.dll

Zdroj:

Rune.cs

Představuje skalární hodnotu Unicode ([ U+0000..U+D7FF ], inclusive; nebo [ U+E000.. U+10FFFF ], včetně).

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

public readonly struct Rune : IComparable, IComparable<System.Text.Rune>, IEquatable<System.Text.Rune>, ISpanFormattable, IUtf8SpanFormattable, IUtf8SpanParsable<System.Text.Rune>

type Rune = struct
    interface IFormattable
    interface ISpanFormattable
    interface IUtf8SpanFormattable
    interface IUtf8SpanParsable<Rune>

Public Structure Rune
Implements IComparable, IComparable(Of Rune), IEquatable(Of Rune), ISpanFormattable, IUtf8SpanFormattable, IUtf8SpanParsable(Of Rune)

Dědičnost

Object

ValueType

Rune

Implementuje

IComparable IComparable<Rune> IEquatable<Rune> IFormattable ISpanFormattable IUtf8SpanFormattable IUtf8SpanParsable<Rune>

Poznámky

Rune Instance představuje skalární hodnotu Unicode, což znamená libovolný bod kódu s výjimkou náhradního rozsahu (U+D800..U+DFFF). Konstruktory a operátory převodu typu ověřují vstup, takže uživatelé mohou volat rozhraní API za předpokladu, že je základní Rune instance správně vytvořená.

Pokud neznáte termíny skalární hodnota Unicode, kódový bod, náhradní rozmezí a dobře formátovaný, přečtěte si téma Úvod do kódování znaků v .NET.

Kdy použít typ Rune

Zvažte použití typu Rune, pokud váš kód:

• Volá rozhraní API, která vyžadují skalární hodnoty Unicode.
• Explicitní zpracování náhradních dvojic

Rozhraní API, která vyžadují skalární hodnoty Unicode

Pokud váš kód prochází char instancemi v string nebo ReadOnlySpan<char>, některé z char metod nebudou správně fungovat na char instancích, které jsou v surrogate range. Například následující rozhraní API vyžadují, aby skalární hodnota char fungovala správně:

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

Následující příklad ukazuje kód, který nebude správně fungovat, pokud některé z char instancí jsou náhradní body kódu:

// 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;
}

// THE FOLLOWING METHOD SHOWS INCORRECT CODE.
// DO NOT DO THIS IN A PRODUCTION APPLICATION.
let countLettersBadExample (s: string) =
    let mutable letterCount = 0

    for ch in s do
        if Char.IsLetter ch then
            letterCount <- letterCount + 1
    
    letterCount

Tady je ekvivalentní kód, který funguje s 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;
}

Předchozí kód funguje správně s některými jazyky, jako je angličtina:

CountLettersInString("Hello")
// Returns 5

Ale nebude fungovat správně pro jazyky mimo základní vícejazyčnou rovinu, například Osage:

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

Důvodem, proč tato metoda vrací nesprávné výsledky pro text Osage je, že char instance písmen Osage jsou náhradní body kódu. Žádný bod náhradního kódu nemá dostatek informací k určení, jestli se jedná o písmeno.

Pokud změníte tento kód na to, aby se používal Rune místo char, metoda funguje správně s kódovými body mimo základní vícejazyčnou rovinu.

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

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

    return letterCount;
}

let countLetters (s: string) =
    let mutable letterCount = 0

    for rune in s.EnumerateRunes() do
        if Rune.IsLetter rune then
            letterCount <- letterCount + 1

    letterCount

Tady je ekvivalentní kód, který funguje s ReadOnlySpan<char>:

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

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

    return letterCount;
}

Předchozí kód počítá správně písmena Osage:

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

Kód, který explicitně zpracovává náhradní páry

Zvažte použití Rune typu, pokud váš kód volá rozhraní API, která explicitně pracují s náhradními body kódu, například následující metody:

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

Například následující metoda má speciální logiku pro řešení náhradních char párů:

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.");
        }
    }
}

Takový kód je jednodušší, pokud používá Rune, jako v následujícím příkladu:

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
    }
}

Kdy se nepoužívá Rune

Pokud váš kód splňuje podmínky, nemusíte používat typ Rune.

• Hledá přesné char shody.
• Rozdělí řetězec podle zadaného znaku.

Použití typu Rune může vrátit nesprávné výsledky, pokud váš kód:

• Spočítá počet zobrazovaných znaků v string

Vyhledání přesných char shod

Následující kód prochází hledáním string konkrétních znaků a vrátí index první shody. Tento kód není nutné měnit tak, aby se používal Rune, protože kód hledá znaky, které jsou reprezentovány jedním 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
}

Rozděl řetězec na známé char

Je běžné volat string.Split a používat oddělovače, jako je ' ' (mezera) nebo ',' (čárka), jak je znázorněno v následujícím příkladu:

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

Zde není nutné používat Rune , protože kód hledá znaky, které jsou reprezentovány jedním char.

Spočítat počet zobrazovaných znaků v string

Počet Rune instancí v řetězci nemusí odpovídat počtu uživatelsky srozumitelných znaků zobrazených při zobrazení řetězce.

Vzhledem k tomu, že Rune instance představují skalární hodnoty Unicode, mohou komponenty, které dodržují pokyny pro segmentaci textu Unicode , použít Rune jako stavební blok pro počítání zobrazovaných znaků.

Typ StringInfo lze použít k počítání zobrazovaných znaků, ale ve všech scénářích jiných než .NET 5 nebo novějších se nepočítá správně.

Další informace najdete v tématu Graphemové clustery.

Jak vytvořit instanci Rune

Existuje několik způsobů, jak získat Rune instanci. Konstruktor můžete použít k vytvoření Rune přímo z:

• Bod kódu.

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

• Jedenchar.

  Rune c = new Rune('a');
  

• Náhradní char pár.

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

Všechny konstruktory vyvolají výjimku ArgumentException, pokud vstup nepředstavuje platnou skalární hodnotu Unicode.

Pro volající, kteří nechtějí, aby při selhání docházelo k vyvolání výjimek, jsou dostupné metody Rune.TryCreate.

Rune Instance lze také číst z existujících vstupních sekvencí. Například pokud ReadOnlySpan<char> představuje data UTF-16, metoda Rune.DecodeFromUtf16 vrátí první výskyt Rune na začátku vstupního úseku. Metoda Rune.DecodeFromUtf8 funguje podobně a přijímá ReadOnlySpan<byte> parametr, který představuje data UTF-8. Jsou k dispozici ekvivalentní metody pro čtení od konce rozsahu místo od začátku rozsahu.

Vlastnosti dotazu Rune

Chcete-li získat celočíselnou hodnotu Rune bodu kódu instance, použijte Rune.Value vlastnost.

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

Mnoho statických rozhraní API dostupných pro typ char je také k dispozici pro typ Rune. Například jsou Rune.IsWhiteSpace a Rune.GetUnicodeCategory ekvivalenty k metodám Char.IsWhiteSpace a Char.GetUnicodeCategory. Metody Rune správně zpracovávají náhradní páry.

Následující příklad kódu přebírá ReadOnlySpan<char> jako vstup a ořízne z počátečního i koncového rozsahu každý Rune , který není písmenem nebo číslicí.

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;
}

Mezi char a Rune existují určité rozdíly v API. Příklad:

• Neexistuje žádný Rune ekvivalent , Char.IsSurrogate(Char)protože Rune instance podle definice nemohou být nikdy náhradními body kódu.
• Vždy Rune.GetUnicodeCategory nevrací stejný výsledek jako Char.GetUnicodeCategory. Vrátí stejnou hodnotu jako CharUnicodeInfo.GetUnicodeCategory. Další informace naleznete v poznámkách o Char.GetUnicodeCategory.

Převeďte Rune na UTF-8 nebo UTF-16

Rune Vzhledem k tomu, že je skalární hodnota Unicode, lze ji převést na kódování UTF-8, UTF-16 nebo UTF-32. Typ Rune má integrovanou podporu převodu na UTF-8 a UTF-16.

Rune.EncodeToUtf16 Převede Rune instanci na char instance. Chcete-li zjistit počet instancí char, které by byly výsledkem převodu instance Rune na UTF-16, použijte vlastnost Rune.Utf16SequenceLength. Podobné metody existují pro převod UTF-8.

Následující příklad převede Rune instanci na char pole. Kód předpokládá, že máte instanci Rune v proměnné rune.

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

Vzhledem k tomu, že string je posloupností znaků UTF-16, následující příklad také převede instanci Rune na UTF-16:

string theString = rune.ToString();

Následující příklad převede Rune instanci na bajtové UTF-8 pole:

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

Metody Rune.EncodeToUtf16 a Rune.EncodeToUtf8 vrátí skutečný počet zapsaných prvků. Vyvolají výjimku, pokud je cílová vyrovnávací paměť příliš krátká, aby obsahovala výsledek. Existují i metody TryEncodeToUtf8 a TryEncodeToUtf16 pro volající, kteří se chtějí vyhnout výjimkám.

Runy v .NET vs. jiných jazycích

Termín rune není definován ve standardu Unicode. Termín pochází zpět k vytvoření UTF-8. Rob Pike a Ken Thompson hledali termín, který by nakonec popsal, co by se nakonec stalo známým jako kódový bod. Usadili se na termínu "rune", a Rob Pike později vliv na programovací jazyk Go pomohl popularizovat termín.

Typ .NET Rune však není ekvivalentem typu Go rune . V Go je rune typ alias pro int32. Runa Go má představovat kódový bod Unicode, ale může to být jakákoli 32bitová hodnota, včetně náhradních kódových bodů a hodnot, které nejsou legálními kódovými body Unicode.

Podobné typy v jiných programovacích jazycích najdete, viz primitivní typ char Rustu nebo typ Unicode.Scalar Swiftu, které oba představují skalární hodnoty Unicode. Poskytují funkce podobné typu Rune v .NET a nepovolují vytváření instancí hodnot, které nejsou platnými skalárními hodnotami Unicode.

Konstruktory

Name	Description
Rune(Char, Char)	Rune Vytvoří ze zadaného páru náhradních souborů UTF-16.
Rune(Char)	Rune Vytvoří z poskytnuté jednotky kódu UTF-16.
Rune(Int32)	Rune Vytvoří ze zadaného 32bitového celého čísla, které představuje skalární hodnotu Unicode.
Rune(UInt32)	Rune Vytvoří ze zadaného 32bitového celého čísla bez znaménka, které představuje skalární hodnotu Unicode.

Vlastnosti

Name	Description
IsAscii	Získá hodnotu, která označuje, zda skalární hodnota přidružená k tomu Rune je v rozsahu kódování ASCII.
IsBmp	Získá hodnotu, která označuje, zda skalární hodnota přidružená k tomu Rune je v rozsahu kódování BMP.
Plane	Získá rovinu Unicode (0 až 16 včetně), která obsahuje tento skalární.
ReplacementChar	Rune Získá instanci, která představuje znak nahrazení Unicode U+FFFD.
Utf16SequenceLength	Získá délku v jednotkách kódu (Char) sekvence UTF-16 vyžadované k reprezentaci této skalární hodnoty.
Utf8SequenceLength	Získá délku v jednotkách kódu sekvence UTF-8 vyžadované k reprezentaci této skalární hodnoty.
Value	Získá skalární hodnotu Unicode jako celé číslo.

Metody

Name	Description
CompareTo(Rune)	Porovná aktuální instanci se zadanou Rune instancí.
DecodeFromUtf16(ReadOnlySpan<Char>, Rune, Int32)	Dekóduje Rune na začátku poskytnuté zdrojové vyrovnávací paměti UTF-16.
DecodeFromUtf8(ReadOnlySpan<Byte>, Rune, Int32)	Dekóduje Rune na začátku poskytnuté zdrojové vyrovnávací paměti UTF-8.
DecodeLastFromUtf16(ReadOnlySpan<Char>, Rune, Int32)	Dekóduje Rune na konci poskytnuté zdrojové vyrovnávací paměti UTF-16.
DecodeLastFromUtf8(ReadOnlySpan<Byte>, Rune, Int32)	Dekóduje Rune na konci poskytnuté zdrojové vyrovnávací paměti UTF-8.
EncodeToUtf16(Span<Char>)	Zakóduje ho Rune do cílové vyrovnávací paměti UTF-16.
EncodeToUtf8(Span<Byte>)	Zakóduje ho Rune do cílové vyrovnávací paměti UTF-8.
Equals(Object)	Vrátí hodnotu, která určuje, zda aktuální instance a zadaný objekt jsou stejné.
Equals(Rune)	Vrátí hodnotu, která určuje, zda je aktuální instance a zadaná rune rovna.
GetHashCode()	Vrátí kód hash pro tuto instanci.
GetNumericValue(Rune)	Získá číselnou hodnotu přidruženou k zadanému spuštění.
GetRuneAt(String, Int32)	Rune Získá ten, který začíná na zadané pozici v řetězci.
GetUnicodeCategory(Rune)	Získá kategorii Unicode přidruženou k zadanému spuštění.
IsControl(Rune)	Vrátí hodnotu, která určuje, zda je zadaný rune zařazen do kategorie jako řídicí znak.
IsDigit(Rune)	Vrátí hodnotu, která určuje, jestli je zadaný rune zařazený do kategorií jako desetinná číslice.
IsLetter(Rune)	Vrátí hodnotu, která určuje, jestli je zadaný rune zařazený do kategorií jako písmeno.
IsLetterOrDigit(Rune)	Vrátí hodnotu, která určuje, zda je zadaný rune zařazen do kategorií jako písmeno nebo desetinná číslice.
IsLower(Rune)	Vrátí hodnotu, která určuje, zda je zadaný rune zařazen do kategorie malými písmeny.
IsNumber(Rune)	Vrátí hodnotu, která určuje, jestli je zadaný rune zařazený do kategorie jako číslo.
IsPunctuation(Rune)	Vrátí hodnotu, která určuje, jestli je zadaný rune zařazený do kategorií jako interpunkční znaménko.
IsSeparator(Rune)	Vrátí hodnotu, která určuje, zda je zadaný rune zařazen do kategorie jako oddělovač znaku.
IsSymbol(Rune)	Vrátí hodnotu, která určuje, zda je zadaný rune zařazen do kategorie jako znak symbolu.
IsUpper(Rune)	Vrátí hodnotu, která určuje, zda je zadaný rune zařazen do kategorií jako velké písmeno.
IsValid(Int32)	Vrátí hodnotu, která označuje, zda 32bitové celé číslo se znaménkem představuje platnou skalární hodnotu Unicode; to znamená, že je v rozsahu [ U+0000..U+D7FF ], inclusive; nebo [ U+E000.. U+10FFFF ], včetně.
IsValid(UInt32)	Vrátí hodnotu, která označuje, zda 32bitové celé číslo bez znaménka představuje platnou skalární hodnotu Unicode; to znamená, že je v rozsahu [ U+0000..U+D7FF ], inclusive, nebo [ U+E000.. U+10FFFF ], včetně.
IsWhiteSpace(Rune)	Vrátí hodnotu, která určuje, zda je zadaný rune zařazen do kategorií jako prázdný znak.
ToLower(Rune, CultureInfo)	Vrátí kopii zadaného Rune převedeného na malá písmena pomocí pravidel velikostí písmen zadané jazykové verze.
ToLowerInvariant(Rune)	Vrátí kopii zadaného Rune převedeného na malá písmena pomocí pravidel malých písmen invariantní jazykové verze.
ToString()	Vrátí řetězcovou reprezentaci této Rune instance.
ToUpper(Rune, CultureInfo)	Vrátí kopii zadaného Rune převedeného na velká písmena pomocí pravidel velikostí písmen zadané jazykové verze.
ToUpperInvariant(Rune)	Vrátí kopii zadaného Rune převedeného na velká písmena pomocí pravidel velikostí písmen invariantní jazykové verze.
TryCreate(Char, Char, Rune)	Pokusí se vytvořit Rune ze zadané dvojice náhradních souborů UTF-16 a vrátí hodnotu, která označuje, zda byla operace úspěšná.
TryCreate(Char, Rune)	Pokusí se vytvořit ze zadaného znaku Rune hodnotu, která označuje, jestli operace proběhla úspěšně.
TryCreate(Int32, Rune)	Pokusí se Rune vytvořit ze zadaného podepsaného celého čísla, které představuje skalární hodnotu Unicode.
TryCreate(UInt32, Rune)	Pokusí se Rune vytvořit ze zadaného 32bitového celého čísla bez znaménka, které představuje skalární hodnotu Unicode.
TryEncodeToUtf16(Span<Char>, Int32)	Tento kód zakóduje Rune do cílové vyrovnávací paměti kódování UTF-16.
TryEncodeToUtf8(Span<Byte>, Int32)	Tento kód zakóduje Rune do cílové vyrovnávací paměti kódování UTF-8.
TryGetRuneAt(String, Int32, Rune)	Pokusí se získat Rune hodnotu, která začíná na zadané pozici v řetězci, a vrátí hodnotu, která označuje, jestli operace proběhla úspěšně.

Operátory

Name	Description
Equality(Rune, Rune)	Vrátí hodnotu, která určuje, zda jsou dvě Rune instance stejné.
Explicit(Char to Rune)	Definuje explicitní převod 16bitového znaku Unicode na Runeznak .
Explicit(Int32 to Rune)	Definuje explicitní převod 32bitového signed integer na Rune.
Explicit(UInt32 to Rune)	Definuje explicitní převod 32bitového celočíselného čísla bez znaménka na znak .Rune
GreaterThan(Rune, Rune)	Vrátí hodnotu určující, zda je zadaná Rune hodnota větší než jiná zadaná Runehodnota .
GreaterThanOrEqual(Rune, Rune)	Vrátí hodnotu určující, zda je zadaná Rune hodnota větší nebo rovna jinému zadanému .Rune
Inequality(Rune, Rune)	Vrátí hodnotu, která určuje, jestli mají dvě Rune instance různé hodnoty.
LessThan(Rune, Rune)	Vrátí hodnotu určující, zda je zadaná Rune hodnota menší než jiná zadaná Runehodnota .
LessThanOrEqual(Rune, Rune)	Vrátí hodnotu určující, zda je zadaná Rune hodnota menší nebo rovna jinému zadanému .Rune

Explicitní implementace rozhraní

Name	Description
IComparable.CompareTo(Object)	Porovná aktuální instanci se zadaným objektem.
IFormattable.ToString(String, IFormatProvider)	Naformátuje hodnotu aktuální instance pomocí zadaného formátu.
ISpanFormattable.TryFormat(Span<Char>, Int32, ReadOnlySpan<Char>, IFormatProvider)	Pokusí se naformátovat hodnotu aktuální instance do zadaného rozsahu znaků.
IUtf8SpanFormattable.TryFormat(Span<Byte>, Int32, ReadOnlySpan<Char>, IFormatProvider)	Pokusí se naformátovat hodnotu aktuální instance jako UTF-8 do poskytnutého rozsahu bajtů.
IUtf8SpanParsable<Rune>.Parse(ReadOnlySpan<Byte>, IFormatProvider)	Parsuje rozsah znaků UTF-8 do hodnoty.
IUtf8SpanParsable<Rune>.TryParse(ReadOnlySpan<Byte>, IFormatProvider, Rune)	Představuje skalární hodnotu Unicode ([ U+0000..U+D7FF ], inclusive; nebo [ U+E000.. U+10FFFF ], včetně).