Rune Structure
Définition
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<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)
- Héritage
- Implémente
Remarques
Une Rune instance représente une valeur scalaire Unicode, ce qui signifie tout point de code excluant 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 la valeur scalaire Unicode, le point de code, la 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 d’exécution
- Quand ne pas utiliser le type d’exécution
- Comment instancier un rune
- Comment interroger les propriétés d’une instance Rune
- Convertir un
Rune
en UTF-8 ou UTF-16 - Rune dans .NET et d’autres langages
Quand utiliser le type d’exécution
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 via les char
instances d’un ou d’un string
ReadOnlySpan<char>
, certaines des char
méthodes ne fonctionnent 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 :
- Char.GetNumericValue
- Char.GetUnicodeCategory
- Char.IsDigit
- Char.IsLetter
- Char.IsLetterOrDigit
- Char.IsLower
- Char.IsNumber
- Char.IsPunctuation
- Char.IsSymbol
- Char.IsUpper
L’exemple suivant montre le code qui ne fonctionnera pas correctement si l’une des instances est des points de char
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 un 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 des lettres Osage sont des points de code de substitution. Aucun point de code de substitution unique n’a suffisamment d’informations pour déterminer s’il s’agit d’une lettre.
Si vous modifiez ce code à utiliser Rune
au lieu de , la méthode fonctionne correctement avec des points de char
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 un 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 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 :
- Char.IsSurrogate
- Char.IsSurrogatePair
- Char.IsHighSurrogate
- Char.IsLowSurrogate
- Char.ConvertFromUtf32
- Char.ConvertToUtf32
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 de caractères connue
L’utilisation du Rune
type peut retourner 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 itère à travers une string
recherche de caractères spécifiques, retournant l’index de la première correspondance. Il n’est pas nécessaire de modifier ce code à 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 nom 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 représentés par un seul char
.
Compter le nombre de caractères d’affichage dans un string
Le nombre d’instances Rune
d’une chaîne peut ne pas correspondre au nombre de caractères percés par l’utilisateur affichés lors de l’affichage de la chaîne.
Étant donné que Rune
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
constructeur 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');
Une paire de substitution
char
.Rune d = new Rune('\ud83d', '\udd2e'); // U+1F52E CRYSTAL BALL
Tous les constructeurs lèvent une ArgumentException
valeur scalaire Unicode valide si l’entrée ne représente pas de valeur scalaire Unicode valide.
Il existe Rune.TryCreate des méthodes disponibles pour les appelants qui ne souhaitent pas que les 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é un ReadOnlySpan<char>
qui représente des 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 méthodes et Char.GetUnicodeCategory aux Char.IsWhiteSpace méthodes. Les Rune
méthodes gèrent correctement les paires de substitution.
L’exemple de code suivant prend une ReadOnlySpan<char>
entrée et découpe à la fois du début et de la fin de l’étendue toutes les Rune
lettres qui ne sont 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 certaines différences d’API entre char
et Rune
. Exemple :
- Il n’y a pas
Rune
d’équivalent à Char.IsSurrogate(Char), carRune
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’il Rune
s’agit d’une valeur scalaire Unicode, elle peut être convertie en encodage UTF-8, UTF-16 ou UTF-32. Le Rune
type prend en charge la conversion en UTF-8 et UTF-16.
La Rune.EncodeToUtf16 conversion d’une Rune
instance en char
instances. Pour interroger le nombre d’instances char
résultant 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 char
tableau. Le code suppose que vous disposez d’une Rune
instance dans la rune
variable :
char[] chars = new char[rune.Utf16SequenceLength];
int numCharsWritten = rune.EncodeToUtf16(chars);
Étant donné qu’il string
s’agit d’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 les méthodes 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 des méthodes et EncodeToUtf16 des méthodes non levées TryEncodeToUtf8 ainsi que pour les appelants qui souhaitent éviter les exceptions.
Rune dans .NET et 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 recherchaient un terme pour décrire ce qui serait finalement devenu un point de code. Ils se sont installé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
. Un rune Go est destiné à 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 et les valeurs de substitution qui ne sont pas des points de code Unicode juridiques.
Pour les types similaires dans d’autres langages de programmation, consultez le type primitif char
de Rust ou le Unicode.Scalar
type Swift, qui représentent les deux valeurs scalaires Unicode. Ils fournissent des fonctionnalités similaires à . Le type de Rune
NET et ils interdisent l’instanciation des 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 fournie de caractères. |