Rune 構造体

定義

Unicode スカラー値 ([ U+0000..U+D7FF ] (最初と最後の要素を含む) または [ U+E000..U+10FFFF ] (最初と最後の要素を含む)) を表します。

public value class Rune : IComparable, IComparable<System::Text::Rune>, IEquatable<System::Text::Rune>
public value class Rune : IComparable, IComparable<System::Text::Rune>, IEquatable<System::Text::Rune>, ISpanFormattable
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>
public readonly struct Rune : IComparable, IComparable<System.Text.Rune>, IEquatable<System.Text.Rune>, ISpanFormattable
public readonly struct Rune : IComparable<System.Text.Rune>, IEquatable<System.Text.Rune>
type Rune = struct
type Rune = struct
    interface ISpanFormattable
    interface IFormattable
type Rune = struct
    interface IFormattable
    interface ISpanFormattable
Public Structure Rune
Implements IComparable, IComparable(Of Rune), IEquatable(Of Rune)
Public Structure Rune
Implements IComparable, IComparable(Of Rune), IEquatable(Of Rune), ISpanFormattable
Public Structure Rune
Implements IComparable(Of Rune), IEquatable(Of Rune)
継承
実装

注釈

インスタンスは Rune Unicode スカラー値を表します。これは、サロゲート範囲 (U+D800..U+DFFF)。 型のコンストラクターと変換演算子は入力を検証するため、コンシューマーは基になる Rune インスタンスが整形式であると仮定して API を呼び出すことができます。

Unicode スカラー値、コード ポイント、サロゲート範囲、および整形式の用語に慣れていない場合は、「 .NET での文字エンコードの概要」を参照してください。

次のセクションでは、次の説明を行います。

Rune 型を使用する場合

コードが次の場合は、型の Rune 使用を検討してください。

  • Unicode スカラー値を必要とする API を呼び出す
  • サロゲート ペアを明示的に処理する

Unicode スカラー値を必要とする API

コードが a または ReadOnlySpan<char>a string のインスタンスをchar反復処理する場合、サロゲート範囲内のインスタンスでchar一部のcharメソッドが正しく動作しません。 たとえば、次の API では、スカラー値 char が正しく機能する必要があります。

次の例は、いずれかのインスタンスがサロゲート コード ポイントの場合に 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 など、Basic 多言語プレーン以外の言語では正しく機能しません。

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

このメソッドが Osage テキストの正しくない結果を返す理由は、Osage 文字のインスタンスがサロゲート コード ポイントであるため char です。 文字かどうかを判断するのに十分な情報を持つサロゲート コード ポイントは 1 つもありません。

代わりにchar使用Runeするようにこのコードを変更すると、メソッドは Basic 多言語プレーンの外部のコード ポイントで正しく機能します。

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 ペアを処理するための特別なロジックがあります。

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 致を検索します
  • 既知の文字値で文字列を分割します

コードが次の場合、型を Rune 使用すると正しくない結果が返される可能性があります。

  • 内の表示文字数をカウントします。 string

完全一 char 致を探す

次のコードでは、特定の文字の検索を string 反復処理し、最初の一致のインデックスを返します。 コードは単一charの文字で表される文字を探していますので、このコードを使用Runeするように変更する必要はありません。

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(',');

コードは 1 つのchar文字で表される文字を探しているため、ここでは使用Runeする必要はありません。

内の表示文字数をカウントします。 string

文字列内のインスタンスの Rune 数が、文字列を表示するときに表示されるユーザーが認識できる文字の数と一致しない可能性があります。

インスタンスは Unicode スカラー値を表しているため RuneUnicode テキストセグメント化ガイドライン に従うコンポーネントは、表示文字をカウントするための構成要素として使用 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
    
  • 1つの char

    Rune c = new Rune('a');
    
  • サロゲート char ペア。

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

すべてのコンストラクターは、入力が有効な Unicode スカラー値を表していない場合に an ArgumentException をスローします。

エラー発生時に Rune.TryCreate 例外をスローしたくない呼び出し元に使用できるメソッドがあります。

Rune インスタンスは、既存の入力シーケンスから読み取ることもできます。 たとえば、UTF-16 データを表す a ReadOnlySpan<char> を指定すると、メソッドは Rune.DecodeFromUtf16 入力スパンの先頭にある最初 Rune のインスタンスを返します。 このメソッドも Rune.DecodeFromUtf8 同様に動作し、UTF-8 データを ReadOnlySpan<byte> 表すパラメーターを受け取ります。 スパンの先頭ではなく、スパンの末尾から読み取る同等のメソッドがあります。

のクエリ プロパティ 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.GetUnicodeCategoryChar.GetUnicodeCategory同等Char.IsWhiteSpaceです。 メソッドは Rune サロゲート ペアを正しく処理します。

次のコード例では、入力として受 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. 次に例を示します。

A Rune から UTF-8 または UTF-16 への変換

