UTF32Encoding.GetChars Méthode

  • Référence

Définition

Espace de noms:
System.Text
Assemblys:
mscorlib.dll, System.Text.Encoding.Extensions.dll
Assembly:
System.Text.Encoding.Extensions.dll
Assembly:
mscorlib.dll
Assembly:
netstandard.dll

Décode une séquence d'octets en un jeu de caractères.

Surcharges

GetChars(Byte*, Int32, Char*, Int32)

Décode une séquence d'octets commençant au pointeur d'octet spécifié en un jeu de caractères qui sera stocké à partir du pointeur de caractère spécifié.
GetChars(Byte[], Int32, Int32, Char[], Int32)

Décode une séquence d'octets du tableau d'octets spécifié dans le tableau de caractères spécifié.

GetChars(Byte*, Int32, Char*, Int32)

Source:
UTF32Encoding.cs
Source:
UTF32Encoding.cs
Source:
UTF32Encoding.cs

Important

Cette API n’est pas conforme CLS.

Décode une séquence d'octets commençant au pointeur d'octet spécifié en un jeu de caractères qui sera stocké à partir du pointeur de caractère spécifié.

public:
 override int GetChars(System::Byte* bytes, int byteCount, char* chars, int charCount);
[System.CLSCompliant(false)]
[System.Security.SecurityCritical]
public override int GetChars (byte* bytes, int byteCount, char* chars, int charCount);
[System.CLSCompliant(false)]
public override int GetChars (byte* bytes, int byteCount, char* chars, int charCount);
[<System.CLSCompliant(false)>]
[<System.Security.SecurityCritical>]
override this.GetChars : nativeptr<byte> * int * nativeptr<char> * int -> int
[<System.CLSCompliant(false)>]
override this.GetChars : nativeptr<byte> * int * nativeptr<char> * int -> int

Paramètres

bytes
Byte*

Pointeur du premier octet à décoder.

byteCount
Int32

Nombre d'octets à décoder.

chars
Char*

Pointeur de l'emplacement où commencer l'écriture du jeu de caractères obtenu.

charCount
Int32

Nombre maximal de caractères à écrire.

Retours

Int32

Nombre réel de caractères écrits à l'emplacement indiqué par chars.

Attributs
CLSCompliantAttribute SecurityCriticalAttribute

Exceptions

ArgumentNullException

bytes a la valeur null.

-ou-

chars a la valeur null.

ArgumentOutOfRangeException

byteCount ou charCount est inférieur à zéro.

ArgumentException

La détection d’erreurs est activée et bytes contient une séquence d’octets non valide.

- ou -

charCount est inférieur au nombre de caractères obtenus.

DecoderFallbackException

Un secours s’est produit (pour plus d’informations, consultez Codage de caractères dans .NET)

-et-

DecoderFallback a la valeur DecoderExceptionFallback.

Remarques

Pour calculer la taille exacte du tableau requise pour GetChars stocker les caractères résultants, appelez la GetCharCount méthode . Pour calculer la taille maximale du tableau, appelez la GetMaxCharCount méthode. La GetCharCount méthode alloue généralement moins de mémoire, tandis que la GetMaxCharCount méthode s’exécute généralement plus rapidement.

Avec la détection d’erreur, une séquence non valide entraîne la levée d’un ArgumentException. Sans détection d’erreur, les séquences non valides sont ignorées et aucune exception n’est levée.

Si la plage d’octets à décoder inclut la marque d’ordre d’octets (BOM) et que le tableau d’octets a été retourné par une méthode de type non compatible boM, le caractère U+FFFE est inclus dans le tableau de caractères retourné par cette méthode. Vous pouvez le supprimer en appelant la String.TrimStart méthode .

Les données à convertir, telles que les données lues à partir d’un flux, peuvent être disponibles uniquement dans des blocs séquentiels. Dans ce cas, ou si la quantité de données est tellement importante qu’elle doit être divisée en blocs plus petits, l’application utilise respectivement le Decoder ou Encoder fourni par la GetDecoder méthode ou la GetEncoder méthode.

Voir aussi

S’applique à

GetChars(Byte[], Int32, Int32, Char[], Int32)

