Encoder.GetBytes Método

Definição

Espaço de Nomes:
System.Text
Assemblagem:
netstandard.dll
Assemblagem:
mscorlib.dll
Assemblagens:
mscorlib.dll, System.Text.Encoding.dll
Assemblagem:
System.Text.Encoding.dll

Quando sobrescrito numa classe derivada, codifica um conjunto de caracteres numa sequência de bytes.

Sobrecargas

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

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

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

Quando sobrescrito numa classe derivada, codifica um conjunto de caracteres do array de caracteres especificado e quaisquer caracteres do buffer interno no array de bytes especificado. Um parâmetro indica se deve limpar o estado interno do codificador após a conversão.

Observações

Lembre-se que o Encoder objeto guarda estado entre chamadas para GetBytes. Quando a aplicação termina com um fluxo de dados, deve definir o flush parâmetro para true na última chamada para GetBytes garantir que a informação de estado é limpa e que os bytes codificados são corretamente terminados. Com esta configuração, o codificador ignora bytes inválidos no final do bloco de dados, como substitutos não correspondidos ou sequências combinadas incompletas, e limpa o buffer interno.

Para calcular o tamanho exato do buffer que GetBytes requer armazenar os caracteres resultantes, a aplicação deve usar GetByteCount.

Se GetBytes for chamado com flush definido para false, o codificador armazena bytes finais no final do bloco de dados num buffer interno e usa-os na próxima operação de codificação. A aplicação deve invocar GetByteCount um bloco de dados imediatamente antes de chamar GetBytes o mesmo bloco, para que quaisquer caracteres finais do bloco anterior sejam incluídos no cálculo.

Se a sua aplicação for converter muitos segmentos de um fluxo de entrada, considere usar o Convert método. GetBytes Lança uma exceção se o buffer de saída não for suficientemente grande, mas Convert preenche o máximo de espaço possível e devolve os caracteres lidos e bytes escritos. Veja também o Encoding.GetBytes tópico para mais comentários.

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

Quando sobreposto numa classe derivada, codifica um conjunto de caracteres no intervalo de caracteres de entrada e quaisquer caracteres no buffer interno numa sequência de bytes que são armazenados no intervalo de bytes de entrada. Um parâmetro indica se deve limpar o estado interno do codificador 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 espaço de caracteres para codificar.

bytes
Span<Byte>

Um intervalo de bytes para escrever a sequência resultante de bytes.

flush
Boolean

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

Devoluções

Int32

O número real de bytes escritos na localização indicada pelo bytes parâmetro.

Aplica-se a

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

Importante

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

Quando sobreposto numa classe derivada, codifica um conjunto de caracteres começando no ponteiro de caracteres especificado e quaisquer caracteres do buffer interno numa sequência de bytes que são armazenados a partir do ponteiro de bytes especificado. Um parâmetro indica se deve limpar o estado interno do codificador 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 apontador para o primeiro carácter a codificar.

charCount
Int32

O número de caracteres a codificar.

bytes
Byte*

Um apontador para o local onde começar a escrever a sequência resultante de bytes.

byteCount
Int32

O número máximo de bytes a escrever.

flush
Boolean

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

Devoluções

Int32

O número real de bytes escritos na localização indicada pelo bytes parâmetro.

Atributos
CLSCompliantAttribute ComVisibleAttribute SecurityCriticalAttribute

Exceções

ArgumentNullException

chars é null (Nothing).

-ou-

bytes é null (Nothing).

ArgumentOutOfRangeException

charCount ou byteCount é inferior a zero.

ArgumentException

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

EncoderFallbackException

Ocorreu um recurso de recurso (para mais informações, veja Codificação de Caracteres em .NET)

- e -

Fallback está definido como EncoderExceptionFallback.

Aplica-se a

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

Quando sobrescrito numa classe derivada, codifica um conjunto de caracteres do array de caracteres especificado e quaisquer caracteres do buffer interno no array de bytes especificado. Um parâmetro indica se deve limpar o estado interno do codificador 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[]

O array de caracteres que contém o conjunto de caracteres a codificar.

charIndex
Int32

O índice do primeiro carácter a codificar.

charCount
Int32

O número de caracteres a codificar.

bytes
Byte[]

O array de bytes para conter a sequência resultante de bytes.

byteIndex
Int32

O índice onde começar a escrever a sequência resultante de bytes.

flush
Boolean

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

Devoluções

Int32

O número real de bytes escritos 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 denotam um intervalo válido em chars.

-ou-

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

ArgumentException

bytes não tem capacidade suficiente de byteIndex até ao fim do array para acomodar os bytes resultantes.

EncoderFallbackException

Ocorreu um recurso de recurso (para mais informações, veja Codificação de Caracteres em .NET)

- e -

Fallback está definido como EncoderExceptionFallback.

Exemplos

O exemplo seguinte demonstra como codificar um conjunto de elementos a partir de um array de caracteres e armazenar os bytes codificados num conjunto de elementos num array de bytes. O GetByteCount método é usado para determinar o tamanho do array exigido 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