Encoding.GetChars Metoda

Definicja

Gdy jest zastępowany w klasie pochodnej, dekoduje sekwencję bajtów do zestawu znaków.When overridden in a derived class, decodes a sequence of bytes into a set of characters.

Przeciążenia

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

Gdy jest zastępowany w klasie pochodnej, dekoduje sekwencję bajtów z określonej tablicy bajtów do określonej tablicy znaków.When overridden in a derived class, decodes a sequence of bytes from the specified byte array into the specified character array.

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

Gdy jest zastępowany w klasie pochodnej, dekoduje sekwencję bajtów, zaczynając od określonego wskaźnika Byte do zestawu znaków, które są przechowywane, zaczynając od określonego wskaźnika znakowego.When overridden in a derived class, decodes a sequence of bytes starting at the specified byte pointer into a set of characters that are stored starting at the specified character pointer.

GetChars(ReadOnlySpan<Byte>, Span<Char>)

Gdy jest zastępowany w klasie pochodnej, dekoduje wszystkie bajty w określonym zakresie bajtów tylko do odczytu do zakresu znaków.When overridden in a derived class, decodes all the bytes in the specified read-only byte span into a character span.

GetChars(Byte[], Int32, Int32)

Gdy jest zastępowany w klasie pochodnej, dekoduje sekwencję bajtów z określonej tablicy bajtów do zestawu znaków.When overridden in a derived class, decodes a sequence of bytes from the specified byte array into a set of characters.

GetChars(Byte[])

Gdy jest zastępowany w klasie pochodnej, dekoduje wszystkie bajty w określonej tablicy bajtów do zestawu znaków.When overridden in a derived class, decodes all the bytes in the specified byte array into a set of characters.

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

Gdy jest zastępowany w klasie pochodnej, dekoduje sekwencję bajtów z określonej tablicy bajtów do określonej tablicy znaków.When overridden in a derived class, decodes a sequence of bytes from the specified byte array into the specified character array.

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

Parametry

bytes
Byte[]

Tablica bajtowa zawierająca sekwencję bajtów do zdekodowania.The byte array containing the sequence of bytes to decode.

byteIndex
Int32

Indeks pierwszego bajtu do zdekodowania.The index of the first byte to decode.

byteCount
Int32

Liczba bajtów do zdekodowania.The number of bytes to decode.

chars
Char[]

Tablica znaków, która będzie zawierać zestaw znaków.The character array to contain the resulting set of characters.

charIndex
Int32

Indeks, od którego należy zacząć pisać zestaw znaków.The index at which to start writing the resulting set of characters.

Zwraca

Int32

Rzeczywista liczba znaków do zapisania chars .The actual number of characters written into chars.

Wyjątki

bytes to null.bytes is null.

-lub--or-

chars to null.chars is null.

byteIndex lub byteCount charIndex jest mniejsza od zera.byteIndex or byteCount or charIndex is less than zero.

-lub--or-

byteindex i byteCount nie należy zauważyć prawidłowego zakresu w bytes .byteindex and byteCount do not denote a valid range in bytes.

-lub--or-

charIndex nie jest prawidłowym indeksem w chars .charIndex is not a valid index in chars.

chars nie ma wystarczającej pojemności od charIndex do końca tablicy, aby pomieścić wyniki.chars does not have enough capacity from charIndex to the end of the array to accommodate the resulting characters.

Wystąpiła rezerwa (Aby uzyskać więcej informacji, zobacz kodowanie znaków w programie .NET).A fallback occurred (for more information, see Character Encoding in .NET)

lub-and-

DecoderFallback jest ustawiony na DecoderExceptionFallback .DecoderFallback is set to DecoderExceptionFallback.

Przykłady

Poniższy przykład konwertuje ciąg z jednego kodowania na inny.The following example converts a string from one encoding to another.

using namespace System;
using namespace System::Text;

int main()
{
   String^ unicodeString = "This string contains the unicode character Pi (\u03a0)";
   
   // Create two different encodings.
   Encoding^ ascii = Encoding::ASCII;
   Encoding^ unicode = Encoding::Unicode;
   
   // Convert the string into a byte array.
   array<Byte>^unicodeBytes = unicode->GetBytes( unicodeString );
   
   // Perform the conversion from one encoding to the other.
   array<Byte>^asciiBytes = Encoding::Convert( unicode, ascii, unicodeBytes );
   
   // Convert the new Byte into[] a char and[] then into a string.
   array<Char>^asciiChars = gcnew array<Char>(ascii->GetCharCount( asciiBytes, 0, asciiBytes->Length ));
   ascii->GetChars( asciiBytes, 0, asciiBytes->Length, asciiChars, 0 );
   String^ asciiString = gcnew String( asciiChars );
   
   // Display the strings created before and after the conversion.
   Console::WriteLine( "Original String*: {0}", unicodeString );
   Console::WriteLine( "Ascii converted String*: {0}", asciiString );
}
// The example displays the following output:
//    Original string: This string contains the unicode character Pi (Π)
//    Ascii converted string: This string contains the unicode character Pi (?)
using System;
using System.Text;

class Example
{
   static void Main()
   {
      string unicodeString = "This string contains the unicode character Pi (\u03a0)";

      // Create two different encodings.
      Encoding ascii = Encoding.ASCII;
      Encoding unicode = Encoding.Unicode;

      // Convert the string into a byte array.
      byte[] unicodeBytes = unicode.GetBytes(unicodeString);

      // Perform the conversion from one encoding to the other.
      byte[] asciiBytes = Encoding.Convert(unicode, ascii, unicodeBytes);
         
      // Convert the new byte[] into a char[] and then into a string.
      char[] asciiChars = new char[ascii.GetCharCount(asciiBytes, 0, asciiBytes.Length)];
      ascii.GetChars(asciiBytes, 0, asciiBytes.Length, asciiChars, 0);
      string asciiString = new string(asciiChars);

      // Display the strings created before and after the conversion.
      Console.WriteLine("Original string: {0}", unicodeString);
      Console.WriteLine("Ascii converted string: {0}", asciiString);
   }
}
// The example displays the following output:
//    Original string: This string contains the unicode character Pi (Π)
//    Ascii converted string: This string contains the unicode character Pi (?)
Imports System.Text

