Rune Structure

Référence

Définition

Espace de noms:: System.Text

Assembly:: System.Runtime.dll

Important

Certaines informations portent sur la préversion du produit qui est susceptible d’être en grande partie modifiée avant sa publication. Microsoft exclut toute garantie, expresse ou implicite, concernant les informations fournies ici.

Représente une valeur scalaire Unicode ([ U+0000..U+D7FF ], inclus ou [ U+E000..U+10FFFF ], inclus).

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

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

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

type Rune = struct
    interface ISpanFormattable
    interface IFormattable

type Rune = struct
    interface IFormattable
    interface ISpanFormattable

type Rune = struct
    interface IFormattable
    interface ISpanFormattable
    interface IUtf8SpanFormattable

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, IComparable(Of Rune), IEquatable(Of Rune), ISpanFormattable, IUtf8SpanFormattable

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

Héritage: Object

ValueType
Rune

Implémente: IComparable IComparable<Rune> IEquatable<Rune> IFormattable ISpanFormattable IUtf8SpanFormattable

Remarques

Une Rune instance représente une valeur scalaire Unicode, ce qui signifie tout point de code à l’exclusion de la plage de substitution (U+D800.). U+DFFF). Les constructeurs et opérateurs de conversion du type valident l’entrée, afin que les consommateurs puissent appeler les API en supposant que l’instance sous-jacente Rune est bien formée.

Si vous n’êtes pas familiarisé avec les termes valeur scalaire Unicode, point de code, plage de substitution et bien formé, consultez Présentation de l’encodage de caractères dans .NET.

Les sections suivantes expliquent :

Quand utiliser le type Rune
Quand ne pas utiliser le type Rune
Comment instancier une rune
Comment interroger les propriétés d’une instance Rune
Convertir un Rune en UTF-8 ou UTF-16
Exécuter dans .NET par rapport à d’autres langages

Quand utiliser le type Rune

Envisagez d’utiliser le Rune type si votre code :

Appelle des API qui nécessitent des valeurs scalaires Unicode
Gère explicitement les paires de substitution

API qui nécessitent des valeurs scalaires Unicode

Si votre code itère dans les char instances d’un string ou d’un ReadOnlySpan<char>, certaines méthodes char ne fonctionneront pas correctement sur char les instances qui se trouvent dans la plage de substitution. Par exemple, les API suivantes nécessitent une valeur char scalaire pour fonctionner correctement :

L’exemple suivant montre du code qui ne fonctionne pas correctement si l’une char des instances est des points de code de substitution :

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

Voici un code équivalent qui fonctionne avec :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;
}

Le code précédent fonctionne correctement avec certaines langues telles que l’anglais :

CountLettersInString("Hello")
// Returns 5

Mais cela ne fonctionnera pas correctement pour les langues en dehors du plan multilingue de base, comme Osage :

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

La raison pour laquelle cette méthode retourne des résultats incorrects pour le texte Osage est que les char instances de lettres Osage sont des points de code de substitution. Aucun point de code de substitution ne contient suffisamment d’informations pour déterminer s’il s’agit d’une lettre.

Si vous modifiez ce code pour l’utiliser Rune à la place de char, la méthode fonctionne correctement avec des points de code en dehors du plan multilingue de base :

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

Voici un code équivalent qui fonctionne avec :ReadOnlySpan<char>

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

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

    return letterCount;
}

Le code précédent compte correctement les lettres d’osage :

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

Code qui gère explicitement les paires de substitution

Envisagez d’utiliser le Rune type si votre code appelle des API qui fonctionnent explicitement sur des points de code de substitution, comme les méthodes suivantes :

Par exemple, la méthode suivante a une logique spéciale pour traiter les paires de substitution 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.");
        }
    }
}

Ce code est plus simple s’il utilise Rune, comme dans l’exemple suivant :

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

Quand ne pas utiliser `Rune`

Vous n’avez pas besoin d’utiliser le Rune type si votre code :

Recherche des correspondances exactes char
Fractionne une chaîne sur une valeur char connue

L’utilisation du Rune type peut renvoyer des résultats incorrects si votre code :

Compte le nombre de caractères d’affichage dans un string

Rechercher des correspondances exactes `char`

Le code suivant effectue une itération au sein d’une string recherche de caractères spécifiques, en retournant l’index de la première correspondance. Il n’est pas nécessaire de modifier ce code pour utiliser Rune, car le code recherche des caractères représentés par un seul 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
}

Fractionner une chaîne sur un connu `char`

Il est courant d’appeler string.Split et d’utiliser des délimiteurs tels que ' ' (espace) ou ',' (virgule), comme dans l’exemple suivant :

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

