Encoder.GetBytes Método

Definição

Namespace:
System.Text
Assembly:
netstandard.dll
Assembly:
mscorlib.dll
Assemblies:
mscorlib.dll, System.Text.Encoding.dll
Assembly:
System.Text.Encoding.dll

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

Sobrecargas

Nome Description
GetBytes(ReadOnlySpan<Char>, Span<Byte>, Boolean)

Quando substituído em uma classe derivada, codifica um conjunto de caracteres no intervalo de caracteres de entrada e quaisquer caracteres no buffer interno em uma sequência de bytes que são armazenados no intervalo de bytes de entrada. Um parâmetro indica se o estado interno do codificador deve ser limpo após a conversão.
GetBytes(Char*, Int32, Byte*, Int32, Boolean)

Quando substituído em uma classe derivada, codifica um conjunto de caracteres começando no ponteiro de caractere especificado e quaisquer caracteres no buffer interno em uma sequência de bytes que são armazenados a partir do ponteiro de bytes especificado. Um parâmetro indica se o estado interno do codificador deve ser limpo após a conversão.
GetBytes(Char[], Int32, Int32, Byte[], Int32, Boolean)

Quando substituído em uma classe derivada, codifica um conjunto de caracteres da matriz de caracteres especificada e quaisquer caracteres no buffer interno na matriz de bytes especificada. Um parâmetro indica se o estado interno do codificador deve ser limpo após a conversão.

Comentários

Lembre-se de que o objeto salva o Encoder estado entre chamadas para GetBytes. Quando o aplicativo for feito com um fluxo de dados, ele deverá definir o flush parâmetro true na última chamada para GetBytes garantir que as informações de estado sejam liberadas e que os bytes codificados sejam encerrados corretamente. Com essa configuração, o codificador ignora bytes inválidos no final do bloco de dados, como substitutos incompatíveis ou sequências de combinação incompletas, e limpa o buffer interno.

Para calcular o tamanho exato do buffer que GetBytes requer armazenar os caracteres resultantes, o aplicativo deve usar GetByteCount.

Se GetBytes for chamado com flush set to false, o codificador armazenará bytes à direita no final do bloco de dados em um buffer interno e os usará na próxima operação de codificação. O aplicativo deve chamar GetByteCount um bloco de dados imediatamente antes de chamar GetBytes no mesmo bloco, para que todos os caracteres à direita do bloco anterior sejam incluídos no cálculo.

Se o aplicativo quiser converter muitos segmentos de um fluxo de entrada, considere usar o Convert método. GetBytes gerará uma exceção se o buffer de saída não for grande o suficiente, mas Convert preencherá o máximo de espaço possível e retornará os caracteres lidos e bytes gravados. Consulte também o Encoding.GetBytes tópico para obter mais comentários.

GetBytes(ReadOnlySpan<Char>, Span<Byte>, Boolean)

Quando substituído em uma classe derivada, codifica um conjunto de caracteres no intervalo de caracteres de entrada e quaisquer caracteres no buffer interno em uma sequência de bytes que são armazenados no intervalo de bytes de entrada. Um parâmetro indica se o estado interno do codificador deve ser limpo após a conversão.

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

Parâmetros

chars
ReadOnlySpan<Char>

Um intervalo de caracteres para codificar.

bytes
Span<Byte>

Um intervalo de bytes para o qual gravar a sequência resultante de bytes.

flush
Boolean

true para limpar o estado interno do codificador após a conversão; caso contrário, false.

Retornos

Int32

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

Aplica-se a

GetBytes(Char*, Int32, Byte*, Int32, Boolean)

Importante

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

Quando substituído em uma classe derivada, codifica um conjunto de caracteres começando no ponteiro de caractere especificado e quaisquer caracteres no buffer interno em uma sequência de bytes que são armazenados a partir do ponteiro de bytes especificado. Um parâmetro indica se o estado interno do codificador deve ser limpo após a conversão.

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

Parâmetros

chars
Char*

Um ponteiro para o primeiro caractere a ser codificado.

charCount
Int32

O número de caracteres a serem codificados.

bytes
Byte*

Um ponteiro para o local no qual começar a gravar a sequência resultante de bytes.

byteCount
Int32

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

flush
Boolean

true para limpar o estado interno do codificador após a conversão; caso contrário, false.

Retornos

Int32

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

Atributos
CLSCompliantAttribute ComVisibleAttribute SecurityCriticalAttribute

Exceções

ArgumentNullException

chars é null (Nothing).

-ou-

bytes é null (Nothing).