Class Example
   Shared Sub Main()
      Dim unicodeString As String = "This string contains the unicode character Pi (" & ChrW(&H03A0) & ")"

      ' Create two different encodings.
      Dim ascii As Encoding = Encoding.ASCII
      Dim unicode As Encoding = Encoding.Unicode

      ' Convert the string into a byte array.
      Dim unicodeBytes As Byte() = unicode.GetBytes(unicodeString)

      ' Perform the conversion from one encoding to the other.
      Dim asciiBytes As Byte() = Encoding.Convert(unicode, ascii, unicodeBytes)

      ' Convert the new byte array into a char array and then into a string.
      Dim asciiChars(ascii.GetCharCount(asciiBytes, 0, asciiBytes.Length)-1) As Char
      ascii.GetChars(asciiBytes, 0, asciiBytes.Length, asciiChars, 0)
      Dim asciiString As New String(asciiChars)

      ' Display the strings created before and after the conversion.
      Console.WriteLine("Original string: {0}", unicodeString)
      Console.WriteLine("Ascii converted string: {0}", asciiString)
   End Sub
End Class
' The example displays the following output:
'    Original string: This string contains the unicode character Pi (Π)
'    Ascii converted string: This string contains the unicode character Pi (?)

Poniższy przykład koduje ciąg w tablicy bajtów, a następnie dekoduje zakres bajtów do tablicy znaków.The following example encodes a string into an array of bytes, and then decodes a range of the bytes into an array of characters.

using namespace System;
using namespace System::Text;
void PrintCountsAndChars( array<Byte>^bytes, int index, int count, Encoding^ enc );
int main()
{
   
   // Create two instances of UTF32Encoding: one with little-endian byte order and one with big-endian byte order.
   Encoding^ u32LE = Encoding::GetEncoding( "utf-32" );
   Encoding^ u32BE = Encoding::GetEncoding( "utf-32BE" );
   
   // Use a 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 = "za\u0306\u01FD\u03B2";
   
   // Encode the string using the big-endian byte order.
   array<Byte>^barrBE = gcnew array<Byte>(u32BE->GetByteCount( myStr ));
   u32BE->GetBytes( myStr, 0, myStr->Length, barrBE, 0 );
   
   // Encode the string using 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, decode eight bytes starting at index 0,
   // and print out the counts and the resulting bytes.
   Console::Write( "BE array with BE encoding : " );
   PrintCountsAndChars( barrBE, 0, 8, u32BE );
   Console::Write( "LE array with LE encoding : " );
   PrintCountsAndChars( barrLE, 0, 8, u32LE );
}