a Rune は Unicode スカラー値であるため、UTF-8、UTF-16、または UTF-32 エンコードに変換できます。 この Rune 型には、UTF-8 および UTF-16 への変換が組み込まれています。

Rune.EncodeToUtf16インスタンスをRuneインスタンスにchar変換します。 インスタンスを UTF-16 に変換した結果として発生するRuneインスタンスのchar数を照会するには、このプロパティをRune.Utf16SequenceLength使用します。 UTF-8 変換にも同様のメソッドが存在します。

次の例では、インスタンスを Rune 配列に char 変換します。 このコードでは、変数に Rune インスタンス rune があることを前提としています。

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

a string は UTF-16 文字のシーケンスであるため、次の例ではインスタンスも UTF-16 に変換 Rune します。

string theString = rune.ToString();

次の例では、インスタンスを Rune バイト配列に UTF-8 変換します。

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

and Rune.EncodeToUtf8 メソッドはRune.EncodeToUtf16、書き込まれた実際の要素数を返します。 宛先バッファーが短すぎて結果が格納されなければ、例外がスローされます。 例外を TryEncodeToUtf8 回避する呼び出し EncodeToUtf16 元には、スローおよびメソッドはありません。

.NET でのルーンと他の言語の比較

"rune" という用語は Unicode 標準では定義されていません。 用語は UTF-8 の作成に遡ります。 Rob Pike と Ken Thompson は、最終的に何がコード ポイントとして知られるかを説明する用語を探していました。 彼らは「ルーン」という用語に落ち着き、後にGoプログラミング言語に対するロブ・パイクの影響が用語の普及に役立ちました。

ただし、.NET Rune 型は Go rune 型と同等ではありません。 Go では、型runeint32. Go ルーンは Unicode コード ポイントを表すことを目的としていますが、サロゲート コード ポイントや有効な Unicode コード ポイントではない値など、任意の 32 ビット値を指定できます。

他のプログラミング言語の同様の型については、 Rust のプリミティブ char または Swift の Unicode.Scalarを参照してください。どちらも Unicode スカラー値を表します。 これらは、次のような機能を提供します。NET の Rune 型であり、有効な Unicode スカラー値ではない値のインスタンス化を禁止します。

コンストラクター

Rune(Char)

指定された UTF-16 コード単位から Rune を作成します。

Rune(Char, Char)

指定された UTF-16 サロゲート ペアから Rune を作成します。

Rune(Int32)

Unicode スカラー値を表す、指定された 32 ビット整数から Rune を作成します。

Rune(UInt32)

Unicode スカラー値を表す、指定された符号なし 32 ビット整数から Rune を作成します。

プロパティ

IsAscii

この Rune に関連付けられているスカラー値が ASCII エンコード範囲内であるかどうかを示す値を取得します。

IsBmp

この Rune に関連付けられているスカラー値が BMP エンコード範囲内であるかどうかを示す値を取得します。

Plane

このスカラーを含む Unicode 平面 (0 から 16 まで、0 と 16 を含む) を取得します。

ReplacementChar

Unicode 置換文字 U+FFFD を表す Rune インスタンスを取得します。

Utf16SequenceLength

このスカラー値を表すために必要な UTF-16 シーケンスのコード単位 (Char) の長さを取得します。

Utf8SequenceLength

このスカラー値を表すために必要な UTF-8 シーケンスのコード単位の長さを取得します。

Value

Unicode スカラー値を整数として取得します。

メソッド

CompareTo(Rune)

現在のインスタンスを、指定された Rune インスタンスと比較します。

DecodeFromUtf16(ReadOnlySpan<Char>, Rune, Int32)

指定された UTF-16 ソース バッファーの先頭で Rune を復号します。

DecodeFromUtf8(ReadOnlySpan<Byte>, Rune, Int32)

指定された UTF-8 ソース バッファーの先頭で Rune を復号します。

DecodeLastFromUtf16(ReadOnlySpan<Char>, Rune, Int32)

指定された UTF-16 ソース バッファーの末尾で Rune を復号します。

DecodeLastFromUtf8(ReadOnlySpan<Byte>, Rune, Int32)

指定された UTF-8 ソース バッファーの末尾で Rune を復号します。

EncodeToUtf16(Span<Char>)

この Rune を UTF-16 ターゲット バッファーにエンコードします。

EncodeToUtf8(Span<Byte>)

この Rune をエンコードし、UTF-8 ターゲット バッファーに書き込みます。

Equals(Object)

現在のインスタンスと、指定されたオブジェクトが等しいかどうかを示す値を返します。

Equals(Rune)

現在のインスタンスと指定されたルーンが等しいかどうかを示す値を返します。

GetHashCode()

このインスタンスのハッシュ コードを返します。

GetNumericValue(Rune)

指定されたルーンに関連付けられている数値を取得します。

GetRuneAt(String, Int32)

文字列において指定された位置から始まる Rune を取得します。

GetUnicodeCategory(Rune)

指定されたルーンに関連付けられている Unicode カテゴリを取得します。

IsControl(Rune)