Source:
UTF32Encoding.cs
Source:
UTF32Encoding.cs
Source:
UTF32Encoding.cs

Décode une séquence d'octets du tableau d'octets spécifié dans le tableau de caractères spécifié.

public:
 override int GetChars(cli::array <System::Byte> ^ bytes, int byteIndex, int byteCount, cli::array <char> ^ chars, int charIndex);
public override int GetChars (byte[] bytes, int byteIndex, int byteCount, char[] chars, int charIndex);
override this.GetChars : byte[] * int * int * char[] * int -> int
Public Overrides Function GetChars (bytes As Byte(), byteIndex As Integer, byteCount As Integer, chars As Char(), charIndex As Integer) As Integer

Paramètres

bytes
Byte[]

Tableau d'octets contenant la séquence d'octets à décoder.

byteIndex
Int32

Index du premier octet à décoder.

byteCount
Int32

Nombre d'octets à décoder.

chars
Char[]

Tableau de caractères destiné à contenir le jeu de caractères obtenu.

charIndex
Int32

Index auquel commencer l'écriture du jeu de caractères obtenu.

Retours

Int32

Nombre réel de caractères écrits dans chars.

Exceptions

ArgumentNullException

bytes a la valeur null.

-ou-

chars a la valeur null.

ArgumentOutOfRangeException

byteIndex, byteCount ou charIndex est inférieur à zéro.

- ou -

byteindex et byteCount ne désignent pas une plage valide dans bytes.

- ou -

charIndex n'est pas un index valide dans chars.

ArgumentException

La détection d’erreurs est activée et bytes contient une séquence d’octets non valide.

- ou -

chars ne possède pas une capacité suffisante entre charIndex et la fin du tableau pour prendre en charge les caractères obtenus.

DecoderFallbackException

Un secours s’est produit (pour plus d’informations, consultez Codage de caractères dans .NET)

-et-

DecoderFallback a la valeur DecoderExceptionFallback.

Exemples

L’exemple suivant encode une chaîne en un tableau d’octets, puis décode les octets en un tableau de caractères.

using namespace System;
using namespace System::Text;
void PrintCountsAndChars( array<Byte>^bytes, Encoding^ enc );
int main()
{
   
   // Create two instances of UTF32Encoding: one with little-endian byte order and one with big-endian byte order.
   UTF32Encoding^ u32LE = gcnew UTF32Encoding( false,true,true );
   UTF32Encoding^ u32BE = gcnew UTF32Encoding( true,true,true );
   
   // Create byte arrays from the same string containing the following characters:
   //    Latin Small Letter Z (U+007A)
   //    Latin Small Letter A (U+0061)
   //    Combining Breve (U+0306)
   //    Latin Small Letter AE With Acute (U+01FD)
   //    Greek Small Letter Beta (U+03B2)
   String^ myStr = L"za\u0306\u01FD\u03B2\xD8FF\xDCFF";
   
   // barrBE uses the big-endian byte order.
   array<Byte>^barrBE = gcnew array<Byte>(u32BE->GetByteCount( myStr ));
   u32BE->GetBytes( myStr, 0, myStr->Length, barrBE, 0 );
   
   // barrLE uses the little-endian byte order.
   array<Byte>^barrLE = gcnew array<Byte>(u32LE->GetByteCount( myStr ));
   u32LE->GetBytes( myStr, 0, myStr->Length, barrLE, 0 );
   
   // Get the char counts and decode the byte arrays.
   Console::Write( "BE array with BE encoding : " );
   PrintCountsAndChars( barrBE, u32BE );
   Console::Write( "LE array with LE encoding : " );
   PrintCountsAndChars( barrLE, u32LE );
   
   // Decode the byte arrays using an encoding with a different byte order.
   Console::Write( "BE array with LE encoding : " );
   try
   {
      PrintCountsAndChars( barrBE, u32LE );
   }
   catch ( System::ArgumentException^ e ) 
   {
      Console::WriteLine( e->Message );
   }

   Console::Write( "LE array with BE encoding : " );
   try
   {
      PrintCountsAndChars( barrLE, u32BE );
   }
   catch ( System::ArgumentException^ e ) 
   {
      Console::WriteLine( e->Message );
   }

}