void PrintCountsAndChars( array<Byte>^bytes, int index, int count, Encoding^ enc )
{
   
   // Display the name of the encoding used.
   Console::Write( "{0,-25} :", enc );
   
   // Display the exact character count.
   int iCC = enc->GetCharCount( bytes, index, count );
   Console::Write( " {0,-3}", iCC );
   
   // Display the maximum character count.
   int iMCC = enc->GetMaxCharCount( count );
   Console::Write( " {0,-3} :", iMCC );
   
   // Decode the bytes and display the characters.
   array<Char>^chars = enc->GetChars( bytes, index, count );
   
   // The following is an alternative way to decode the bytes:
   // Char[] chars = new Char[iCC];
   // enc->GetChars( bytes, index, count, 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 : 2   6   :za
LE array with LE encoding : System.Text.UTF32Encoding : 2   6   :za

*/
using System;
using System.Text;

public class SamplesEncoding  {

   public static void Main()  {

      // Create two instances of UTF32Encoding: one with little-endian byte order and one with big-endian byte order.
      Encoding u32LE = Encoding.GetEncoding( "utf-32" );
      Encoding u32BE = Encoding.GetEncoding( "utf-32BE" );

      // Use a 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 = "za\u0306\u01FD\u03B2";

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

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

      // Get the char counts, decode eight bytes starting at index 0,
      // and print out the counts and the resulting bytes.
      Console.Write( "BE array with BE encoding : " );
      PrintCountsAndChars( barrBE, 0, 8, u32BE );
      Console.Write( "LE array with LE encoding : " );
      PrintCountsAndChars( barrLE, 0, 8, u32LE );
   }

   public static void PrintCountsAndChars( byte[] bytes, int index, int count, 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, index, count );
      Console.Write( " {0,-3}", iCC );

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

      // Decode the bytes and display the characters.
      char[] chars = enc.GetChars( bytes, index, count );

      // The following is an alternative way to decode the bytes:
      // char[] chars = new char[iCC];
      // enc.GetChars( bytes, index, count, 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 : 2   6   :za
LE array with LE encoding : System.Text.UTF32Encoding : 2   6   :za

*/
Imports System.Text

Public Class SamplesEncoding   

   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 Encoding = Encoding.GetEncoding("utf-32")
      Dim u32BE As Encoding = Encoding.GetEncoding("utf-32BE")

      ' Use a 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)
      Dim myStr As String = "za" & ChrW(&H0306) & ChrW(&H01FD) & ChrW(&H03B2)

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

      ' Encode the string using the little-endian byte order.
      ' NOTE: In VB.NET, arrays contain one extra element by default.
      '       The following line creates barrLE 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, decode eight bytes starting at index 0,
      ' and print out the counts and the resulting bytes.
      Console.Write("BE array with BE encoding : ")
      PrintCountsAndChars(barrBE, 0, 8, u32BE)
      Console.Write("LE array with LE encoding : ")
      PrintCountsAndChars(barrLE, 0, 8, u32LE)

   End Sub


   Public Shared Sub PrintCountsAndChars(bytes() As Byte, index As Integer, count As Integer, 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, index, count)
      Console.Write(" {0,-3}", iCC)

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

      ' Decode the bytes.
      Dim chars As Char() = enc.GetChars(bytes, index, count)

      ' The following is an alternative way to decode the bytes:
      ' NOTE: In VB.NET, arrays contain one extra element by default.
      '       The following line creates the array with the exact number of elements required.
      ' Dim chars(iCC - 1) As Char
      ' enc.GetChars( bytes, index, count, chars, 0 )

      ' Display the characters.
      Console.WriteLine(chars)

   End Sub

End Class


'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 : 2   6   :za
'LE array with LE encoding : System.Text.UTF32Encoding : 2   6   :za

Uwagi

Aby obliczyć dokładne rozmiary tablicy wymagane przez GetChars program do przechowywania wyników, należy użyć GetCharCount metody.To calculate the exact array size required by GetChars to store the resulting characters, you should use the GetCharCount method. Aby obliczyć maksymalny rozmiar tablicy, użyj GetMaxCharCount metody.To calculate the maximum array size, use the GetMaxCharCount method. GetCharCountMetoda ogólnie zezwala na przydzielanie mniejszej ilości pamięci, podczas gdy GetMaxCharCount metoda zazwyczaj wykonuje się szybciej.The GetCharCount method generally allows allocation of less memory, while the GetMaxCharCount method generally executes faster.

GetChars(Byte[], Int32, Int32, Char[], Int32) Pobiera znaki z sekwencji bajtów wejściowych.GetChars(Byte[], Int32, Int32, Char[], Int32) gets characters from an input byte sequence. Encoding.GetChars jest inna niż Decoder.GetChars Encoding , ponieważ oczekuje konwersji dyskretnych, natomiast Decoder jest przeznaczona dla wielu przebiegów w pojedynczym strumieniu wejściowym.Encoding.GetChars is different than Decoder.GetChars because Encoding expects discrete conversions, while Decoder is designed for multiple passes on a single input stream.

Jeśli dane, które mają być konwertowane, są dostępne tylko w blokach sekwencyjnych (takich jak dane odczytane ze strumienia) lub jeśli ilość danych jest tak duża, że musi być podzielona na mniejsze bloki, należy użyć Decoder lub Encoder dostarczone przez GetDecoder metodę lub GetEncoder metodę, odpowiednio, klasy pochodnej.If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the Decoder or the Encoder provided by the GetDecoder method or the GetEncoder method, respectively, of a derived class.

Uwaga

Ta metoda jest przeznaczona do działania na znaki Unicode, a nie w dowolnych danych binarnych, takich jak tablice bajtowe.This method is intended to operate on Unicode characters, not on arbitrary binary data, such as byte arrays. Jeśli zachodzi potrzeba zakodowania dowolnych danych binarnych do tekstu, należy użyć protokołu takiego jak UUENCODE, który jest implementowany przez metody takie jak Convert.ToBase64CharArray .If you need to encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as Convert.ToBase64CharArray.

GetCharCountMetoda określa, ile znaków powoduje dekodowanie sekwencji bajtów, a GetChars Metoda wykonuje rzeczywiste dekodowanie.The GetCharCount method determines how many characters result in decoding a sequence of bytes, and the GetChars method performs the actual decoding. Encoding.GetCharsMetoda oczekuje konwersji dyskretnych, w przeciwieństwie do Decoder.GetChars metody, która obsługuje wiele przebiegów w pojedynczym strumieniu wejściowym.The Encoding.GetChars method expects discrete conversions, in contrast to the Decoder.GetChars method, which handles multiple passes on a single input stream.

Obsługiwane są różne wersje systemów GetCharCount i GetChars .Several versions of GetCharCount and GetChars are supported. Poniżej przedstawiono niektóre zagadnienia związane z programowaniem tych metod:The following are some programming considerations for use of these methods:

  • Aplikacja może wymagać dekodowania wielu bajtów wejściowych ze strony kodowej i przetworzyć bajty przy użyciu wielu wywołań.Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. W takim przypadku prawdopodobnie trzeba będzie zachować stan między wywołaniami, ponieważ sekwencje bajtów mogą być przerywane podczas przetwarzania w partiach.In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (Na przykład część sekwencji ISO-2022 może zakończyć jedno GetChars wywołanie i kontynuować na początku następnego GetChars wywołania.(For example, part of an ISO-2022 shift sequence may end one GetChars call and continue at the beginning of the next GetChars call. Encoding.GetChars spowoduje wywołanie powrotu dla tych niekompletnych sekwencji, ale Decoder zapamiętaje te sekwencje dla następnego wywołania.)Encoding.GetChars will call the fallback for those incomplete sequences, but Decoder will remember those sequences for the next call.)

  • Jeśli aplikacja obsługuje wyprowadzanie ciągów, GetString Metoda jest zalecana.If your app handles string outputs, the GetString method is recommended. Ponieważ ta metoda musi sprawdzić długość ciągu i przydzielić bufor, jest nieco wolniejsza, ale typ otrzymany String jest preferowany.Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting String type is to be preferred.

  • Wersja bajtowa programu GetChars(Byte*, Int32, Char*, Int32) umożliwia stosowanie niektórych szybkich technik, szczególnie z wieloma wywołaniami dużych buforów.The byte version of GetChars(Byte*, Int32, Char*, Int32) allows some fast techniques, particularly with multiple calls to large buffers. Należy jednak pamiętać, że ta wersja metody jest czasami niebezpieczna, ponieważ wskaźniki są wymagane.Bear in mind, however, that this method version is sometimes unsafe, since pointers are required.

  • Jeśli aplikacja wymaga konwersji dużej ilości danych, należy ponownie użyć buforu wyjściowego.If your app must convert a large amount of data, it should reuse the output buffer. W takiej sytuacji GetChars(Byte[], Int32, Int32, Char[], Int32) najlepszym wyborem jest wersja, która obsługuje wyjściowe bufory znaków.In this case, the GetChars(Byte[], Int32, Int32, Char[], Int32) version that supports output character buffers is the best choice.

  • Rozważ użycie Decoder.Convert metody zamiast GetCharCount .Consider using the Decoder.Convert method instead of GetCharCount. Metoda konwersji umożliwia konwertowanie możliwie największej ilości danych i zgłasza wyjątek, jeśli bufor wyjściowy jest zbyt mały.The conversion method converts as much data as possible and throws an exception if the output buffer is too small. W przypadku ciągłego dekodowania strumienia ta metoda jest często najlepszym wyborem.For continuous decoding of a stream, this method is often the best choice.

Zobacz też

Dotyczy

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

Ważne

Ten interfejs API nie jest zgodny ze specyfikacją CLS.

Gdy jest zastępowany w klasie pochodnej, dekoduje sekwencję bajtów, zaczynając od określonego wskaźnika Byte do zestawu znaków, które są przechowywane, zaczynając od określonego wskaźnika znakowego.When overridden in a derived class, decodes a sequence of bytes starting at the specified byte pointer into a set of characters that are stored starting at the specified character pointer.

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

Parametry

bytes
Byte*

Wskaźnik do pierwszego bajtu do zdekodowania.A pointer to the first byte to decode.

byteCount
Int32

Liczba bajtów do zdekodowania.The number of bytes to decode.

chars
Char*

Wskaźnik do lokalizacji, w której ma zostać rozpoczęte pisanie zestawu znaków.A pointer to the location at which to start writing the resulting set of characters.

charCount
Int32

Maksymalna liczba znaków do zapisania.The maximum number of characters to write.

Zwraca

Int32

Rzeczywista liczba znaków zapisywana w lokalizacji wskazywanej przez chars parametr.The actual number of characters written at the location indicated by the chars parameter.

Atrybuty

Wyjątki

bytes to null.bytes is null.

-lub--or-

chars to null.chars is null.

byteCount lub charCount jest mniejsza od zera.byteCount or charCount is less than zero.

charCount jest mniejsza niż liczba znaków będących wynikiem.charCount is less than the resulting number of characters.

Wystąpiła rezerwa (Aby uzyskać więcej informacji, zobacz kodowanie znaków w programie .NET).A fallback occurred (for more information, see Character Encoding in .NET)

lub-and-

DecoderFallback jest ustawiony na DecoderExceptionFallback .DecoderFallback is set to DecoderExceptionFallback.

Uwagi

Aby obliczyć dokładny rozmiar tablicy, który jest GetChars wymagany do przechowywania wyników, należy użyć GetCharCount metody.To calculate the exact array size that GetChars requires to store the resulting characters, you should use the GetCharCount method. Aby obliczyć maksymalny rozmiar tablicy, użyj GetMaxCharCount metody.To calculate the maximum array size, use the GetMaxCharCount method. GetCharCountMetoda ogólnie zezwala na przydzielanie mniejszej ilości pamięci, podczas gdy GetMaxCharCount metoda zazwyczaj wykonuje się szybciej.The GetCharCount method generally allows allocation of less memory, while the GetMaxCharCount method generally executes faster.

Encoding.GetChars Pobiera znaki z sekwencji bajtów wejściowych.Encoding.GetChars gets characters from an input byte sequence. Encoding.GetChars jest inna niż Decoder.GetChars Encoding , ponieważ oczekuje konwersji dyskretnych, natomiast Decoder jest przeznaczona dla wielu przebiegów w pojedynczym strumieniu wejściowym.Encoding.GetChars is different than Decoder.GetChars because Encoding expects discrete conversions, while Decoder is designed for multiple passes on a single input stream.

Jeśli dane, które mają być konwertowane, są dostępne tylko w blokach sekwencyjnych (takich jak dane odczytane ze strumienia) lub jeśli ilość danych jest tak duża, że musi być podzielona na mniejsze bloki, należy użyć Decoder lub Encoder obiekt dostarczony przez GetDecoder lub GetEncoder metodę, odpowiednio, klasy pochodnej.If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the Decoder or the Encoder object provided by the GetDecoder or the GetEncoder method, respectively, of a derived class.

Uwaga

Ta metoda jest przeznaczona do działania na znaki Unicode, a nie w dowolnych danych binarnych, takich jak tablice bajtowe.This method is intended to operate on Unicode characters, not on arbitrary binary data, such as byte arrays. Jeśli zachodzi potrzeba zakodowania dowolnych danych binarnych do tekstu, należy użyć protokołu takiego jak UUENCODE, który jest implementowany przez metody takie jak Convert.ToBase64CharArray .If you need to encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as Convert.ToBase64CharArray.

GetCharCountMetoda określa, ile znaków powoduje dekodowanie sekwencji bajtów, a GetChars Metoda wykonuje rzeczywiste dekodowanie.The GetCharCount method determines how many characters result in decoding a sequence of bytes, and the GetChars method performs the actual decoding. Encoding.GetCharsMetoda oczekuje konwersji dyskretnych, w przeciwieństwie do Decoder.GetChars metody, która obsługuje wiele przebiegów w pojedynczym strumieniu wejściowym.The Encoding.GetChars method expects discrete conversions, in contrast to the Decoder.GetChars method, which handles multiple passes on a single input stream.

Obsługiwane są różne wersje systemów GetCharCount i GetChars .Several versions of GetCharCount and GetChars are supported. Poniżej przedstawiono niektóre zagadnienia związane z programowaniem tych metod:The following are some programming considerations for use of these methods:

  • Aplikacja może wymagać dekodowania wielu bajtów wejściowych ze strony kodowej i przetworzyć bajty przy użyciu wielu wywołań.Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. W takim przypadku prawdopodobnie trzeba będzie zachować stan między wywołaniami, ponieważ sekwencje bajtów mogą być przerywane podczas przetwarzania w partiach.In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (Na przykład część sekwencji ISO-2022 może zakończyć jedno GetChars wywołanie i kontynuować na początku następnego GetChars wywołania.(For example, part of an ISO-2022 shift sequence may end one GetChars call and continue at the beginning of the next GetChars call. Encoding.GetChars spowoduje wywołanie powrotu dla tych niekompletnych sekwencji, ale Decoder zapamiętaje te sekwencje dla następnego wywołania.)Encoding.GetChars will call the fallback for those incomplete sequences, but Decoder will remember those sequences for the next call.)

  • Jeśli aplikacja obsługuje wyprowadzanie ciągów, GetString Metoda jest zalecana.If your app handles string outputs, the GetString method is recommended. Ponieważ ta metoda musi sprawdzić długość ciągu i przydzielić bufor, jest nieco wolniejsza, ale typ otrzymany String jest preferowany.Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting String type is to be preferred.

  • Wersja bajtowa programu GetChars(Byte*, Int32, Char*, Int32) umożliwia stosowanie niektórych szybkich technik, szczególnie z wieloma wywołaniami dużych buforów.The byte version of GetChars(Byte*, Int32, Char*, Int32) allows some fast techniques, particularly with multiple calls to large buffers. Należy jednak pamiętać, że ta wersja metody jest czasami niebezpieczna, ponieważ wskaźniki są wymagane.Bear in mind, however, that this method version is sometimes unsafe, since pointers are required.

  • Jeśli aplikacja wymaga konwersji dużej ilości danych, należy ponownie użyć buforu wyjściowego.If your app must convert a large amount of data, it should reuse the output buffer. W takiej sytuacji GetChars(Byte[], Int32, Int32, Char[], Int32) najlepszym wyborem jest wersja, która obsługuje wyjściowe bufory znaków.In this case, the GetChars(Byte[], Int32, Int32, Char[], Int32) version that supports output character buffers is the best choice.

  • Rozważ użycie Decoder.Convert metody zamiast GetCharCount .Consider using the Decoder.Convert method instead of GetCharCount. Metoda konwersji umożliwia konwertowanie możliwie największej ilości danych i zgłasza wyjątek, jeśli bufor wyjściowy jest zbyt mały.The conversion method converts as much data as possible and throws an exception if the output buffer is too small. W przypadku ciągłego dekodowania strumienia ta metoda jest często najlepszym wyborem.For continuous decoding of a stream, this method is often the best choice.

Zobacz też

Dotyczy

GetChars(ReadOnlySpan<Byte>, Span<Char>)

Gdy jest zastępowany w klasie pochodnej, dekoduje wszystkie bajty w określonym zakresie bajtów tylko do odczytu do zakresu znaków.When overridden in a derived class, decodes all the bytes in the specified read-only byte span into a character span.

public:
 virtual int GetChars(ReadOnlySpan<System::Byte> bytes, Span<char> chars);
public virtual int GetChars (ReadOnlySpan<byte> bytes, Span<char> chars);
abstract member GetChars : ReadOnlySpan<byte> * Span<char> -> int
override this.GetChars : ReadOnlySpan<byte> * Span<char> -> int
Public Overridable Function GetChars (bytes As ReadOnlySpan(Of Byte), chars As Span(Of Char)) As Integer

Parametry

bytes
ReadOnlySpan<Byte>

Zakres tylko do odczytu zawierający sekwencję bajtów do zdekodowania.A read-only span containing the sequence of bytes to decode.

chars
Span<Char>

Znak zakresu, który otrzymuje zdekodowane bajty.The character span receiving the decoded bytes.

Zwraca

Int32

Liczba zdekodowanych bajtów.The number of decoded bytes.

Uwagi

Encoding.GetChars Pobiera znaki z wejściowego zakresu bajtów.Encoding.GetChars gets characters from an input byte span. Encoding.GetChars jest inna niż Decoder.GetChars Encoding , ponieważ oczekuje konwersji dyskretnych, natomiast Decoder jest przeznaczona dla wielu przebiegów w pojedynczym strumieniu wejściowym.Encoding.GetChars is different than Decoder.GetChars because Encoding expects discrete conversions, while Decoder is designed for multiple passes on a single input stream.

Jeśli dane, które mają być konwertowane, są dostępne tylko w blokach sekwencyjnych (takich jak dane odczytane ze strumienia) lub jeśli ilość danych jest tak duża, że musi być podzielona na mniejsze bloki, należy użyć Decoder lub Encoder dostarczone przez GetDecoder metodę lub GetEncoder metodę, odpowiednio, klasy pochodnej.If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the Decoder or the Encoder provided by the GetDecoder method or the GetEncoder method, respectively, of a derived class.

GetCharCountMetoda określa, ile znaków powoduje dekodowanie sekwencji bajtów, a GetChars Metoda wykonuje rzeczywiste dekodowanie.The GetCharCount method determines how many characters result in decoding a sequence of bytes, and the GetChars method performs the actual decoding. Encoding.GetCharsMetoda oczekuje konwersji dyskretnych, w przeciwieństwie do Decoder.GetChars metody, która obsługuje wiele przebiegów w pojedynczym strumieniu wejściowym.The Encoding.GetChars method expects discrete conversions, in contrast to the Decoder.GetChars method, which handles multiple passes on a single input stream.

Obsługiwane są różne wersje systemów GetCharCount i GetChars .Several versions of GetCharCount and GetChars are supported. Poniżej przedstawiono niektóre zagadnienia związane z programowaniem tych metod:The following are some programming considerations for use of these methods:

  • Aplikacja może wymagać dekodowania wielu bajtów wejściowych ze strony kodowej i przetworzyć bajty przy użyciu wielu wywołań.Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. W takim przypadku prawdopodobnie trzeba będzie zachować stan między wywołaniami, ponieważ sekwencje bajtów mogą być przerywane podczas przetwarzania w partiach.In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (Na przykład część sekwencji ISO-2022 może zakończyć jedno GetChars wywołanie i kontynuować na początku następnego GetChars wywołania.(For example, part of an ISO-2022 shift sequence may end one GetChars call and continue at the beginning of the next GetChars call. Encoding.GetChars spowoduje wywołanie powrotu dla tych niekompletnych sekwencji, ale Decoder zapamiętaje te sekwencje dla następnego wywołania.)Encoding.GetChars will call the fallback for those incomplete sequences, but Decoder will remember those sequences for the next call.)

  • Jeśli aplikacja obsługuje wyprowadzanie ciągów, zaleca się użycie GetString metody.If your app handles string outputs, it is recommended to use the GetString method. Ponieważ ta metoda musi sprawdzić długość ciągu i przydzielić bufor, jest nieco wolniejsza, ale typ otrzymany String jest preferowany.Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting String type is to be preferred.

  • Wersja bajtowa programu GetChars(Byte*, Int32, Char*, Int32) umożliwia stosowanie niektórych szybkich technik, szczególnie z wieloma wywołaniami dużych buforów.The byte version of GetChars(Byte*, Int32, Char*, Int32) allows some fast techniques, particularly with multiple calls to large buffers. Należy jednak pamiętać, że ta wersja metody jest czasami niebezpieczna, ponieważ wskaźniki są wymagane.Bear in mind, however, that this method version is sometimes unsafe, since pointers are required.

  • Jeśli aplikacja wymaga konwersji dużej ilości danych, należy ponownie użyć buforu wyjściowego.If your app must convert a large amount of data, it should reuse the output buffer. W takiej sytuacji GetChars(Byte[], Int32, Int32, Char[], Int32) najlepszym wyborem jest wersja, która obsługuje wyjściowe bufory znaków.In this case, the GetChars(Byte[], Int32, Int32, Char[], Int32) version that supports output character buffers is the best choice.

  • Rozważ użycie Decoder.Convert metody zamiast GetCharCount .Consider using the Decoder.Convert method instead of GetCharCount. Metoda konwersji umożliwia konwertowanie możliwie największej ilości danych i zgłasza wyjątek, jeśli bufor wyjściowy jest zbyt mały.The conversion method converts as much data as possible and throws an exception if the output buffer is too small. W przypadku ciągłego dekodowania strumienia ta metoda jest często najlepszym wyborem.For continuous decoding of a stream, this method is often the best choice.

Dotyczy

GetChars(Byte[], Int32, Int32)

Gdy jest zastępowany w klasie pochodnej, dekoduje sekwencję bajtów z określonej tablicy bajtów do zestawu znaków.When overridden in a derived class, decodes a sequence of bytes from the specified byte array into a set of characters.

public:
 virtual cli::array <char> ^ GetChars(cli::array <System::Byte> ^ bytes, int index, int count);
public virtual char[] GetChars (byte[] bytes, int index, int count);
abstract member GetChars : byte[] * int * int -> char[]
override this.GetChars : byte[] * int * int -> char[]
Public Overridable Function GetChars (bytes As Byte(), index As Integer, count As Integer) As Char()

Parametry

bytes
Byte[]

Tablica bajtowa zawierająca sekwencję bajtów do zdekodowania.The byte array containing the sequence of bytes to decode.

index
Int32

Indeks pierwszego bajtu do zdekodowania.The index of the first byte to decode.

count
Int32

Liczba bajtów do zdekodowania.The number of bytes to decode.

Zwraca

Char[]

Tablica znaków zawierająca wyniki dekodowania określonej sekwencji bajtów.A character array containing the results of decoding the specified sequence of bytes.

Wyjątki

bytes to null.bytes is null.

index lub count jest mniejsza od zera.index or count is less than zero.

-lub--or-

index i count nie należy zauważyć prawidłowego zakresu w bytes .index and count do not denote a valid range in bytes.

Wystąpiła rezerwa (Aby uzyskać więcej informacji, zobacz kodowanie znaków w programie .NET).A fallback occurred (for more information, see Character Encoding in .NET)

lub-and-

DecoderFallback jest ustawiony na DecoderExceptionFallback .DecoderFallback is set to DecoderExceptionFallback.

Przykłady

Poniższy przykład koduje ciąg w tablicy bajtów, a następnie dekoduje zakres bajtów do tablicy znaków.The following example encodes a string into an array of bytes, and then decodes a range of the bytes into an array of characters.

using namespace System;
using namespace System::Text;
void PrintCountsAndChars( array<Byte>^bytes, int index, int count, Encoding^ enc );
int main()
{
   
   // Create two instances of UTF32Encoding: one with little-endian byte order and one with big-endian byte order.
   Encoding^ u32LE = Encoding::GetEncoding( "utf-32" );
   Encoding^ u32BE = Encoding::GetEncoding( "utf-32BE" );
   
   // Use a 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 = "za\u0306\u01FD\u03B2";
   
   // Encode the string using the big-endian byte order.
   array<Byte>^barrBE = gcnew array<Byte>(u32BE->GetByteCount( myStr ));
   u32BE->GetBytes( myStr, 0, myStr->Length, barrBE, 0 );
   
   // Encode the string using 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, decode eight bytes starting at index 0,
   // and print out the counts and the resulting bytes.
   Console::Write( "BE array with BE encoding : " );
   PrintCountsAndChars( barrBE, 0, 8, u32BE );
   Console::Write( "LE array with LE encoding : " );
   PrintCountsAndChars( barrLE, 0, 8, u32LE );
}

void PrintCountsAndChars( array<Byte>^bytes, int index, int count, Encoding^ enc )
{
   
   // Display the name of the encoding used.
   Console::Write( "{0,-25} :", enc );
   
   // Display the exact character count.
   int iCC = enc->GetCharCount( bytes, index, count );
   Console::Write( " {0,-3}", iCC );
   
   // Display the maximum character count.
   int iMCC = enc->GetMaxCharCount( count );
   Console::Write( " {0,-3} :", iMCC );
   
   // Decode the bytes and display the characters.
   array<Char>^chars = enc->GetChars( bytes, index, count );
   
   // The following is an alternative way to decode the bytes:
   // Char[] chars = new Char[iCC];
   // enc->GetChars( bytes, index, count, 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 : 2   6   :za
LE array with LE encoding : System.Text.UTF32Encoding : 2   6   :za

*/
using System;
using System.Text;

public class SamplesEncoding  {

   public static void Main()  {

      // Create two instances of UTF32Encoding: one with little-endian byte order and one with big-endian byte order.
      Encoding u32LE = Encoding.GetEncoding( "utf-32" );
      Encoding u32BE = Encoding.GetEncoding( "utf-32BE" );

      // Use a 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 = "za\u0306\u01FD\u03B2";

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

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

      // Get the char counts, decode eight bytes starting at index 0,
      // and print out the counts and the resulting bytes.
      Console.Write( "BE array with BE encoding : " );
      PrintCountsAndChars( barrBE, 0, 8, u32BE );
      Console.Write( "LE array with LE encoding : " );
      PrintCountsAndChars( barrLE, 0, 8, u32LE );
   }

   public static void PrintCountsAndChars( byte[] bytes, int index, int count, 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, index, count );
      Console.Write( " {0,-3}", iCC );

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

      // Decode the bytes and display the characters.
      char[] chars = enc.GetChars( bytes, index, count );

      // The following is an alternative way to decode the bytes:
      // char[] chars = new char[iCC];
      // enc.GetChars( bytes, index, count, 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 : 2   6   :za
LE array with LE encoding : System.Text.UTF32Encoding : 2   6   :za

*/
Imports System.Text

Public Class SamplesEncoding   

   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 Encoding = Encoding.GetEncoding("utf-32")
      Dim u32BE As Encoding = Encoding.GetEncoding("utf-32BE")

      ' Use a 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)
      Dim myStr As String = "za" & ChrW(&H0306) & ChrW(&H01FD) & ChrW(&H03B2)

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

      ' Encode the string using the little-endian byte order.
      ' NOTE: In VB.NET, arrays contain one extra element by default.
      '       The following line creates barrLE 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, decode eight bytes starting at index 0,
      ' and print out the counts and the resulting bytes.
      Console.Write("BE array with BE encoding : ")
      PrintCountsAndChars(barrBE, 0, 8, u32BE)
      Console.Write("LE array with LE encoding : ")
      PrintCountsAndChars(barrLE, 0, 8, u32LE)

   End Sub


   Public Shared Sub PrintCountsAndChars(bytes() As Byte, index As Integer, count As Integer, 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, index, count)
      Console.Write(" {0,-3}", iCC)

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

      ' Decode the bytes.
      Dim chars As Char() = enc.GetChars(bytes, index, count)

      ' The following is an alternative way to decode the bytes:
      ' NOTE: In VB.NET, arrays contain one extra element by default.
      '       The following line creates the array with the exact number of elements required.
      ' Dim chars(iCC - 1) As Char
      ' enc.GetChars( bytes, index, count, chars, 0 )

      ' Display the characters.
      Console.WriteLine(chars)

   End Sub

End Class


'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 : 2   6   :za
'LE array with LE encoding : System.Text.UTF32Encoding : 2   6   :za

Uwagi

Encoding.GetChars Pobiera znaki z sekwencji bajtów wejściowych.Encoding.GetChars gets characters from an input byte sequence. Encoding.GetChars jest inna niż Decoder.GetChars Encoding , ponieważ oczekuje konwersji dyskretnych, natomiast Decoder jest przeznaczona dla wielu przebiegów w pojedynczym strumieniu wejściowym.Encoding.GetChars is different than Decoder.GetChars because Encoding expects discrete conversions, while Decoder is designed for multiple passes on a single input stream.

Jeśli dane, które mają być konwertowane, są dostępne tylko w blokach sekwencyjnych (takich jak dane odczytane ze strumienia) lub jeśli ilość danych jest tak duża, że musi być podzielona na mniejsze bloki, należy użyć Decoder lub Encoder dostarczone przez GetDecoder metodę lub GetEncoder metodę, odpowiednio, klasy pochodnej.If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the Decoder or the Encoder provided by the GetDecoder method or the GetEncoder method, respectively, of a derived class.

Uwaga

Ta metoda jest przeznaczona do działania na znaki Unicode, a nie w dowolnych danych binarnych, takich jak tablice bajtowe.This method is intended to operate on Unicode characters, not on arbitrary binary data, such as byte arrays. Jeśli zachodzi potrzeba zakodowania dowolnych danych binarnych do tekstu, należy użyć protokołu takiego jak UUENCODE, który jest implementowany przez metody takie jak Convert.ToBase64CharArray .If you need to encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as Convert.ToBase64CharArray.

GetCharCountMetoda określa, ile znaków powoduje dekodowanie sekwencji bajtów, a GetChars Metoda wykonuje rzeczywiste dekodowanie.The GetCharCount method determines how many characters result in decoding a sequence of bytes, and the GetChars method performs the actual decoding. Encoding.GetCharsMetoda oczekuje konwersji dyskretnych, w przeciwieństwie do Decoder.GetChars metody, która obsługuje wiele przebiegów w pojedynczym strumieniu wejściowym.The Encoding.GetChars method expects discrete conversions, in contrast to the Decoder.GetChars method, which handles multiple passes on a single input stream.

Obsługiwane są różne wersje systemów GetCharCount i GetChars .Several versions of GetCharCount and GetChars are supported. Poniżej przedstawiono niektóre zagadnienia związane z programowaniem tych metod:The following are some programming considerations for use of these methods:

  • Aplikacja może wymagać dekodowania wielu bajtów wejściowych ze strony kodowej i przetworzyć bajty przy użyciu wielu wywołań.Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. W takim przypadku prawdopodobnie trzeba będzie zachować stan między wywołaniami, ponieważ sekwencje bajtów mogą być przerywane podczas przetwarzania w partiach.In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (Na przykład część sekwencji ISO-2022 może zakończyć jedno GetChars wywołanie i kontynuować na początku następnego GetChars wywołania.(For example, part of an ISO-2022 shift sequence may end one GetChars call and continue at the beginning of the next GetChars call. Encoding.GetChars spowoduje wywołanie powrotu dla tych niekompletnych sekwencji, ale Decoder zapamiętaje te sekwencje dla następnego wywołania.)Encoding.GetChars will call the fallback for those incomplete sequences, but Decoder will remember those sequences for the next call.)

  • Jeśli aplikacja obsługuje wyprowadzanie ciągów, zaleca się użycie GetString metody.If your app handles string outputs, it is recommended to use the GetString method. Ponieważ ta metoda musi sprawdzić długość ciągu i przydzielić bufor, jest nieco wolniejsza, ale typ otrzymany String jest preferowany.Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting String type is to be preferred.

  • Wersja bajtowa programu GetChars(Byte*, Int32, Char*, Int32) umożliwia stosowanie niektórych szybkich technik, szczególnie z wieloma wywołaniami dużych buforów.The byte version of GetChars(Byte*, Int32, Char*, Int32) allows some fast techniques, particularly with multiple calls to large buffers. Należy jednak pamiętać, że ta wersja metody jest czasami niebezpieczna, ponieważ wskaźniki są wymagane.Bear in mind, however, that this method version is sometimes unsafe, since pointers are required.

  • Jeśli aplikacja wymaga konwersji dużej ilości danych, należy ponownie użyć buforu wyjściowego.If your app must convert a large amount of data, it should reuse the output buffer. W takiej sytuacji GetChars(Byte[], Int32, Int32, Char[], Int32) najlepszym wyborem jest wersja, która obsługuje wyjściowe bufory znaków.In this case, the GetChars(Byte[], Int32, Int32, Char[], Int32) version that supports output character buffers is the best choice.

  • Rozważ użycie Decoder.Convert metody zamiast GetCharCount .Consider using the Decoder.Convert method instead of GetCharCount. Metoda konwersji umożliwia konwertowanie możliwie największej ilości danych i zgłasza wyjątek, jeśli bufor wyjściowy jest zbyt mały.The conversion method converts as much data as possible and throws an exception if the output buffer is too small. W przypadku ciągłego dekodowania strumienia ta metoda jest często najlepszym wyborem.For continuous decoding of a stream, this method is often the best choice.

Zobacz też

Dotyczy

GetChars(Byte[])

Gdy jest zastępowany w klasie pochodnej, dekoduje wszystkie bajty w określonej tablicy bajtów do zestawu znaków.When overridden in a derived class, decodes all the bytes in the specified byte array into a set of characters.

public:
 virtual cli::array <char> ^ GetChars(cli::array <System::Byte> ^ bytes);
public virtual char[] GetChars (byte[] bytes);
abstract member GetChars : byte[] -> char[]
override this.GetChars : byte[] -> char[]
Public Overridable Function GetChars (bytes As Byte()) As Char()

Parametry

bytes
Byte[]

Tablica bajtowa zawierająca sekwencję bajtów do zdekodowania.The byte array containing the sequence of bytes to decode.

Zwraca

Char[]

Tablica znaków zawierająca wyniki dekodowania określonej sekwencji bajtów.A character array containing the results of decoding the specified sequence of bytes.

Wyjątki

bytes to null.bytes is null.

Wystąpiła rezerwa (Aby uzyskać więcej informacji, zobacz kodowanie znaków w programie .NET).A fallback occurred (for more information, see Character Encoding in .NET)

lub-and-

DecoderFallback jest ustawiony na DecoderExceptionFallback .DecoderFallback is set to DecoderExceptionFallback.

Przykłady

Poniższy przykład koduje ciąg w tablicy bajtów, a następnie dekoduje bajty do tablicy znaków.The following example encodes a string into an array of bytes, and then decodes the bytes into an array of characters.

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.
   Encoding^ u32LE = Encoding::GetEncoding( "utf-32" );
   Encoding^ u32BE = Encoding::GetEncoding( "utf-32BE" );
   
   // Use a 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 = "za\u0306\u01FD\u03B2";
   
   // Encode the string using the big-endian byte order.
   array<Byte>^barrBE = gcnew array<Byte>(u32BE->GetByteCount( myStr ));
   u32BE->GetBytes( myStr, 0, myStr->Length, barrBE, 0 );
   
   // Encode the string using 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 );
}

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 = enc->GetChars( bytes );
   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 : 5   12  :zăǽβ
LE array with LE encoding : System.Text.UTF32Encoding : 5   12  :zăǽβ

*/
using System;
using System.Text;

public class SamplesEncoding  {

   public static void Main()  {

      // Create two instances of UTF32Encoding: one with little-endian byte order and one with big-endian byte order.
      Encoding u32LE = Encoding.GetEncoding( "utf-32" );
      Encoding u32BE = Encoding.GetEncoding( "utf-32BE" );

      // Use a 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 = "za\u0306\u01FD\u03B2";

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

      // Encode the string using 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 );
   }

   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 = enc.GetChars( bytes );
      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 : 5   12  :zăǽβ
LE array with LE encoding : System.Text.UTF32Encoding : 5   12  :zăǽβ

*/
Imports System.Text

Public Class SamplesEncoding   

   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 Encoding = Encoding.GetEncoding("utf-32")
      Dim u32BE As Encoding = Encoding.GetEncoding("utf-32BE")

      ' Use a 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)
      Dim myStr As String = "za" & ChrW(&H0306) & ChrW(&H01FD) & ChrW(&H03B2) 

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

      ' Encode the string using the little-endian byte order.
      ' NOTE: In VB.NET, arrays contain one extra element by default.
      '       The following line creates the 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)

   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 As Char() = enc.GetChars(bytes)
      Console.WriteLine(chars)

   End Sub

End Class


'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 : 5   12  :zăǽβ
'LE array with LE encoding : System.Text.UTF32Encoding : 5   12  :zăǽβ

Uwagi

Encoding.GetChars Pobiera znaki z sekwencji bajtów wejściowych.Encoding.GetChars gets characters from an input byte sequence. Encoding.GetChars jest inna niż Decoder.GetChars Encoding , ponieważ oczekuje konwersji dyskretnych, natomiast Decoder jest przeznaczona dla wielu przebiegów w pojedynczym strumieniu wejściowym.Encoding.GetChars is different than Decoder.GetChars because Encoding expects discrete conversions, while Decoder is designed for multiple passes on a single input stream.

Jeśli dane, które mają być konwertowane, są dostępne tylko w blokach sekwencyjnych (takich jak dane odczytane ze strumienia) lub jeśli ilość danych jest tak duża, że musi być podzielona na mniejsze bloki, należy użyć Decoder lub Encoder dostarczone przez GetDecoder metodę lub GetEncoder metodę, odpowiednio, klasy pochodnej.If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the Decoder or the Encoder provided by the GetDecoder method or the GetEncoder method, respectively, of a derived class.

Uwaga

Ta metoda jest przeznaczona do działania na znaki Unicode, a nie w dowolnych danych binarnych, takich jak tablice bajtowe.This method is intended to operate on Unicode characters, not on arbitrary binary data, such as byte arrays. Jeśli zachodzi potrzeba zakodowania dowolnych danych binarnych do tekstu, należy użyć protokołu takiego jak UUENCODE, który jest implementowany przez metody takie jak Convert.ToBase64CharArray .If you need to encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as Convert.ToBase64CharArray.

GetCharCountMetoda określa, ile znaków powoduje dekodowanie sekwencji bajtów, a GetChars Metoda wykonuje rzeczywiste dekodowanie.The GetCharCount method determines how many characters result in decoding a sequence of bytes, and the GetChars method performs the actual decoding. Encoding.GetCharsMetoda oczekuje konwersji dyskretnych, w przeciwieństwie do Decoder.GetChars metody, która obsługuje wiele przebiegów w pojedynczym strumieniu wejściowym.The Encoding.GetChars method expects discrete conversions, in contrast to the Decoder.GetChars method, which handles multiple passes on a single input stream.

Obsługiwane są różne wersje systemów GetCharCount i GetChars .Several versions of GetCharCount and GetChars are supported. Poniżej przedstawiono niektóre zagadnienia związane z programowaniem tych metod:The following are some programming considerations for use of these methods:

  • Aplikacja może wymagać dekodowania wielu bajtów wejściowych ze strony kodowej i przetworzyć bajty przy użyciu wielu wywołań.Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. W takim przypadku prawdopodobnie trzeba będzie zachować stan między wywołaniami, ponieważ sekwencje bajtów mogą być przerywane podczas przetwarzania w partiach.In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (Na przykład część sekwencji ISO-2022 może zakończyć jedno GetChars wywołanie i kontynuować na początku następnego GetChars wywołania.(For example, part of an ISO-2022 shift sequence may end one GetChars call and continue at the beginning of the next GetChars call. Encoding.GetChars spowoduje wywołanie powrotu dla tych niekompletnych sekwencji, ale Decoder zapamiętaje te sekwencje dla następnego wywołania.)Encoding.GetChars will call the fallback for those incomplete sequences, but Decoder will remember those sequences for the next call.)

  • Jeśli aplikacja obsługuje wyprowadzanie ciągów, zaleca się użycie GetString metody.If your app handles string outputs, it is recommended to use the GetString method. Ponieważ ta metoda musi sprawdzić długość ciągu i przydzielić bufor, jest nieco wolniejsza, ale typ otrzymany String jest preferowany.Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting String type is to be preferred.

  • Wersja bajtowa programu GetChars(Byte*, Int32, Char*, Int32) umożliwia stosowanie niektórych szybkich technik, szczególnie z wieloma wywołaniami dużych buforów.The byte version of GetChars(Byte*, Int32, Char*, Int32) allows some fast techniques, particularly with multiple calls to large buffers. Należy jednak pamiętać, że ta wersja metody jest czasami niebezpieczna, ponieważ wskaźniki są wymagane.Bear in mind, however, that this method version is sometimes unsafe, since pointers are required.

  • Jeśli aplikacja wymaga konwersji dużej ilości danych, należy ponownie użyć buforu wyjściowego.If your app must convert a large amount of data, it should reuse the output buffer. W takiej sytuacji GetChars(Byte[], Int32, Int32, Char[], Int32) najlepszym wyborem jest wersja, która obsługuje wyjściowe bufory znaków.In this case, the GetChars(Byte[], Int32, Int32, Char[], Int32) version that supports output character buffers is the best choice.

  • Rozważ użycie Decoder.Convert metody zamiast GetCharCount .Consider using the Decoder.Convert method instead of GetCharCount. Metoda konwersji umożliwia konwertowanie możliwie największej ilości danych i zgłasza wyjątek, jeśli bufor wyjściowy jest zbyt mały.The conversion method converts as much data as possible and throws an exception if the output buffer is too small. W przypadku ciągłego dekodowania strumienia ta metoda jest często najlepszym wyborem.For continuous decoding of a stream, this method is often the best choice.

Zobacz też

Dotyczy