UTF8Encoding.GetBytes Método

Definição

Codifica um conjunto de caracteres em uma sequência de bytes.Encodes a set of characters into a sequence of bytes.

Sobrecargas

GetBytes(String)

Codifica os caracteres em um objeto String especificado em uma sequência de bytes.Encodes the characters in a specified String object into a sequence of bytes.

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

Codifica o intervalo de caracteres especificado no intervalo de bytes especificado.Encodes the specified character span into the specified byte span.

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

Codifica um conjunto de caracteres começando no ponteiro de caractere especificado em uma sequência de bytes armazenados começando no ponteiro de byte especificado.Encodes a set of characters starting at the specified character pointer into a sequence of bytes that are stored starting at the specified byte pointer.

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

Codifica um conjunto de caracteres da matriz de caracteres especificada na matriz de bytes especificada.Encodes a set of characters from the specified character array into the specified byte array.

GetBytes(String, Int32, Int32, Byte[], Int32)

Codifica um conjunto de caracteres do String especificado para a matriz de bytes especificada.Encodes a set of characters from the specified String into the specified byte array.

GetBytes(String)

Codifica os caracteres em um objeto String especificado em uma sequência de bytes.Encodes the characters in a specified String object into a sequence of bytes.

public:
 override cli::array <System::Byte> ^ GetBytes(System::String ^ s);
public override byte[] GetBytes (string s);
override this.GetBytes : string -> byte[]
Public Overrides Function GetBytes (s As String) As Byte()

Parâmetros

s
String

A cadeia de caracteres a ser codificada.The character string to encode.

Retornos

Byte[]

Uma matriz de bytes que contém os caracteres codificados na cadeia de caracteres especificada pelo parâmetro s.A byte array that contains the encoded characters in the string specified by the s parameter.

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

Codifica o intervalo de caracteres especificado no intervalo de bytes especificado.Encodes the specified character span into the specified byte span.

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

Parâmetros

chars
ReadOnlySpan<Char>

O intervalo de caracteres a ser codificado.The character span to encode.

bytes
Span<Byte>

O intervalo que deve conter o conjunto de bytes resultante.The span to contain the resulting set of bytes.

Retornos

O número real de bytes gravados no bytes.The actual number of bytes written into bytes.

Comentários

Para calcular o tamanho exato exigido pelo GetBytes para armazenar os bytes resultantes, chame o método GetByteCount.To calculate the exact size required by GetBytes to store the resulting bytes, you call the GetByteCount method. Para calcular o tamanho máximo, você chama o método GetMaxByteCount.To calculate the maximum size, you call the GetMaxByteCount method. O método GetByteCount geralmente aloca menos memória, enquanto o método GetMaxByteCount geralmente é executado mais rapidamente.The GetByteCount method generally allocates less memory, while the GetMaxByteCount method generally executes faster.

Com a detecção de erro, uma sequência inválida faz com que esse método gere uma exceção de ArgumentException.With error detection, an invalid sequence causes this method to throw an ArgumentException exception. Sem a detecção de erros, as sequências inválidas são ignoradas e nenhuma exceção é lançada.Without error detection, invalid sequences are ignored, and no exception is thrown.

Os dados a serem convertidos, como dados lidos de um fluxo, podem estar disponíveis somente em blocos sequenciais.Data to be converted, such as data read from a stream, might be available only in sequential blocks. Nesse caso, ou se a quantidade de dados for tão grande que precisa ser dividida em blocos menores, use o Decoder ou o Encoder retornado pelo método GetDecoder ou pelo método GetEncoder, respectivamente.In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, use the Decoder or the Encoder returned by the GetDecoder method or the GetEncoder method, respectively.

Para garantir que os bytes codificados sejam decodificados corretamente quando eles são salvos como um arquivo ou como um fluxo, você pode prefixar um fluxo de bytes codificados com um preâmbulo.To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. A inserção do preâmbulo no início de um fluxo de bytes (como no início de uma série de bytes a ser gravado em um arquivo) é a responsabilidade do desenvolvedor.Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility. O método GetBytes não precede um preâmbulo para o início de uma sequência de bytes codificados.The GetBytes method does not prepend a preamble to the beginning of a sequence of encoded bytes.

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

Importante

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

