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 struct Rune : IComparable, IComparable<System.Text.Rune>, IEquatable<System.Text.Rune>
public struct Rune : IComparable, IComparable<System.Text.Rune>, IEquatable<System.Text.Rune>, ISpanFormattable
public struct Rune : IComparable<System.Text.Rune>, IEquatable<System.Text.Rune>
type Rune = struct
type Rune = struct
    interface ISpanFormattable
    interface IFormattable
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)。 型のコンストラクターと変換演算子は入力を検証します。そのため、コンシューマーは、基になるインスタンスの整形を想定して API Rune を呼び出すことができます。

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

次のセクションでは、以下について説明します。

Rune 型を使用する場合

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

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

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

コードが または のインスタンスを反復処理する場合、一部のメソッドはサロゲート範囲内のインスタンスで正 char string ReadOnlySpan<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;
}

で動作する同等のコードを次に示します 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 文字のインスタンスがサロゲート コード ポイント char だからです。 1 つのサロゲート コード ポイントに、それが文字かどうかを判断するのに十分な情報はありません。

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

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

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

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

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

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

完全一致を char 検索する

次のコードは、特定の文字を string 検索して反復処理し、最初の一致のインデックスを返します。 コードは 1 つの で表される文字を探すので、 を使用するためにこのコードを変更 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(',');

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

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

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

インスタンスは Unicode スカラー値を表すので、Unicode テキストのセグメント化ガイドラインに従うコンポーネントは、表示文字をカウントする構成要素 Rune Rune としてを使用できます。

型を使用して表示文字をカウントできますが、.NET 5 以外の .NET の実装では、すべてのシナリオで正しく StringInfo カウントされません。

詳細については 、「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 スカラー値を表す場合、すべてのコンストラクターは ArgumentException をスローします。

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

Rune インスタンスは、既存の入力シーケンスから読み取る場合も可能です。 たとえば、UTF-16 データを表す を指定すると、 メソッドは入力スパンの先頭にある最初の ReadOnlySpan<char> 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)

型で使用できる静的 API の多 char くは、 型でも使用 Rune できます。 たとえば、 と Rune.IsWhiteSpace Rune.GetUnicodeCategory は メソッドと同等 Char.IsWhiteSpace Char.GetUnicodeCategory です。 メソッド 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;
}

と には、いくつかの API の違 char いがあります Rune 。 次に例を示します。

Rune UTF-8 または UTF-16 に変換する

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

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

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

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

は UTF-16 文字のシーケンスです。次の例では、 インスタンスも string Rune UTF-16 に変換されます。

string theString = rune.ToString();

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

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

メソッド Rune.EncodeToUtf16Rune.EncodeToUtf8 メソッドは、書き込まれた要素の実際の数を返します。 宛先バッファーが短すぎて結果を含めなかった場合、例外がスローされます。 例外を回避する呼び出し元には、スロー以外の メソッド TryEncodeToUtf8 EncodeToUtf16 と メソッドもあります。

.NET の Rune と他の言語

"rune" という用語は、Unicode 標準では定義されていません。 この用語は 、UTF-8 の作成にまで戻っています。 Rob Pike と Ken Tompson は、最終的にコード ポイントとして知られるものについて説明する用語を探しました。 彼らは "rune" という用語に落ち着き、後で Go プログラミング言語に対する Rob Pike の影響は、この用語の一般的化に役立ちます。

ただし、.NET 型 Rune は Go 型と同等 rune ではありません。 Go では、 型 rune は のエイリアス int32 です。 Go ルーンは、Unicode コード ポイントを表す目的ですが、サロゲート コード ポイントや、Unicode コード ポイントとして使用できない値を含め、任意の 32 ビット値を指定できます。

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

コンストラクター

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)

現在のインスタンスの値を指定された文字スパンに書式設定します。

適用対象