Encoding.GetChars Método

Referência

Definição

Namespace:: System.Text

Assembly:: System.Text.Encoding.dll

Assembly:: System.Runtime.dll

Assembly:: mscorlib.dll

Assembly:: netstandard.dll

Importante

Algumas informações se referem a produtos de pré-lançamento que podem ser substancialmente modificados antes do lançamento. A Microsoft não oferece garantias, expressas ou implícitas, das informações aqui fornecidas.

Quando substituído em uma classe derivada, decodifica uma sequência de bytes em um conjunto de caracteres.

Sobrecargas

GetChars(Byte[], Int32, Int32, Char[], Int32)	Quando substituído em uma classe derivada, decodifica uma sequência de bytes da matriz de bytes especificada na matriz de caracteres especificada.
GetChars(Byte, Int32, Char, Int32)	Quando substituído em uma classe derivada, decodifica uma sequência de bytes iniciando no ponteiro de bytes especificado em um conjunto de caracteres começando no ponteiro de caractere especificado.
GetChars(Byte[], Int32, Int32)	Quando substituído em uma classe derivada, decodifica uma sequência de bytes da matriz de bytes especificada em um conjunto de caracteres.
GetChars(ReadOnlySpan<Byte>, Span<Char>)	Quando substituído em uma classe derivada, decodifica todos os bytes no intervalo de bytes somente leitura especificado em um intervalo de caracteres.
GetChars(Byte[])	Quando substituído em uma classe derivada, decodifica todos os bytes na matriz de bytes especificada em um conjunto de caracteres.

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

Origem:: Encoding.cs

Origem:: Encoding.cs

Origem:: Encoding.cs

Quando substituído em uma classe derivada, decodifica uma sequência de bytes da matriz de bytes especificada na matriz de caracteres especificada.

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

Parâmetros

bytes: Byte[]

A matriz de bytes que contém a sequência de bytes a ser decodificada.

byteIndex: Int32

O índice do primeiro byte a ser decodificado.

byteCount: Int32

O número de bytes a serem decodificados.

chars: Char[]

A matriz de caracteres que deve conter o conjunto de caracteres resultante.

charIndex: Int32

O índice no qual será iniciada a gravação do conjunto de caracteres resultante.

Retornos

Int32

O número real de caracteres gravados em chars.

Exceções

ArgumentNullException

bytes é null.

- ou -

chars é null.

ArgumentOutOfRangeException

byteIndex, byteCount ou charIndex é menor que zero.

- ou -

byteindex e byteCount não denotam um intervalo válido em bytes.

- ou -

charIndex não é um índice válido em chars.

ArgumentException

chars não tem capacidade suficiente do charIndex até o final da matriz para acomodar os caracteres resultantes.

DecoderFallbackException

Ocorreu um fallback (saiba mais em Codificação de caracteres no .NET)

-e-

DecoderFallback é definido como DecoderExceptionFallback.

Exemplos

O exemplo a seguir converte uma cadeia de caracteres de uma codificação para outra.

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 (?)

O exemplo a seguir codifica uma cadeia de caracteres em uma matriz de bytes e, em seguida, decodifica um intervalo dos bytes em uma matriz de caracteres.

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

Comentários

Para calcular o tamanho exato da matriz exigido pelo GetChars para armazenar os caracteres resultantes, você deve usar o GetCharCount método. Para calcular o tamanho máximo da matriz, use o GetMaxCharCount método. O GetCharCount método geralmente permite a alocação de menos memória, enquanto o GetMaxCharCount método geralmente é executado mais rapidamente.

GetChars(Byte[], Int32, Int32, Char[], Int32)Obtém os caracteres de uma sequência de bytes de entrada. Encoding.GetCharsé diferente de Decoder.GetChars porque o Encoding espera conversões discretas, enquanto Decoder é projetado para várias passagens em um único fluxo de entrada.