Codifica um conjunto de caracteres começando no ponteiro de caractere especificado em uma sequência de bytes armazenados começando no ponteiro de byte especificado.Encodes a set of characters starting at the specified character pointer into a sequence of bytes that are stored starting at the specified byte pointer.

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

Parâmetros

chars
Char*

Um ponteiro para o primeiro caractere a ser codificado.A pointer to the first character to encode.

charCount
Int32

O número de caracteres a ser codificado.The number of characters to encode.

bytes
Byte*

Um ponteiro para o local no qual a gravação da sequência de bytes resultante deve ser iniciada.A pointer to the location at which to start writing the resulting sequence of bytes.

byteCount
Int32

O número de máximo de bytes a serem gravados.The maximum number of bytes to write.

Retornos

O número real de bytes gravados no local indicado por bytes.The actual number of bytes written at the location indicated by bytes.

Atributos

Exceções

chars é null.chars is null.

- ou --or- bytes é null.bytes is null.

charCount ou byteCount é menor que zero.charCount or byteCount is less than zero.

A detecção de erros está habilitada e chars contém uma sequência de caracteres inválida.Error detection is enabled, and chars contains an invalid sequence of characters.

- ou --or- byteCount é menor que o número de bytes resultante.byteCount is less than the resulting number of bytes.

Ocorreu um fallback (saiba mais em Codificação de caracteres no .NET)A fallback occurred (for more information, see Character Encoding in .NET) -e--and- EncoderFallback é definido como EncoderExceptionFallback.EncoderFallback is set to EncoderExceptionFallback.

Comentários

Para calcular o tamanho exato da matriz exigido pelo GetBytes para armazenar os bytes resultantes, chame o método GetByteCount.To calculate the exact array size required by GetBytes to store the resulting bytes, you call the GetByteCount method. Para calcular o tamanho máximo da matriz, chame o método GetMaxByteCount.To calculate the maximum array size, you call the GetMaxByteCount method. O método GetByteCount geralmente aloca menos memória, enquanto o método GetMaxByteCount geralmente é executado mais rapidamente.The GetByteCount method generally allocates less memory, while the GetMaxByteCount method generally executes faster.

Com a detecção de erro, uma sequência inválida faz com que esse método gere uma exceção de ArgumentException.With error detection, an invalid sequence causes this method to throw an ArgumentException exception. Sem a detecção de erros, as sequências inválidas são ignoradas e nenhuma exceção é lançada.Without error detection, invalid sequences are ignored, and no exception is thrown.

Os dados a serem convertidos, como dados lidos de um fluxo, podem estar disponíveis somente em blocos sequenciais.Data to be converted, such as data read from a stream, might be available only in sequential blocks. Nesse caso, ou se a quantidade de dados for tão grande que precisa ser dividida em blocos menores, use o Decoder ou o Encoder retornado pelo método GetDecoder ou pelo método GetEncoder, respectivamente.In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, use the Decoder or the Encoder returned by the GetDecoder method or the GetEncoder method, respectively.

Para garantir que os bytes codificados sejam decodificados corretamente quando eles são salvos como um arquivo ou como um fluxo, você pode prefixar um fluxo de bytes codificados com um preâmbulo.To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. A inserção do preâmbulo no início de um fluxo de bytes (como no início de uma série de bytes a ser gravado em um arquivo) é a responsabilidade do desenvolvedor.Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility. O método GetBytes não precede um preâmbulo para o início de uma sequência de bytes codificados.The GetBytes method does not prepend a preamble to the beginning of a sequence of encoded bytes.

Veja também

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

Codifica um conjunto de caracteres da matriz de caracteres especificada na matriz de bytes especificada.Encodes a set of characters from the specified character array into the specified byte array.

public:
 override int GetBytes(cli::array <char> ^ chars, int charIndex, int charCount, cli::array <System::Byte> ^ bytes, int byteIndex);
public override int GetBytes (char[] chars, int charIndex, int charCount, byte[] bytes, int byteIndex);
override this.GetBytes : char[] * int * int * byte[] * int -> int
Public Overrides Function GetBytes (chars As Char(), charIndex As Integer, charCount As Integer, bytes As Byte(), byteIndex As Integer) As Integer

Parâmetros

chars
Char[]

A matriz de caracteres que contém o conjunto de caracteres a serem codificados.The character array containing the set of characters to encode.

charIndex
Int32

