Rune 構造体

定義

名前空間:

System.Text

アセンブリ:

System.Runtime.dll

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

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

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

type Rune = struct
    interface IFormattable
    interface ISpanFormattable
    interface IUtf8SpanFormattable

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

継承

Object

ValueType

Rune

実装

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

注釈

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

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

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

• Rune 型を使用する場合
• Rune 型を使用しない場合
• Rune をインスタンス化する方法
• Rune インスタンスのプロパティに対してクエリを実行する方法
• を Rune UTF-8 または UTF-16 に変換する
• .NET でのルーンと他の言語の比較

Rune 型を使用する場合

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

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

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

コードが または ReadOnlySpan<char>のstringインスタンスを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 など、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

サロゲート ペアを明示的に処理するコード

次の Rune メソッドなど、サロゲート コード ポイントを明示的に操作する API をコードが呼び出す場合は、 型の使用を検討してください。

• 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 反復処理し、最初の一致のインデックスを返します。 コードは 1 つの 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 スカラー値を表すの Rune で、 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
  

• 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 同様に動作し、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)

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

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

• 定義上のインスタンスをサロゲート コード ポイントにすることは決してできないため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 変換します。 インスタンスを UTF-16 に変換した結果として発生するRuneインスタンスのchar数を照会するには、 プロパティをRune.Utf16SequenceLength使用します。 UTF-8 変換にも同様のメソッドが存在します。

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

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

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

string theString = rune.ToString();

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

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

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

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

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

ただし、.NET Rune 型は Go rune 型と同等ではありません。 Go では、型runeは のint32エイリアスです。 Go rune は 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)	現在のインスタンスの値を、指定された文字数のスパンに書式設定しようとします。
IUtf8SpanFormattable.TryFormat(Span<Byte>, Int32, ReadOnlySpan<Char>, IFormatProvider)	現在のインスタンスの値を UTF-8 として指定されたバイトスパンに書式設定しようとします。