Il n’est pas nécessaire d’utiliser Rune ici, car le code recherche des caractères qui sont représentés par un seul char.

Compter le nombre de caractères affichés dans un `string`

Le nombre d’instances Rune d’une chaîne peut ne pas correspondre au nombre de caractères visibles par l’utilisateur lors de l’affichage de la chaîne.

Étant donné Rune que les instances représentent des valeurs scalaires Unicode, les composants qui suivent les instructions de segmentation de texte Unicode peuvent être utilisés Rune comme bloc de construction pour compter les caractères d’affichage.

Le StringInfo type peut être utilisé pour compter les caractères d’affichage, mais il ne compte pas correctement dans tous les scénarios pour les implémentations .NET autres que .NET 5+.

Pour plus d’informations, consultez Clusters Grapheme.

Comment instancier un `Rune`

Il existe plusieurs façons d’obtenir une Rune instance. Vous pouvez utiliser un constructeur pour créer un Rune directement à partir de :

Point de code.

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

Un seul char.
```
Rune c = new Rune('a');
```

Paire de substitution char .

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

Tous les constructeurs lèvent un ArgumentException si l’entrée ne représente pas une valeur scalaire Unicode valide.

Il existe Rune.TryCreate des méthodes disponibles pour les appelants qui ne souhaitent pas que des exceptions soient levées en cas d’échec.

Rune Les instances peuvent également être lues à partir de séquences d’entrée existantes. Par exemple, étant donné que représente des ReadOnlySpan<char> données UTF-16, la Rune.DecodeFromUtf16 méthode retourne la première Rune instance au début de l’étendue d’entrée. La Rune.DecodeFromUtf8 méthode fonctionne de la même façon, en acceptant un ReadOnlySpan<byte> paramètre qui représente des données UTF-8. Il existe des méthodes équivalentes à lire à partir de la fin de l’étendue au lieu du début de l’étendue.

Propriétés de requête d’un `Rune`

Pour obtenir la valeur de point de code entier d’une Rune instance, utilisez la Rune.Value propriété .

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

La plupart des API statiques disponibles sur le char type sont également disponibles sur le Rune type. Par exemple, Rune.IsWhiteSpace et Rune.GetUnicodeCategory sont équivalents aux Char.IsWhiteSpace méthodes et Char.GetUnicodeCategory . Les Rune méthodes gèrent correctement les paires de substitution.

L’exemple de code suivant prend un ReadOnlySpan<char> comme entrée et supprime à la fois le début et la fin de l’étendue qui Rune n’est pas une lettre ou un chiffre.

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

Il existe des différences d’API entre char et Rune. Exemple :

Il n’existe pas Rune d’équivalent à Char.IsSurrogate(Char), car Rune les instances par définition ne peuvent jamais être des points de code de substitution.
le Rune.GetUnicodeCategory ne retourne pas toujours le même résultat que Char.GetUnicodeCategory. Elle retourne la même valeur que CharUnicodeInfo.GetUnicodeCategory. Pour plus d’informations, consultez les remarques sur Char.GetUnicodeCategory.

Convertir un `Rune` en UTF-8 ou UTF-16

Étant donné qu’un Rune est une valeur scalaire Unicode, il peut être converti en encodage UTF-8, UTF-16 ou UTF-32. Le Rune type prend en charge la conversion en UTF-8 et UTF-16.

convertit Rune.EncodeToUtf16 une Rune instance en char instances. Pour interroger le nombre d’instances char qui résulteraient de la conversion d’une Rune instance en UTF-16, utilisez la Rune.Utf16SequenceLength propriété . Des méthodes similaires existent pour la conversion UTF-8.

L’exemple suivant convertit une Rune instance en tableau char . Le code suppose que vous avez une Rune instance dans la rune variable :

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

Étant donné qu’un string est une séquence de caractères UTF-16, l’exemple suivant convertit également une Rune instance en UTF-16 :

string theString = rune.ToString();

L’exemple suivant convertit une Rune instance en tableau d’octets UTF-8 :

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

Les Rune.EncodeToUtf16 méthodes et Rune.EncodeToUtf8 retournent le nombre réel d’éléments écrits. Ils lèvent une exception si la mémoire tampon de destination est trop courte pour contenir le résultat. Il existe également des méthodes et TryEncodeToUtf16 sans levée TryEncodeToUtf8 pour les appelants qui souhaitent éviter les exceptions.

Rune dans .NET par rapport à d’autres langages

Le terme « rune » n’est pas défini dans la norme Unicode. Le terme remonte à la création d’UTF-8. Rob Pike et Ken Thompson cherchaient un terme pour décrire ce qui allait devenir un point de code. Ils se sont fixés sur le terme « rune », et l’influence ultérieure de Rob Pike sur le langage de programmation Go a aidé à populariser le terme.