O índice do primeiro caractere a ser codificado.The index of the first character to encode.

charCount
Int32

O número de caracteres a ser codificado.The number of characters to encode.

bytes
Byte[]

A matriz de bytes que conterá a sequência de bytes resultante.The byte array to contain the resulting sequence of bytes.

byteIndex
Int32

O índice no qual será iniciada a gravação da sequência de bytes resultante.The index at which to start writing the resulting sequence of bytes.

Retornos

O número real de bytes gravados no bytes.The actual number of bytes written into bytes.

Exceções

chars é null.chars is null.

- ou --or- bytes é null.bytes is null.

charIndex, charCount ou byteIndex é menor que zero.charIndex or charCount or byteIndex is less than zero.

- ou --or- charIndex e charCount não denotam um intervalo válido em chars.charIndex and charCount do not denote a valid range in chars.

- ou --or- byteIndex não é um índice válido em bytes.byteIndex is not a valid index in bytes.

A detecção de erros está habilitada e chars contém uma sequência de caracteres inválida.Error detection is enabled, and chars contains an invalid sequence of characters.

- ou --or- O bytes não tem capacidade suficiente do byteIndex ao final da matriz para acomodar os bytes resultantes.bytes does not have enough capacity from byteIndex to the end of the array to accommodate the resulting bytes.

Ocorreu um fallback (saiba mais em Codificação de caracteres no .NET)A fallback occurred (for more information, see Character Encoding in .NET) -e--and- EncoderFallback é definido como EncoderExceptionFallback.EncoderFallback is set to EncoderExceptionFallback.

Exemplos

O exemplo a seguir usa o método GetBytes para codificar um intervalo de caracteres a partir de uma cadeia de caracteres e armazena os bytes codificados em um intervalo de elementos em uma matriz de bytes.The following example uses the GetBytes method to encode a range of characters from a string and stores the encoded bytes in a range of elements in a byte array.

using namespace System;
using namespace System::Text;
using namespace System::Collections;
int main()
{
   array<Byte>^bytes;
   String^ chars = "UTF8 Encoding Example";
   UTF8Encoding^ utf8 = gcnew UTF8Encoding;
   int byteCount = utf8->GetByteCount( chars->ToCharArray(), 0, 13 );
   bytes = gcnew array<Byte>(byteCount);
   int bytesEncodedCount = utf8->GetBytes( chars, 0, 13, bytes, 0 );
   Console::WriteLine( "{0} bytes used to encode string.", bytesEncodedCount );
   Console::Write( "Encoded bytes: " );
   IEnumerator^ myEnum = bytes->GetEnumerator();
   while ( myEnum->MoveNext() )
   {
      Byte b = safe_cast<Byte>(myEnum->Current);
      Console::Write( "[{0}]", b );
   }

   Console::WriteLine();
}

using System;
using System.Text;

