Rune 結構

定義

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

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

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

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

public readonly struct 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>, IParsable<System.Text.Rune>, ISpanFormattable, ISpanParsable<System.Text.Rune>, IUtf8SpanFormattable, IUtf8SpanParsable<System.Text.Rune>

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

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

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

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

type Rune = struct
    interface IFormattable
    interface ISpanFormattable
    interface IUtf8SpanFormattable

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

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

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

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

繼承

Object

ValueType

Rune

實作

IComparable IComparable<Rune> IEquatable<Rune> IFormattable ISpanFormattable IUtf8SpanFormattable IUtf8SpanParsable<Rune> IParsable<Rune> IParsable<TSelf> ISpanParsable<Rune>

備註

Rune實例代表 Unicode 純量值，這表示它是任何不在代理區間（U+D800..U+DFFF）內的碼點。 型態的建構子與轉換運算子會驗證輸入，因此消費者可以假設底層 Rune 實例是良好形式而呼叫 API。

如果您不熟悉 Unicode 純量值、碼位、代理範圍和格式正確性，請參閱 .NET 中的字元編碼簡介。

使用 Rune 類型的時機

如果您的程式代碼滿足Rune類型，請考慮使用：

• 呼叫需要 Unicode 純量值的 API
• 明確處理代理字組

需要 Unicode 純量值的 API

如果您的程式代碼逐一遍歷char或string中的ReadOnlySpan<char>實例的話，某些char方法將無法在代理範圍內的char實例上正確運作。 例如，下列 API 需要純量值 char 才能正常運作：

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

下列範例顯示如果任何char 實例是代理代碼點，程式碼將無法正確運行：

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

以下是適用於 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;
}

上述程式代碼適用於某些語言，例如英文：

CountLettersInString("Hello")
// Returns 5

但它不適用於基本多語平面以外的語言，例如 Osage：

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

此方法對 Osage 文字傳回不正確結果的原因是，Osage 字母的實例是代理碼點。 沒有單一代用字元碼點有足夠的信息來判斷其是否為字母。

如果您將此程式碼從使用Rune改為使用char，此方法可以正確地處理超出基本多語平面的程式碼點：

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

以下是適用於 ReadOnlySpan<char>的對等程式代碼：

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

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

    return letterCount;
}

上述程式代碼會正確計算 Osage 字母：

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

明確處理代理字組的程序代碼

如果您的程式碼呼叫明確在代理碼位上操作的 API，請考慮使用 Rune 類型，例如下列方法：

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

例如，下列方法具有處理代理 char 配對的特殊邏輯：

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

如果這類程式代碼使用 Rune，則比較簡單，如下列範例所示：

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

何時不使用 Rune

如果您的程式代碼， 您不需要使用 Rune 類型：

• 尋找完全 char 相符的匹配項目
• 在已知的 char 值上分割字串

如果您的代碼使用Rune類型，可能會返回不正確的結果：

• 計算 string 中顯示字元的數目

尋找完全相符的 char 項目

下列程式碼會對 string 進行迭代，尋找特定字元，並傳回第一個匹配的索引。 不需要變更此程式代碼來使用 Rune，因為程式代碼正在尋找以單 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
}

在已知的char上分割字串

常常呼叫 string.Split 並使用分隔符，例如 ' ' （空格） 或 ',' （逗號），這是很常見的做法，如下列範例所示：

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

這裡不需要使用 Rune ，因為程式代碼正在尋找以單 char一 表示的字元。

計算string中的顯示字元數量

字串中的實例數目 Rune 可能不符合顯示字串時所顯示的使用者感知字元數目。

由於 Rune 實例代表 Unicode 純量值，因此遵循 Unicode 文字分割指導方針的 元件可用來 Rune 做為計算顯示字元的建置元件。

此 StringInfo 類型可用來計算顯示字符，但在 .NET 5+ 以外的其他 .NET 實作中，無法正確計算。

如需詳細資訊，請參閱 Grapheme 叢集。

如何實例化 Rune

有數種方式可以取得 Rune 實例。 您可以使用建構函式直接從以下來源建立 Rune：