Toutefois, le type .NET Rune n’est pas l’équivalent du type Go rune . Dans Go, le rune type est un alias pour int32. Une rune Go est destinée à représenter un point de code Unicode, mais il peut s’agir de n’importe quelle valeur 32 bits, y compris les points de code de substitution et les valeurs qui ne sont pas des points de code Unicode légaux.

Pour des types similaires dans d’autres langages de programmation, consultez Le type primitif char de Rust ou le type SwiftUnicode.Scalar, qui représentent tous deux des valeurs scalaires Unicode. Ils fournissent des fonctionnalités similaires à . Le type de Rune NET et ils interdisent l’instanciation de valeurs qui ne sont pas des valeurs scalaires Unicode légales.

Constructeurs

Rune(Char)	Crée un Rune à partir de l’unité de code UTF-16 fournie.
Rune(Char, Char)	Crée un Rune à partir de la paire de substitution UTF-16 fournie.
Rune(Int32)	Crée un Rune à partir de l’entier 32 bits spécifié qui représente une valeur scalaire Unicode.
Rune(UInt32)	Crée un Rune à partir de l’entier 32 bits non signé spécifié qui représente une valeur scalaire Unicode.

Propriétés

IsAscii	Obtient une valeur qui indique si la valeur scalaire associée à ce Rune est comprise dans la plage d’encodage ASCII.
IsBmp	Obtient une valeur qui indique si la valeur scalaire associée à ce Rune est comprise dans la plage d’encodage BMP.
Plane	Obtient le plan Unicode (0 à 16, inclus) qui contient cette valeur scalaire.
ReplacementChar	Obtient une instance Rune qui représente le caractère de remplacement Unicode U+FFFD.
Utf16SequenceLength	Obtient la longueur en unités de code (Char) de la séquence UTF-16 nécessaire pour représenter cette valeur scalaire.
Utf8SequenceLength	Obtient la longueur en unités de code de la séquence UTF-8 nécessaire pour représenter cette valeur scalaire.
Value	Obtient la valeur scalaire Unicode sous la forme d’un entier.

Méthodes