Se os dados a serem convertidos estiverem disponíveis somente em blocos sequenciais (como dados lidos de um fluxo) ou se a quantidade de dados for tão grande que precise ser dividida em blocos menores, você deverá usar o Decoder ou o Encoder fornecido pelo GetDecoder método ou pelo GetEncoder método, respectivamente, de uma classe derivada.

Observação

Esse método destina-se a operar em caracteres Unicode, não em dados binários arbitrários, como matrizes de bytes. Se você precisar codificar dados binários arbitrários em texto, deverá usar um protocolo como uuencode, que é implementado por métodos como Convert.ToBase64CharArray .

O GetCharCount método determina quantos caracteres resultam na decodificação de uma sequência de bytes e o GetChars método executa a decodificação real. O Encoding.GetChars método espera conversões discretas, ao contrário do Decoder.GetChars método, que lida com várias passagens em um único fluxo de entrada.

Há suporte para várias versões do GetCharCount e do GetChars . A seguir estão algumas considerações de programação para o uso desses métodos:

Seu aplicativo pode precisar decodificar vários bytes de entrada de uma página de código e processar os bytes usando várias chamadas. Nesse caso, é provável que você precise manter o estado entre as chamadas, pois as sequências de bytes podem ser interrompidas quando processadas em lotes. (Por exemplo, parte de uma sequência de turnos ISO-2022 pode encerrar uma GetChars chamada e continuar no início da próxima GetChars chamada. Encoding.GetChars chamará o fallback para essas sequências incompletas, mas Decoder se lembrará dessas sequências para a próxima chamada.)
Se seu aplicativo lida com saídas de cadeia de caracteres, o GetString método é recomendado. Como esse método deve verificar o comprimento da cadeia de caracteres e alocar um buffer, ele é um pouco mais lento, mas o String tipo resultante é preferencial.
A versão de byte do GetChars(Byte*, Int32, Char*, Int32) permite algumas técnicas rápidas, especialmente com várias chamadas para buffers grandes. No entanto, lembre-se de que essa versão do método às vezes não é segura, já que os ponteiros são necessários.
Se seu aplicativo precisar converter uma grande quantidade de dados, ele deverá reutilizar o buffer de saída. Nesse caso, a GetChars(Byte[], Int32, Int32, Char[], Int32) versão que dá suporte a buffers de caracteres de saída é a melhor opção.
Considere usar o Decoder.Convert método em vez de GetCharCount . O método de conversão converte o máximo de dados possível e gera uma exceção se o buffer de saída for muito pequeno. Para a decodificação contínua de um fluxo, esse método geralmente é a melhor opção.

Confira também

Aplica-se a

GetChars(Byte, Int32, Char, Int32)

Origem:: Encoding.cs

Origem:: Encoding.cs

Origem:: Encoding.cs

Importante

Esta API não está em conformidade com CLS.

Quando substituído em uma classe derivada, decodifica uma sequência de bytes iniciando no ponteiro de bytes especificado em um conjunto de caracteres começando no ponteiro de caractere especificado.

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

