UTF32Encoding.GetChars Metoda

Odwołanie

Definicja

Przestrzeń nazw:: System.Text

Zestawy:: mscorlib.dll, System.Text.Encoding.Extensions.dll

Zestaw:: System.Text.Encoding.Extensions.dll

Zestaw:: mscorlib.dll

Zestaw:: netstandard.dll

Ważne

Niektóre informacje odnoszą się do produktu w wersji wstępnej, który może zostać znacząco zmodyfikowany przed wydaniem. Firma Microsoft nie udziela żadnych gwarancji, jawnych lub domniemanych, w odniesieniu do informacji podanych w tym miejscu.

Dekoduje sekwencję bajtów do zestawu znaków.

Przeciążenia

GetChars(Byte, Int32, Char, Int32)	Dekoduje sekwencję bajtów rozpoczynającą się od określonego wskaźnika bajtów do zestawu znaków przechowywanych w określonym wskaźniku znaków.
GetChars(Byte[], Int32, Int32, Char[], Int32)	Dekoduje sekwencję bajtów z określonej tablicy bajtów do określonej tablicy znaków.

GetChars(Byte, Int32, Char, Int32)

Ważne

Ten interfejs API nie jest zgodny ze specyfikacją CLS.

Dekoduje sekwencję bajtów rozpoczynającą się od określonego wskaźnika bajtów do zestawu znaków przechowywanych w określonym wskaźniku znaków.

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

Parametry

bytes: Byte*

Wskaźnik do pierwszego bajtu w celu dekodowania.

byteCount: Int32

Liczba bajtów do dekodowania.

chars: Char*

Wskaźnik do lokalizacji, w której chcesz rozpocząć pisanie wynikowego zestawu znaków.

charCount: Int32

Maksymalna liczba znaków do zapisania.

Zwraca

Int32

Rzeczywista liczba znaków zapisanych w lokalizacji wskazanej przez chars.

Atrybuty: CLSCompliantAttribute SecurityCriticalAttribute

Wyjątki

ArgumentNullException

bytes to null.

-lub- chars to null.

ArgumentOutOfRangeException

byteCount wartość lub charCount jest mniejsza niż zero.

ArgumentException

Wykrywanie błędów jest włączone i bytes zawiera nieprawidłową sekwencję bajtów.

-lub- charCount jest mniejsza niż wynikowa liczba znaków.

DecoderFallbackException

Wystąpił rezerwowy (aby uzyskać więcej informacji, zobacz Kodowanie znaków na platformie .NET) -and- DecoderFallback jest ustawiona na DecoderExceptionFallbackwartość .

Uwagi

Aby obliczyć dokładny rozmiar tablicy wymagany przez GetChars do przechowywania wynikowych znaków, wywołaj metodę GetCharCount . Aby obliczyć maksymalny rozmiar tablicy, wywołaj metodę GetMaxCharCount . Metoda GetCharCount zazwyczaj przydziela mniej pamięci, podczas gdy GetMaxCharCount metoda zwykle wykonuje się szybciej.

W przypadku wykrywania błędów nieprawidłowa sekwencja powoduje, że ta metoda zgłasza błąd ArgumentException. Bez wykrywania błędów nieprawidłowe sekwencje są ignorowane i nie jest zgłaszany żaden wyjątek.

Jeśli zakres bajtów, które mają zostać zdekodowane, zawiera znak kolejności bajtów (BOM), a tablica bajtów została zwrócona przez metodę typu rozpoznawczego innego niż BOM, znak U+FFFE jest uwzględniony w tablicy znaków zwracanej przez tę metodę. Można go usunąć, wywołując metodę String.TrimStart .

Dane, które mają być konwertowane, takie jak dane odczytywane ze strumienia, mogą być dostępne tylko w blokach sekwencyjnych. W takim przypadku lub jeśli ilość danych jest tak duża, że musi być podzielona na mniejsze bloki, aplikacja używa Decoder wartości lub Encoder podanej GetDecoder odpowiednio przez metodę lub GetEncoder metodę.

Zobacz też

Dotyczy

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

Dekoduje sekwencję bajtów z określonej tablicy bajtów do określonej tablicy znaków.

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

Parametry

bytes: Byte[]

Tablica bajtów zawierająca sekwencję bajtów do dekodowania.

byteIndex: Int32

Indeks pierwszego bajtu do dekodowania.

byteCount: Int32

Liczba bajtów do dekodowania.

chars: Char[]

Tablica znaków zawierająca wynikowy zestaw znaków.

charIndex: Int32

Indeks, na którym rozpocznie się pisanie wynikowego zestawu znaków.

Zwraca

Int32

Rzeczywista liczba znaków zapisanych w charspliku .

Wyjątki

ArgumentNullException

bytes to null.

-lub- chars to null.

ArgumentOutOfRangeException

byteIndex lub byteCount charIndex jest mniejszy niż zero.

-lub- byteindex i byteCount nie oznaczają prawidłowego zakresu w byteselemecie .

-lub- charIndex nie jest prawidłowym indeksem w pliku chars.

ArgumentException

Wykrywanie błędów jest włączone i bytes zawiera nieprawidłową sekwencję bajtów.

-lub- chars nie ma wystarczającej pojemności od charIndex do końca tablicy, aby pomieścić wynikowe znaki.

DecoderFallbackException

Wystąpił rezerwowy (aby uzyskać więcej informacji, zobacz Kodowanie znaków na platformie .NET) -and- DecoderFallback jest ustawiona na DecoderExceptionFallbackwartość .

Przykłady

Poniższy przykład koduje ciąg do tablicy bajtów, a następnie dekoduje bajty do tablicy znaków.

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

Uwagi

Zobacz też

Dotyczy

UTF32Encoding.GetChars Metoda

Definicja

Przeciążenia

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

Parametry

Zwraca

Wyjątki

Uwagi

Zobacz też

Dotyczy

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

Parametry

Zwraca

Wyjątki

Przykłady

Uwagi

Zobacz też

Dotyczy

Dodatkowe zasoby

GetChars(Byte, Int32, Char, Int32)