class UTF8EncodingExample {
    public static void Main() {
        Byte[] bytes;
        String chars = "UTF8 Encoding Example";
        
        UTF8Encoding utf8 = new UTF8Encoding();
        
        int byteCount = utf8.GetByteCount(chars.ToCharArray(), 0, 13);
        bytes = new Byte[byteCount];
        int bytesEncodedCount = utf8.GetBytes(chars, 0, 13, bytes, 0);
        
        Console.WriteLine(
            "{0} bytes used to encode string.", bytesEncodedCount
        );

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

Class UTF8EncodingExample
    
    Public Shared Sub Main()
        Dim bytes() As Byte
        Dim chars As String = "UTF8 Encoding Example"
        
        Dim utf8 As New UTF8Encoding()
        
        Dim byteCount As Integer = utf8.GetByteCount(chars.ToCharArray(), 0, 13)
        bytes = New Byte(byteCount - 1) {}
        Dim bytesEncodedCount As Integer = utf8.GetBytes(chars, 0, 13, bytes, 0)
        
        Console.WriteLine("{0} bytes used to encode string.", 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

Comentários

Para calcular o tamanho exato da matriz exigido pelo GetBytes para armazenar os bytes resultantes, chame o método GetByteCount.To calculate the exact array size required by GetBytes to store the resulting bytes, you call the GetByteCount method. Para calcular o tamanho máximo da matriz, chame o método GetMaxByteCount.To calculate the maximum array size, you call the GetMaxByteCount method. O método GetByteCount geralmente aloca menos memória, enquanto o método GetMaxByteCount geralmente é executado mais rapidamente.The GetByteCount method generally allocates less memory, while the GetMaxByteCount method generally executes faster.

Com a detecção de erro, uma sequência inválida faz com que esse método gere uma exceção de ArgumentException.With error detection, an invalid sequence causes this method to throw an ArgumentException exception. Sem a detecção de erros, as sequências inválidas são ignoradas e nenhuma exceção é lançada.Without error detection, invalid sequences are ignored, and no exception is thrown.

Os dados a serem convertidos, como dados lidos de um fluxo, podem estar disponíveis somente em blocos sequenciais.Data to be converted, such as data read from a stream, might be available only in sequential blocks. Nesse caso, ou se a quantidade de dados for tão grande que precisa ser dividida em blocos menores, use o Decoder ou o Encoder fornecido pelo método GetDecoder ou o método GetEncoder, respectivamente.In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, use the Decoder or the Encoder provided by the GetDecoder method or the GetEncoder method, respectively.

Para garantir que os bytes codificados sejam decodificados corretamente quando eles são salvos como um arquivo ou como um fluxo, você pode prefixar um fluxo de bytes codificados com um preâmbulo.To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. A inserção do preâmbulo no início de um fluxo de bytes (como no início de uma série de bytes a ser gravado em um arquivo) é a responsabilidade do desenvolvedor.Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility. O método GetBytes não precede um preâmbulo para o início de uma sequência de bytes codificados.The GetBytes method does not prepend a preamble to the beginning of a sequence of encoded bytes.

Veja também

GetBytes(String, Int32, Int32, Byte[], Int32)

Codifica um conjunto de caracteres do String especificado para a matriz de bytes especificada.Encodes a set of characters from the specified String into the specified byte array.

public:
 override int GetBytes(System::String ^ s, int charIndex, int charCount, cli::array <System::Byte> ^ bytes, int byteIndex);
public override int GetBytes (string s, int charIndex, int charCount, byte[] bytes, int byteIndex);
override this.GetBytes : string * int * int * byte[] * int -> int
Public Overrides Function GetBytes (s As String, charIndex As Integer, charCount As Integer, bytes As Byte(), byteIndex As Integer) As Integer

Parâmetros

s
String

O String que contém o conjunto de caracteres a ser codificado.The String containing the set of characters to encode.

charIndex
Int32

O índice do primeiro caractere a ser codificado.The index of the first character to encode.

charCount
Int32

O número de caracteres a ser codificado.The number of characters to encode.

bytes
Byte[]

A matriz de bytes que conterá a sequência de bytes resultante.The byte array to contain the resulting sequence of bytes.

byteIndex
Int32

O índice no qual será iniciada a gravação da sequência de bytes resultante.The index at which to start writing the resulting sequence of bytes.

Retornos

O número real de bytes gravados no bytes.The actual number of bytes written into bytes.

Exceções

s é null.s is null.

- ou --or- bytes é null.bytes is null.

charIndex, charCount ou byteIndex é menor que zero.charIndex or charCount or byteIndex is less than zero.

- ou --or- charIndex e charCount não denotam um intervalo válido em chars.charIndex and charCount do not denote a valid range in chars.

- ou --or- byteIndex não é um índice válido em bytes.byteIndex is not a valid index in bytes.

A detecção de erros está habilitada e s contém uma sequência de caracteres inválida.Error detection is enabled, and s contains an invalid sequence of characters.

- ou --or- O bytes não tem capacidade suficiente do byteIndex ao final da matriz para acomodar os bytes resultantes.bytes does not have enough capacity from byteIndex to the end of the array to accommodate the resulting bytes.

Ocorreu um fallback (saiba mais em Codificação de caracteres no .NET)A fallback occurred (for more information, see Character Encoding in .NET) -e--and- EncoderFallback é definido como EncoderExceptionFallback.EncoderFallback is set to EncoderExceptionFallback.

Exemplos

O exemplo a seguir usa o método GetBytes para codificar um intervalo de elementos de uma matriz de caracteres Unicode e armazenar os bytes codificados em um intervalo de elementos em uma matriz de bytes.The following example uses the GetBytes method to encode a range of elements from a Unicode character array and store the encoded bytes in a range of elements in a byte array.

using namespace System;
using namespace System::Text;
using namespace System::Collections;
int main()
{
   array<Byte>^bytes;
   
   // Unicode characters.
   
   // Pi
   // Sigma
   array<Char>^chars = {L'\u03a0',L'\u03a3',L'\u03a6',L'\u03a9'};
   UTF8Encoding^ utf8 = gcnew UTF8Encoding;
   int byteCount = utf8->GetByteCount( chars, 1, 2 );
   bytes = gcnew array<Byte>(byteCount);
   int bytesEncodedCount = utf8->GetBytes( chars, 1, 2, bytes, 0 );
   Console::WriteLine( "{0} bytes used to encode characters.", bytesEncodedCount );
   Console::Write( "Encoded bytes: " );
   IEnumerator^ myEnum = bytes->GetEnumerator();
   while ( myEnum->MoveNext() )
   {
      Byte b = safe_cast<Byte>(myEnum->Current);
      Console::Write( "[{0}]", b );
   }

   Console::WriteLine();
}

using System;
using System.Text;

class UTF8EncodingExample {
    public static void Main() {
        Byte[] bytes;
        // Unicode characters.
        Char[] chars = new Char[] {
            '\u0023', // #
            '\u0025', // %
            '\u03a0', // Pi
            '\u03a3'  // Sigma
        };
        
        UTF8Encoding utf8 = new UTF8Encoding();
        
        int byteCount = utf8.GetByteCount(chars, 1, 2);
        bytes = new Byte[byteCount];
        int bytesEncodedCount = utf8.GetBytes(chars, 1, 2, bytes, 0);
        
        Console.WriteLine(
            "{0} bytes used to encode characters.", bytesEncodedCount
        );

        Console.Write("Encoded bytes: ");
        foreach (Byte b in bytes) {
            Console.Write("[{0}]", b);
        }
        Console.WriteLine();
    }
}
Imports System.Text
Imports Microsoft.VisualBasic.Strings

Class UTF8EncodingExample
    
    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 utf8 As New UTF8Encoding()
        
        Dim byteCount As Integer = utf8.GetByteCount(chars, 1, 2)
        bytes = New Byte(byteCount - 1) {}
        Dim bytesEncodedCount As Integer = utf8.GetBytes(chars, 1, 2, bytes, 0)
        
        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

Comentários

Para calcular o tamanho exato da matriz exigido pelo GetBytes para armazenar os bytes resultantes, chame o método GetByteCount.To calculate the exact array size required by GetBytes to store the resulting bytes, you call the GetByteCount method. Para calcular o tamanho máximo da matriz, chame o método GetMaxByteCount.To calculate the maximum array size, you call the GetMaxByteCount method. O método GetByteCount geralmente aloca menos memória, enquanto o método GetMaxByteCount geralmente é executado mais rapidamente.The GetByteCount method generally allocates less memory, while the GetMaxByteCount method generally executes faster.

Com a detecção de erro, uma sequência inválida faz com que esse método gere uma exceção de ArgumentException.With error detection, an invalid sequence causes this method to throw an ArgumentException exception. Sem a detecção de erros, as sequências inválidas são ignoradas e nenhuma exceção é lançada.Without error detection, invalid sequences are ignored, and no exception is thrown.

Os dados a serem convertidos, como dados lidos de um fluxo, podem estar disponíveis somente em blocos sequenciais.Data to be converted, such as data read from a stream, might be available only in sequential blocks. Nesse caso, ou se a quantidade de dados for tão grande que precisa ser dividida em blocos menores, use o Decoder ou o Encoder fornecido pelo método GetDecoder ou o método GetEncoder, respectivamente.In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, use the Decoder or the Encoder provided by the GetDecoder method or the GetEncoder method, respectively.

Para garantir que os bytes codificados sejam decodificados corretamente quando eles são salvos como um arquivo ou como um fluxo, você pode prefixar um fluxo de bytes codificados com um preâmbulo.To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. A inserção do preâmbulo no início de um fluxo de bytes (como no início de uma série de bytes a ser gravado em um arquivo) é a responsabilidade do desenvolvedor.Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility. O método GetBytes não precede um preâmbulo para o início de uma sequência de bytes codificados.The GetBytes method does not prepend a preamble to the beginning of a sequence of encoded bytes.

Veja também

Aplica-se a