指定されたルーンが制御文字として分類されているかどうかを示す値を返します。

IsDigit(Rune)

指定されたルーンが 10 進数の数字として分類されているかどうかを示す値を返します。

IsLetter(Rune)

指定されたルーンが文字として分類されているかどうかを示す値を返します。

IsLetterOrDigit(Rune)

指定されたルーンが文字または 10 進数の数字として分類されているかどうかを示す値を返します。

IsLower(Rune)

指定されたルーンが小文字として分類されているかどうかを示す値を返します。

IsNumber(Rune)

指定されたルーンが数字として分類されているかどうかを示す値を返します。

IsPunctuation(Rune)

指定されたルーンが区切り記号として分類されているかどうかを示す値を返します。

IsSeparator(Rune)

指定されたルーンが区切り文字として分類されているかどうかを示す値を返します。

IsSymbol(Rune)

指定されたルーンが記号として分類されているかどうかを示す値を返します。

IsUpper(Rune)

指定されたルーンが大文字として分類されているかどうかを示す値を返します。

IsValid(Int32)

32 ビットの符号付き整数が有効な Unicode スカラー値、すなわち、[ U+0000..U+D7FF ] (最初と最後の要素を含む) または [ U+E000..U+10FFFF ] (最初と最後の要素を含む) という範囲内にあるかどうかを示す値を返します。

IsValid(UInt32)

32 ビットの符号なし整数が有効な Unicode スカラー値、すなわち、[ U+0000..U+D7FF ] (最初と最後の要素を含む) または [ U+E000..U+10FFFF ] (最初と最後の要素を含む) という範囲内にあるかどうかを示す値を返します。

IsWhiteSpace(Rune)

指定されたルーンが空白文字として分類されているかどうかを示す値を返します。

ToLower(Rune, CultureInfo)

指定されたカルチャの大文字と小文字の規則を使用して、指定された Rune のコピーを小文字に変換して返します。

ToLowerInvariant(Rune)

インバリアント カルチャの大文字と小文字の規則を使用して、指定された Rune のコピーを小文字に変換して返します。

ToString()

この Rune オブジェクトの文字列表現を返します。

ToUpper(Rune, CultureInfo)

指定されたカルチャの大文字と小文字の規則を使用して、指定された Rune のコピーを大文字に変換して返します。

ToUpperInvariant(Rune)

インバリアント カルチャの大文字と小文字の規則を使用して、指定された Rune のコピーを大文字に変換して返します。

TryCreate(Char, Char, Rune)

指定された UTF-16 サロゲート ペアから Rune の作成を試し、操作が成功したかどうかを示す値を返します。

TryCreate(Char, Rune)

指定された文字から Rune の作成を試し、操作が成功したかどうかを示す値を返します。

TryCreate(Int32, Rune)

Unicode スカラー値を表す指定された符号付き整数から Rune の作成を試します。

TryCreate(UInt32, Rune)

Unicode スカラー値を表す、指定された符号付き 32 ビット整数から Rune の作成を試します。

TryEncodeToUtf16(Span<Char>, Int32)

この Rune を、UTF-16 でエンコードされたターゲット バッファーにエンコードします。

TryEncodeToUtf8(Span<Byte>, Int32)

この Rune を、UTF-8 でエンコードされたターゲット バッファーにエンコードします。

TryGetRuneAt(String, Int32, Rune)

文字列において指定された位置から始まる Rune の取得を試し、操作が成功したかどうかを示す値を返します。

演算子

Equality(Rune, Rune)

2 つの Rune インスタンスが等しいかどうかを示す値を返します。

Explicit(Char to Rune)

16 ビットの Unicode 文字の Rune への明示的な変換を定義します。

Explicit(Int32 to Rune)

32 ビット符号付き整数の Rune への明示的な変換を定義します。

Explicit(UInt32 to Rune)

32 ビット符号なし整数の Rune への明示的な変換を定義します。

GreaterThan(Rune, Rune)

指定した Rune が、指定した別の Rune より大きいかどうかを示す値を返します。

GreaterThanOrEqual(Rune, Rune)

指定した Rune が、指定した別の Rune 以上かどうかを示す値を返します。

Inequality(Rune, Rune)

2 つの Rune インスタンスの値が異なるかどうかを示す値を返します。

LessThan(Rune, Rune)

指定した Rune が、指定した別の Rune より小さいかどうかを示す値を返します。

LessThanOrEqual(Rune, Rune)

指定した Rune が、指定したもう 1 つの Rune 以下であるかどうかを示す値を返します。

明示的なインターフェイスの実装

IComparable.CompareTo(Object)

現在のインスタンスを、指定したオブジェクトと比較します。

IFormattable.ToString(String, IFormatProvider)

指定された書式を使用して現在のインスタンスの値を書式設定します。

ISpanFormattable.TryFormat(Span<Char>, Int32, ReadOnlySpan<Char>, IFormatProvider)

現在のインスタンスの値を指定された文字数範囲に書式設定しようとします。

適用対象