[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

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

Parâmetros

bytes: Byte*

Um ponteiro do primeiro byte a ser decodificado.

byteCount: Int32

O número de bytes a serem decodificados.

chars: Char*

Um ponteiro para o local no qual a gravação do conjunto de caracteres resultante deve ser iniciada.

charCount: Int32

O número máximo de caracteres a serem gravados.

Retornos

Int32

O número real de caracteres gravados no local indicado pelo parâmetro chars.

Atributos: CLSCompliantAttribute SecurityCriticalAttribute ComVisibleAttribute

Exceções

ArgumentNullException

bytes é null.

- ou -

chars é null.

ArgumentOutOfRangeException

byteCount ou charCount é menor que zero.

ArgumentException

charCount é menor que o número de caracteres resultante.

DecoderFallbackException

Ocorreu um fallback (saiba mais em Codificação de caracteres no .NET)

-e-

DecoderFallback é definido como DecoderExceptionFallback.

Comentários

Para calcular o tamanho exato da matriz que GetChars o exige para armazenar os caracteres resultantes, você deve usar o GetCharCount método. Para calcular o tamanho máximo da matriz, use o GetMaxCharCount método. O GetCharCount método geralmente permite a alocação de menos memória, enquanto o GetMaxCharCount método geralmente é executado mais rapidamente.

Encoding.GetCharsObtém os caracteres de uma sequência de bytes de entrada. Encoding.GetCharsé diferente de Decoder.GetChars porque o Encoding espera conversões discretas, enquanto Decoder é projetado para várias passagens em um único fluxo de entrada.

Se os dados a ser convertido estão disponíveis somente em blocos sequenciais (como ler de um fluxo de dados) ou se a quantidade de dados é tão grande que ele precisa ser divididos em blocos menores, você deve usar o Decoder ou o Encoder objeto fornecido pelo GetDecoder ou o GetEncoder método, respectivamente, de uma classe derivada.

Observação

Há suporte para várias versões do GetCharCount e do GetChars . A seguir estão algumas considerações de programação para o uso desses métodos:

Seu aplicativo pode precisar decodificar vários bytes de entrada de uma página de código e processar os bytes usando várias chamadas. Nesse caso, é provável que você precise manter o estado entre as chamadas, pois as sequências de bytes podem ser interrompidas quando processadas em lotes. (Por exemplo, parte de uma sequência de turnos ISO-2022 pode encerrar uma GetChars chamada e continuar no início da próxima GetChars chamada. Encoding.GetChars chamará o fallback para essas sequências incompletas, mas Decoder se lembrará dessas sequências para a próxima chamada.)
Se seu aplicativo lida com saídas de cadeia de caracteres, o GetString método é recomendado. Como esse método deve verificar o comprimento da cadeia de caracteres e alocar um buffer, ele é um pouco mais lento, mas o String tipo resultante é preferencial.
A versão de byte do GetChars(Byte*, Int32, Char*, Int32) permite algumas técnicas rápidas, especialmente com várias chamadas para buffers grandes. No entanto, lembre-se de que essa versão do método às vezes não é segura, já que os ponteiros são necessários.
Se seu aplicativo precisar converter uma grande quantidade de dados, ele deverá reutilizar o buffer de saída. Nesse caso, a GetChars(Byte[], Int32, Int32, Char[], Int32) versão que dá suporte a buffers de caracteres de saída é a melhor opção.
Considere usar o Decoder.Convert método em vez de GetCharCount . O método de conversão converte o máximo de dados possível e gera uma exceção se o buffer de saída for muito pequeno. Para a decodificação contínua de um fluxo, esse método geralmente é a melhor opção.

Confira também

Aplica-se a

GetChars(Byte[], Int32, Int32)

Origem:: Encoding.cs

Origem:: Encoding.cs

Origem:: Encoding.cs

Quando substituído em uma classe derivada, decodifica uma sequência de bytes da matriz de bytes especificada em um conjunto de caracteres.

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()

Parâmetros

bytes: Byte[]

A matriz de bytes que contém a sequência de bytes a ser decodificada.

index: Int32

O índice do primeiro byte a ser decodificado.

count: Int32

O número de bytes a serem decodificados.

Retornos

Char[]

Uma matriz de caracteres que contém os resultados da decodificação da sequência de bytes especificada.

Exceções

ArgumentNullException

bytes é null.

ArgumentOutOfRangeException

index ou count é menor que zero.

- ou -

index e count não denotam um intervalo válido em bytes.

DecoderFallbackException

Ocorreu um fallback (saiba mais em Codificação de caracteres no .NET)

-e-

DecoderFallback é definido como DecoderExceptionFallback.

Exemplos

O exemplo a seguir codifica uma cadeia de caracteres em uma matriz de bytes e, em seguida, decodifica um intervalo dos bytes em uma matriz de caracteres.

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

Comentários

Observação

Há suporte para várias versões do GetCharCount e do GetChars . A seguir estão algumas considerações de programação para o uso desses métodos:

Seu aplicativo pode precisar decodificar vários bytes de entrada de uma página de código e processar os bytes usando várias chamadas. Nesse caso, é provável que você precise manter o estado entre as chamadas, pois as sequências de bytes podem ser interrompidas quando processadas em lotes. (Por exemplo, parte de uma sequência de turnos ISO-2022 pode encerrar uma GetChars chamada e continuar no início da próxima GetChars chamada. Encoding.GetChars chamará o fallback para essas sequências incompletas, mas Decoder se lembrará dessas sequências para a próxima chamada.)
Se seu aplicativo lida com saídas de cadeia de caracteres, é recomendável usar o GetString método. Como esse método deve verificar o comprimento da cadeia de caracteres e alocar um buffer, ele é um pouco mais lento, mas o String tipo resultante é preferencial.
A versão de byte do GetChars(Byte*, Int32, Char*, Int32) permite algumas técnicas rápidas, especialmente com várias chamadas para buffers grandes. No entanto, lembre-se de que essa versão do método às vezes não é segura, já que os ponteiros são necessários.
Se seu aplicativo precisar converter uma grande quantidade de dados, ele deverá reutilizar o buffer de saída. Nesse caso, a GetChars(Byte[], Int32, Int32, Char[], Int32) versão que dá suporte a buffers de caracteres de saída é a melhor opção.
Considere usar o Decoder.Convert método em vez de GetCharCount . O método de conversão converte o máximo de dados possível e gera uma exceção se o buffer de saída for muito pequeno. Para a decodificação contínua de um fluxo, esse método geralmente é a melhor opção.

Confira também

Aplica-se a

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

Origem:: Encoding.cs

Origem:: Encoding.cs

Origem:: Encoding.cs

Quando substituído em uma classe derivada, decodifica todos os bytes no intervalo de bytes somente leitura especificado em um intervalo de caracteres.

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

Parâmetros

bytes: ReadOnlySpan<Byte>

Um intervalo somente leitura que contém a sequência de bytes a serem decodificados.

chars: Span<Char>

O intervalo de caracteres que recebe os bytes decodificados.

Retornos

Int32

O número real de caracteres gravados no intervalo indicado pelo parâmetro chars.

Comentários

Encoding.GetCharsObtém os caracteres de um intervalo de bytes de entrada. Encoding.GetCharsé diferente de Decoder.GetChars porque o Encoding espera conversões discretas, enquanto Decoder é projetado para várias passagens em um único fluxo de entrada.

Há suporte para várias versões do GetCharCount e do GetChars . A seguir estão algumas considerações de programação para o uso desses métodos:

Seu aplicativo pode precisar decodificar vários bytes de entrada de uma página de código e processar os bytes usando várias chamadas. Nesse caso, é provável que você precise manter o estado entre as chamadas, pois as sequências de bytes podem ser interrompidas quando processadas em lotes. (Por exemplo, parte de uma sequência de turnos ISO-2022 pode encerrar uma GetChars chamada e continuar no início da próxima GetChars chamada. Encoding.GetChars chamará o fallback para essas sequências incompletas, mas Decoder se lembrará dessas sequências para a próxima chamada.)
Se seu aplicativo lida com saídas de cadeia de caracteres, é recomendável usar o GetString método. Como esse método deve verificar o comprimento da cadeia de caracteres e alocar um buffer, ele é um pouco mais lento, mas o String tipo resultante é preferencial.
A versão de byte do GetChars(Byte*, Int32, Char*, Int32) permite algumas técnicas rápidas, especialmente com várias chamadas para buffers grandes. No entanto, lembre-se de que essa versão do método às vezes não é segura, já que os ponteiros são necessários.
Se seu aplicativo precisar converter uma grande quantidade de dados, ele deverá reutilizar o buffer de saída. Nesse caso, a GetChars(Byte[], Int32, Int32, Char[], Int32) versão que dá suporte a buffers de caracteres de saída é a melhor opção.
Considere usar o Decoder.Convert método em vez de GetCharCount . O método de conversão converte o máximo de dados possível e gera uma exceção se o buffer de saída for muito pequeno. Para a decodificação contínua de um fluxo, esse método geralmente é a melhor opção.

Aplica-se a

GetChars(Byte[])

Origem:: Encoding.cs

Origem:: Encoding.cs

Origem:: Encoding.cs

Quando substituído em uma classe derivada, decodifica todos os bytes na matriz de bytes especificada em um conjunto de caracteres.

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()

Parâmetros

bytes: Byte[]

A matriz de bytes que contém a sequência de bytes a ser decodificada.

Retornos

Char[]

Uma matriz de caracteres que contém os resultados da decodificação da sequência de bytes especificada.

Exceções

ArgumentNullException

bytes é null.

DecoderFallbackException

Ocorreu um fallback (saiba mais em Codificação de caracteres no .NET)

-e-

DecoderFallback é definido como DecoderExceptionFallback.

Exemplos

O exemplo a seguir codifica uma cadeia de caracteres em uma matriz de bytes e, em seguida, decodifica os bytes em uma matriz de caracteres.

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

Comentários

Observação

Há suporte para várias versões do GetCharCount e do GetChars . A seguir estão algumas considerações de programação para o uso desses métodos:

Seu aplicativo pode precisar decodificar vários bytes de entrada de uma página de código e processar os bytes usando várias chamadas. Nesse caso, é provável que você precise manter o estado entre as chamadas, pois as sequências de bytes podem ser interrompidas quando processadas em lotes. (Por exemplo, parte de uma sequência de turnos ISO-2022 pode encerrar uma GetChars chamada e continuar no início da próxima GetChars chamada. Encoding.GetChars chamará o fallback para essas sequências incompletas, mas Decoder se lembrará dessas sequências para a próxima chamada.)
Se seu aplicativo lida com saídas de cadeia de caracteres, é recomendável usar o GetString método. Como esse método deve verificar o comprimento da cadeia de caracteres e alocar um buffer, ele é um pouco mais lento, mas o String tipo resultante é preferencial.
A versão de byte do GetChars(Byte*, Int32, Char*, Int32) permite algumas técnicas rápidas, especialmente com várias chamadas para buffers grandes. No entanto, lembre-se de que essa versão do método às vezes não é segura, já que os ponteiros são necessários.
Se seu aplicativo precisar converter uma grande quantidade de dados, ele deverá reutilizar o buffer de saída. Nesse caso, a GetChars(Byte[], Int32, Int32, Char[], Int32) versão que dá suporte a buffers de caracteres de saída é a melhor opção.
Considere usar o Decoder.Convert método em vez de GetCharCount . O método de conversão converte o máximo de dados possível e gera uma exceção se o buffer de saída for muito pequeno. Para a decodificação contínua de um fluxo, esse método geralmente é a melhor opção.

Confira também

Aplica-se a

Compartilhar via

Encoding.GetChars Método

Definição

Sobrecargas

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

Parâmetros

Retornos

Exceções

Exemplos

Comentários

Confira também

Aplica-se a

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

Parâmetros

Retornos

Exceções

Comentários

Confira também

Aplica-se a

GetChars(Byte[], Int32, Int32)

Parâmetros

Retornos

Exceções

Exemplos

Comentários

Confira também

Aplica-se a

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

Parâmetros

Retornos

Comentários

Aplica-se a

GetChars(Byte[])

Parâmetros

Retornos

Exceções

Exemplos

Comentários

Confira também

Aplica-se a

Recursos adicionais

GetChars(Byte, Int32, Char, Int32)