• 碼位。

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

• 單一 char。

  Rune c = new Rune('a');
  

• 代理 char 字組。

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

如果輸入不代表有效的 Unicode 純量值，則所有建構函式都會擲回 ArgumentException 。

呼叫端有多個 Rune.TryCreate 方法可用，以避免在失敗時擲回例外狀況。

Rune 實例也可以從現有的輸入序列讀取。 例如，假設有 ReadOnlySpan<char> 代表UTF-16數據的 ，此方法 Rune.DecodeFromUtf16 會在輸入範圍開頭傳回第一個 Rune 實例。 方法 Rune.DecodeFromUtf8 的運作方式類似，接受 ReadOnlySpan<byte> 代表UTF-8數據的參數。 有等效的方法可以從範圍的結尾讀取，而不是從範圍的開頭讀取。

查詢Rune的屬性

若要取得 實例的 Rune 整數代碼點值，請使用 Rune.Value 屬性。

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

類型上 char 可用的許多靜態 API 也可用於 Rune 類型。 例如， Rune.IsWhiteSpace 和 Rune.GetUnicodeCategory 相當於 Char.IsWhiteSpace 和 Char.GetUnicodeCategory 方法。 Rune方法可正確處理 Surrogate 字組。

下列範例程式碼會接受 ReadOnlySpan<char> 作為輸入，並從範圍的起始和結尾修剪每個不是字母或數字的 Rune。

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

char 和 Rune 之間有一些 API 差異。 例如：

• 沒有 Rune 與 相等的 Char.IsSurrogate(Char)，因為 Rune 根據定義實例永遠不能是代理程式代碼點。
• Rune.GetUnicodeCategory不一定會傳回與 Char.GetUnicodeCategory相同的結果。 它會傳回與 CharUnicodeInfo.GetUnicodeCategory相同的值。 如需詳細資訊，請參閱Char.GetUnicodeCategory。

將Rune轉換為UTF-8或UTF-16

Rune由於 是 Unicode 純量值，因此可以轉換成 UTF-8、UTF-16 或 UTF-32 編碼。 此 Rune 類型內建支持轉換成UTF-8和UTF-16。

Rune.EncodeToUtf16 將 Rune 實例轉換成 char 實例。 若要查詢將 char 實例轉換成 UTF-16 所產生的實例數目，請使用 Rune 屬性。 UTF-8 轉換也有類似的方法。

下列範例會將 Rune 實例 char 轉換成陣列。 程式假設您在 Rune 變數中有一個 rune 實例。

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

string由於 是UTF-16字元序列，因此下列範例也會將 實例轉換成 Rune UTF-16：

string theString = rune.ToString();

下列範例會將 Rune 實體 UTF-8 轉換成位元組數組：

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

Rune.EncodeToUtf16和 Rune.EncodeToUtf8 方法會傳回寫入之項目的實際數目。 如果目的地緩衝區太短而無法包含結果，它們就會擲回例外狀況。 對於想要避免例外狀況的呼叫端，也有非擲回 TryEncodeToUtf8 和 TryEncodeToUtf16 方法。

.NET 中的 Rune 與其他語言

“rune” 一詞未定義於 Unicode 標準中。 此詞彙可追溯到 UTF-8的建立。 羅布·派克和肯·湯普森正在尋找一個詞彙，以描述最終會被稱為代碼點的內容。 他們最終定名為「符文」，而 Rob Pike 後來對 Go 程式語言的影響，幫助這個詞的普及。

不過，.NET Rune 類型與 Go rune 類型不相等。 在 Go 中，rune 類型是 int32 的 別名。 Go rune 的目的是要代表 Unicode 字碼點，但它可以是任何 32 位值，包括代理字碼點和不是合法 Unicode 字碼點的值。

如需其他程式設計語言中的類似類型，請參閱 Rust 的基本 char 類型 或 Swift Unicode.Scalar 的類型，這兩者都代表 Unicode 純量值。 它們提供的功能與 .NET 的 Rune 類型相似，並且禁止實例化非合法的 Unicode 純量值。