CompareTo(Rune)	Compare l’instance actuelle à l’instance Rune spécifiée.
DecodeFromUtf16(ReadOnlySpan<Char>, Rune, Int32)	Décode Rune au début de la mémoire tampon source UTF-16 fournie.
DecodeFromUtf8(ReadOnlySpan<Byte>, Rune, Int32)	Décode Rune au début de la mémoire tampon source UTF-8 fournie.
DecodeLastFromUtf16(ReadOnlySpan<Char>, Rune, Int32)	Décode Rune à la fin de la mémoire tampon source UTF-16 fournie.
DecodeLastFromUtf8(ReadOnlySpan<Byte>, Rune, Int32)	Décode Rune à la fin de la mémoire tampon source UTF-8 fournie.
EncodeToUtf16(Span<Char>)	Encode ce Rune dans une mémoire tampon de destination au format UTF-16.
EncodeToUtf8(Span<Byte>)	Encode ce Rune dans une mémoire tampon de destination au format UTF-8.
Equals(Object)	Retourne une valeur qui indique si l'instance actuelle et un objet spécifié sont égaux.
Equals(Rune)	Retourne une valeur qui indique si l'instance actuelle et un Rune spécifié sont égaux.
GetHashCode()	Retourne le code de hachage de cette instance.
GetNumericValue(Rune)	Obtient la valeur numérique associée au Rune spécifié.
GetRuneAt(String, Int32)	Obtient le Rune qui commence à une position spécifiée dans une chaîne.
GetUnicodeCategory(Rune)	Obtient la catégorie Unicode associée au Rune spécifié.
IsControl(Rune)	Retourne une valeur qui indique si le Rune spécifié est classé dans la catégorie des caractères de contrôle.
IsDigit(Rune)	Retourne une valeur qui indique si le Rune spécifié est classé dans la catégorie des chiffres décimaux.
IsLetter(Rune)	Retourne une valeur qui indique si le Rune spécifié est classé dans la catégorie des lettres.
IsLetterOrDigit(Rune)	Retourne une valeur qui indique si le Rune spécifié est classé dans la catégorie des lettres ou des chiffres décimaux.
IsLower(Rune)	Retourne une valeur qui indique si le Rune spécifié est classé dans la catégorie des lettres minuscules.
IsNumber(Rune)	Retourne une valeur qui indique si le Rune spécifié est classé dans la catégorie des nombres.
IsPunctuation(Rune)	Retourne une valeur qui indique si le Rune spécifié est classé dans la catégorie des signes de ponctuation.
IsSeparator(Rune)	Retourne une valeur qui indique si le Rune spécifié est classé dans la catégorie des caractères de séparation.
IsSymbol(Rune)	Retourne une valeur qui indique si le Rune spécifié est classé dans la catégorie des symboles.
IsUpper(Rune)	Retourne une valeur qui indique si le Rune spécifié est classé dans la catégorie des lettres majuscules.
IsValid(Int32)	Retourne une valeur qui indique si un entier signé 32 bits représente une valeur scalaire Unicode valide, c’est-à-dire, comprise dans la plage [ U+0000..U+D7FF ], inclus ou [ U+E000..U+10FFFF ], inclus.
IsValid(UInt32)	Retourne une valeur qui indique si un entier non signé 32 bits représente une valeur scalaire Unicode valide, c’est-à-dire, comprise dans la plage [ U+0000..U+D7FF ], inclus ou [ U+E000..U+10FFFF ], inclus.
IsWhiteSpace(Rune)	Retourne une valeur qui indique si le Rune spécifié est classé dans la catégorie des caractères d’espace blanc.
ToLower(Rune, CultureInfo)	Retourne une copie du Rune spécifié converti en minuscules, à l’aide des règles de casse de la culture spécifiée.
ToLowerInvariant(Rune)	Retourne une copie du Rune spécifié converti en minuscules à l’aide des règles de casse de la culture invariante.
ToString()	Retourne la représentation sous forme de chaîne de cette instance Rune.
ToUpper(Rune, CultureInfo)	Retourne une copie du Rune spécifié converti en majuscules, à l’aide des règles de casse de la culture spécifiée.
ToUpperInvariant(Rune)	Retourne une copie du Rune spécifié converti en majuscules à l’aide des règles de casse de la culture invariante.
TryCreate(Char, Char, Rune)	Tente de créer un Rune à partir de la paire de substitution UTF-16 spécifiée et retourne une valeur qui indique si l’opération a réussi.
TryCreate(Char, Rune)	Tente de créer un Rune à partir d’un caractère spécifié et retourne une valeur qui indique si l’opération a réussi.
TryCreate(Int32, Rune)	Tente de créer un Rune à partir d’un entier signé spécifié qui représente une valeur scalaire Unicode.
TryCreate(UInt32, Rune)	Tente de créer un Rune à partir d’un entier 32 bits non signé spécifié qui représente une valeur scalaire Unicode.
TryEncodeToUtf16(Span<Char>, Int32)	Encode ce Rune dans une mémoire tampon de destination au format UTF-16.
TryEncodeToUtf8(Span<Byte>, Int32)	Encode ce Rune dans une mémoire tampon de destination au format UTF-8.
TryGetRuneAt(String, Int32, Rune)	Tente d’obtenir le Rune qui commence à une position spécifiée dans une chaîne et retourne une valeur qui indique si l’opération a réussi.

Opérateurs

Equality(Rune, Rune)	Retourne une valeur qui indique si deux instances de Rune sont égales.
Explicit(Char to Rune)	Définit une conversion explicite d’un caractère Unicode 16 bits en Rune.
Explicit(Int32 to Rune)	Définit une conversion explicite d’un entier signé 32 bits en Rune.
Explicit(UInt32 to Rune)	Définit une conversion explicite d’un entier non signé 32 bits en Rune.
GreaterThan(Rune, Rune)	Retourne une valeur indiquant si un Rune spécifié est supérieur à un autre Rune spécifié.
GreaterThanOrEqual(Rune, Rune)	Retourne une valeur indiquant si un Rune spécifié est supérieur ou égal à un autre Rune spécifié.
Inequality(Rune, Rune)	Retourne une valeur qui indique si deux instances Rune ont des valeurs différentes.
LessThan(Rune, Rune)	Retourne une valeur indiquant si un Rune spécifié est inférieur à un autre Rune spécifié.
LessThanOrEqual(Rune, Rune)	Retourne une valeur indiquant si un Rune spécifié est inférieur ou égal à un autre Rune spécifié.

Implémentations d’interfaces explicites

IComparable.CompareTo(Object)	Compare l’instance actuelle à l’objet spécifié.
IFormattable.ToString(String, IFormatProvider)	Met en forme la valeur de l’instance actuelle en utilisant le format spécifié.
ISpanFormattable.TryFormat(Span<Char>, Int32, ReadOnlySpan<Char>, IFormatProvider)	Tente de mettre en forme la valeur de l’instance actuelle dans l’étendue de caractères fournie.
IUtf8SpanFormattable.TryFormat(Span<Byte>, Int32, ReadOnlySpan<Char>, IFormatProvider)	Représente une valeur scalaire Unicode ([ U+0000..U+D7FF ], inclus ou [ U+E000..U+10FFFF ], inclus).

S’applique à