ArgumentOutOfRangeException

charCount ou byteCount é menor que zero.

ArgumentException

byteCount é menor que o número resultante de bytes.

EncoderFallbackException

Ocorreu um fallback (para obter mais informações, consulte Codificação de caracteres no .NET)

-e-

Fallback é definido como EncoderExceptionFallback.

Aplica-se a

GetBytes(Char[], Int32, Int32, Byte[], Int32, Boolean)

Quando substituído em uma classe derivada, codifica um conjunto de caracteres da matriz de caracteres especificada e quaisquer caracteres no buffer interno na matriz de bytes especificada. Um parâmetro indica se o estado interno do codificador deve ser limpo após a conversão.

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

Parâmetros

chars
Char[]

A matriz de caracteres que contém o conjunto de caracteres a serem codificados.

charIndex
Int32

O índice do primeiro caractere a ser codificado.

charCount
Int32

O número de caracteres a serem codificados.

bytes
Byte[]

A matriz de bytes para conter a sequência resultante de bytes.

byteIndex
Int32

O índice no qual começar a gravar a sequência resultante de bytes.

flush
Boolean

true para limpar o estado interno do codificador após a conversão; caso contrário, false.

Retornos

Int32

O número real de bytes gravados em bytes.

Exceções

ArgumentNullException

chars é null (Nothing).

-ou-

bytes é null (Nothing).

ArgumentOutOfRangeException

charIndex ou charCount ou byteIndex é menor que zero.

-ou-

charIndex e charCount não denotar um intervalo válido em chars.

-ou-

byteIndex não é um índice válido em bytes.

ArgumentException

bytes não tem capacidade suficiente do byteIndex final da matriz para acomodar os bytes resultantes.

EncoderFallbackException

Ocorreu um fallback (para obter mais informações, consulte Codificação de caracteres no .NET)

-e-

Fallback é definido como EncoderExceptionFallback.

Exemplos

O exemplo a seguir demonstra como codificar um intervalo de elementos de uma matriz de caracteres e armazenar os bytes codificados em um intervalo de elementos em uma matriz de bytes. O GetByteCount método é usado para determinar o tamanho da matriz exigida por GetBytes.

using System;
using System.Text;

class EncoderExample {
    public static void Main() {
        Byte[] bytes;
        // Unicode characters.
        Char[] chars = new Char[] {
            '\u0023', // #
            '\u0025', // %
            '\u03a0', // Pi
            '\u03a3'  // Sigma
        };
        
        Encoder uniEncoder = Encoding.Unicode.GetEncoder();
        
        int byteCount = uniEncoder.GetByteCount(chars, 0, chars.Length, true);
        bytes = new Byte[byteCount];
        int bytesEncodedCount = uniEncoder.GetBytes(chars, 0, chars.Length, bytes, 0, true);
        
        Console.WriteLine(
            "{0} bytes used to encode characters.", bytesEncodedCount
        );

        Console.Write("Encoded bytes: ");
        foreach (Byte b in bytes) {
            Console.Write("[{0}]", b);
        }
        Console.WriteLine();
    }
}

/* This code example produces the following output.

8 bytes used to encode characters.
Encoded bytes: [35][0][37][0][160][3][163][3]

*/

Imports System.Text
Imports Microsoft.VisualBasic.Strings

Class EncoderExample
    
    Public Shared Sub Main()
        Dim bytes() As Byte
        ' Unicode characters.
        ' ChrW(35)  = #
        ' ChrW(37)  = %
        ' ChrW(928) = Pi
        ' ChrW(931) = Sigma
        Dim chars() As Char = {ChrW(35), ChrW(37), ChrW(928), ChrW(931)}
        
        Dim uniEncoder As Encoder = Encoding.Unicode.GetEncoder()
        
        Dim byteCount As Integer = _
            uniEncoder.GetByteCount(chars, 0, chars.Length, True)
        bytes = New Byte(byteCount - 1) {}
        Dim bytesEncodedCount As Integer = _
            uniEncoder.GetBytes(chars, 0, chars.Length, bytes, 0, True)
        
        Console.WriteLine( _
            "{0} bytes used to encode characters.", _
            bytesEncodedCount _
        )
        
        Console.Write("Encoded bytes: ")
        Dim b As Byte
        For Each b In  bytes
            Console.Write("[{0}]", b)
        Next b
        Console.WriteLine()
    End Sub
End Class

'This code example produces the following output.
'8 bytes used to encode characters.
'Encoded bytes: [35][0][37][0][160][3][163][3]
'

Aplica-se a