void PrintCountsAndChars( array<Byte>^bytes, Encoding^ enc )
{
   
   // Display the name of the encoding used.
   Console::Write( "{0,-25} :", enc );
   
   // Display the exact character count.
   int iCC = enc->GetCharCount( bytes );
   Console::Write( " {0,-3}", iCC );
   
   // Display the maximum character count.
   int iMCC = enc->GetMaxCharCount( bytes->Length );
   Console::Write( " {0,-3} :", iMCC );
   
   // Decode the bytes and display the characters.
   array<Char>^chars = gcnew array<Char>(iCC);
   enc->GetChars( bytes, 0, bytes->Length, chars, 0 );
   Console::WriteLine( chars );
}

/* 
This code produces the following output.  The question marks take the place of characters that cannot be displayed at the console.

BE array with BE encoding : System.Text.UTF32Encoding : 7   14  :za??�?
LE array with LE encoding : System.Text.UTF32Encoding : 7   14  :za??�?
BE array with LE encoding : System.Text.UTF32Encoding :Invalid byte was found at byte index 3.
LE array with BE encoding : System.Text.UTF32Encoding :Invalid byte was found at byte index 3.

*/

using System;
using System.Text;

public class SamplesUTF32Encoding  {

   public static void Main()  {

      // Create two instances of UTF32Encoding: one with little-endian byte order and one with big-endian byte order.
      UTF32Encoding u32LE = new UTF32Encoding( false, true, true );
      UTF32Encoding u32BE = new UTF32Encoding( true, true, true );

      // Create byte arrays from the same string containing the following characters:
      //    Latin Small Letter Z (U+007A)
      //    Latin Small Letter A (U+0061)
      //    Combining Breve (U+0306)
      //    Latin Small Letter AE With Acute (U+01FD)
      //    Greek Small Letter Beta (U+03B2)
      //    a high-surrogate value (U+D8FF)
      //    a low-surrogate value (U+DCFF)
      String myStr = "za\u0306\u01FD\u03B2\uD8FF\uDCFF";

      // barrBE uses the big-endian byte order.
      byte[] barrBE = new byte[u32BE.GetByteCount( myStr )];
      u32BE.GetBytes( myStr, 0, myStr.Length, barrBE, 0 );

      // barrLE uses the little-endian byte order.
      byte[] barrLE = new byte[u32LE.GetByteCount( myStr )];
      u32LE.GetBytes( myStr, 0, myStr.Length, barrLE, 0 );

      // Get the char counts and decode the byte arrays.
      Console.Write( "BE array with BE encoding : " );
      PrintCountsAndChars( barrBE, u32BE );
      Console.Write( "LE array with LE encoding : " );
      PrintCountsAndChars( barrLE, u32LE );

      // Decode the byte arrays using an encoding with a different byte order.
      Console.Write( "BE array with LE encoding : " );
      try  {
         PrintCountsAndChars( barrBE, u32LE );
      }
      catch ( System.ArgumentException e )  {
         Console.WriteLine( e.Message );
      }

      Console.Write( "LE array with BE encoding : " );
      try  {
         PrintCountsAndChars( barrLE, u32BE );
      }
      catch ( System.ArgumentException e )  {
         Console.WriteLine( e.Message );
      }
   }

   public static void PrintCountsAndChars( byte[] bytes, Encoding enc )  {

      // Display the name of the encoding used.
      Console.Write( "{0,-25} :", enc.ToString() );

      // Display the exact character count.
      int iCC  = enc.GetCharCount( bytes );
      Console.Write( " {0,-3}", iCC );

      // Display the maximum character count.
      int iMCC = enc.GetMaxCharCount( bytes.Length );
      Console.Write( " {0,-3} :", iMCC );

      // Decode the bytes and display the characters.
      char[] chars = new char[iCC];
      enc.GetChars( bytes, 0, bytes.Length, chars, 0 );
      Console.WriteLine( chars );
   }
}

Imports System.Text

