Encoding.GetChars Método

Definição

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 (byte[] bytes, int byteIndex, int byteCount, char[] chars, int charIndex);

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

O número real de caracteres gravados em chars.

Exceções

bytes é null.

- ou -

chars é null.

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.

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

Exemplos

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

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

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

*/

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

.NET 9 e outras versões
Produto Versões
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 1.1, 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.6, 2.0, 2.1
UWP 10.0

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.

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

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

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

Atributos

Exceções

bytes é null.

- ou -

chars é null.

byteCount ou charCount é menor que zero.

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

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

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

.NET 9 e outras versões
Produto Versões
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.3, 1.4, 1.6, 2.0, 2.1
UWP 10.0

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 char[] GetChars (byte[] bytes, int index, int count);

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

bytes é null.

index ou count é menor que zero.

- ou -

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

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

*/

Comentários

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 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, é 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

.NET 9 e outras versões
Produto Versões
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 1.1, 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.6, 2.0, 2.1
UWP 10.0

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<byte> bytes, Span<char> chars);

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

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.

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.

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, é 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

.NET 9 e outras versões
Produto Versões
.NET Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Standard 2.1

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 char[] GetChars (byte[] bytes);

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

bytes é null.

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 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ăǽβ

*/

Comentários

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 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, é 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

.NET 9 e outras versões
Produto Versões
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 1.1, 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.6, 2.0, 2.1
UWP 10.0