Public Class SamplesUTF32Encoding   

   Public Shared Sub Main()

      ' Create two instances of UTF32Encoding: one with little-endian byte order and one with big-endian byte order.
      Dim u32LE As New UTF32Encoding(False, True, True)
      Dim u32BE As New UTF32Encoding(True, True, True)


      ' Create byte arrays from the same string containing the following characters:
      '    Latin Small Letter Z (U+007A)
      '    Latin Small Letter A (U+0061)
      '    Combining Breve (U+0306)
      '    Latin Small Letter AE With Acute (U+01FD)
      '    Greek Small Letter Beta (U+03B2)
      '    a high-surrogate value (U+D8FF)
      '    a low-surrogate value (U+DCFF)
      Dim myStr As String = "za" & ChrW(&H0306) & ChrW(&H01FD) & ChrW(&H03B2) & ChrW(&HD8FF) & ChrW(&HDCFF)

      ' barrBE uses the big-endian byte order.
      ' NOTE: In Visual Basic, arrays contain one extra element by default.
      '       The following line creates an array with the exact number of elements required.
      Dim barrBE(u32BE.GetByteCount(myStr) - 1) As Byte
      u32BE.GetBytes(myStr, 0, myStr.Length, barrBE, 0)

      ' barrLE uses the little-endian byte order.
      ' NOTE: In Visual Basic, arrays contain one extra element by default.
      '       The following line creates an array with the exact number of elements required.
      Dim barrLE(u32LE.GetByteCount(myStr) - 1) As Byte
      u32LE.GetBytes(myStr, 0, myStr.Length, barrLE, 0)


      ' Get the char counts and decode the byte arrays.
      Console.Write("BE array with BE encoding : ")
      PrintCountsAndChars(barrBE, u32BE)
      Console.Write("LE array with LE encoding : ")
      PrintCountsAndChars(barrLE, u32LE)


      ' Decode the byte arrays using an encoding with a different byte order.
      Console.Write("BE array with LE encoding : ")
      Try
         PrintCountsAndChars(barrBE, u32LE)
      Catch e As System.ArgumentException
         Console.WriteLine(e.Message)
      End Try

      Console.Write("LE array with BE encoding : ")
      Try
         PrintCountsAndChars(barrLE, u32BE)
      Catch e As System.ArgumentException
         Console.WriteLine(e.Message)
      End Try

   End Sub


   Public Shared Sub PrintCountsAndChars(bytes() As Byte, enc As Encoding)

      ' Display the name of the encoding used.
      Console.Write("{0,-25} :", enc.ToString())

      ' Display the exact character count.
      Dim iCC As Integer = enc.GetCharCount(bytes)
      Console.Write(" {0,-3}", iCC)

      ' Display the maximum character count.
      Dim iMCC As Integer = enc.GetMaxCharCount(bytes.Length)
      Console.Write(" {0,-3} :", iMCC)

      ' Decode the bytes and display the characters.
      Dim chars(iCC) As Char
      enc.GetChars(bytes, 0, bytes.Length, chars, 0)
      Console.WriteLine(chars)

   End Sub

End Class

Remarques

Pour calculer la taille exacte du tableau requise pour GetChars stocker les caractères résultants, appelez la GetCharCount méthode . Pour calculer la taille maximale du tableau, appelez la GetMaxCharCount méthode. La GetCharCount méthode alloue généralement moins de mémoire, tandis que la GetMaxCharCount méthode s’exécute généralement plus rapidement.

Avec la détection d’erreur, une séquence non valide entraîne la levée d’un ArgumentException. Sans détection d’erreur, les séquences non valides sont ignorées et aucune exception n’est levée.

Si la plage d’octets à décoder inclut la marque d’ordre d’octets (BOM) et que le tableau d’octets a été retourné par une méthode de type non compatible boM, le caractère U+FFFE est inclus dans le tableau de caractères retourné par cette méthode. Vous pouvez le supprimer en appelant la String.TrimStart méthode .

Les données à convertir, telles que les données lues à partir d’un flux, peuvent être disponibles uniquement dans des blocs séquentiels. Dans ce cas, ou si la quantité de données est tellement importante qu’elle doit être divisée en blocs plus petits, l’application utilise respectivement le Decoder ou Encoder fourni par la GetDecoder méthode ou la GetEncoder méthode.

Voir aussi

S’applique à