Encoder.GetBytes Encoder.GetBytes Encoder.GetBytes Encoder.GetBytes Method

Definición

Cuando se reemplaza en una clase derivada, codifica un juego de caracteres en una secuencia de bytes.When overridden in a derived class, encodes a set of characters into a sequence of bytes.

Sobrecargas

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

Cuando se reemplaza en una clase derivada, codifica un juego de caracteres a partir del puntero de carácter especificado y cualquier carácter del búfer interno en una secuencia de bytes que se almacenan a partir del puntero de byte especificado.When overridden in a derived class, encodes a set of characters starting at the specified character pointer and any characters in the internal buffer into a sequence of bytes that are stored starting at the specified byte pointer. Un parámetro indica si se debe borrar el estado interno del codificador después de la conversión.A parameter indicates whether to clear the internal state of the encoder after the conversion.

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

Cuando se reemplaza en una clase derivada, codifica un juego de caracteres de la matriz de caracteres especificada y cualquier carácter del búfer interno en la matriz de bytes especificada.When overridden in a derived class, encodes a set of characters from the specified character array and any characters in the internal buffer into the specified byte array. Un parámetro indica si se debe borrar el estado interno del codificador después de la conversión.A parameter indicates whether to clear the internal state of the encoder after the conversion.

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

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

bytes
Span<Byte>

Devoluciones

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

Importante

Esta API no es conforme a CLS.

Cuando se reemplaza en una clase derivada, codifica un juego de caracteres a partir del puntero de carácter especificado y cualquier carácter del búfer interno en una secuencia de bytes que se almacenan a partir del puntero de byte especificado.When overridden in a derived class, encodes a set of characters starting at the specified character pointer and any characters in the internal buffer into a sequence of bytes that are stored starting at the specified byte pointer. Un parámetro indica si se debe borrar el estado interno del codificador después de la conversión.A parameter indicates whether to clear the internal state of the encoder after the conversion.

public:
 virtual int GetBytes(char* chars, int charCount, System::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);
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*

Puntero al primer carácter que se va a codificar.A pointer to the first character to encode.

charCount
Int32 Int32 Int32 Int32

Número de caracteres que se van a codificar.The number of characters to encode.

bytes
Byte*

Puntero a la ubicación en la que se iniciará la escritura de la secuencia de bytes resultante.A pointer to the location at which to start writing the resulting sequence of bytes.

byteCount
Int32 Int32 Int32 Int32

Número máximo de bytes que se pueden escribir.The maximum number of bytes to write.

flush
Boolean Boolean Boolean Boolean

Es true para borrar el estado interno del codificador después de la conversión; de lo contrario, es false.true to clear the internal state of the encoder after the conversion; otherwise, false.

Devoluciones

Número real de bytes escritos en la ubicación indicada por el parámetro bytes.The actual number of bytes written at the location indicated by the bytes parameter.

Excepciones

chars es null (Nothing).chars is null (Nothing).

O bien-or- bytes es null (Nothing).bytes is null (Nothing).

charCount o byteCount es menor que cero.charCount or byteCount is less than zero.

El valor de byteCount es menor que el número resultante de bytes.byteCount is less than the resulting number of bytes.

Se ha producido una acción de reserva (vea Codificación de caracteres en .NET Framework para obtener una explicación completa)A fallback occurred (see Character Encoding in the .NET Framework for fuller explanation) - y --and- El valor de Fallback está establecido en EncoderExceptionFallback.Fallback is set to EncoderExceptionFallback.

Comentarios

Recuerde que el Encoder objeto guarda el estado entre las llamadas a GetBytes.Remember that the Encoder object saves state between calls to GetBytes. Cuando la aplicación se realiza con un flujo de datos, se debe establecer el flush parámetro true en la última llamada a GetBytes para asegurarse de que se vacíe la información de estado y que los bytes codificados se terminan correctamente.When the application is done with a stream of data, it should set the flush parameter to true in the last call to GetBytes to make sure that the state information is flushed and that the encoded bytes are properly terminated. Con esta configuración, el codificador omite los bytes no válidos al final del bloque de datos, como suplentes no coincidentes o combinación incompleta secuencias y borra el búfer interno.With this setting, the encoder ignores invalid bytes at the end of the data block, such as unmatched surrogates or incomplete combining sequences, and clears the internal buffer.

Para calcular el tamaño del búfer exacto que GetBytes requiere para almacenar los caracteres resultantes, debe usar la aplicación GetByteCount.To calculate the exact buffer size that GetBytes requires to store the resulting characters, the application should use GetByteCount.

Si GetBytes se llama con flush establecido en false, el codificador almacena los bytes finales al final del bloque de datos en un búfer interno y se utilizan en la siguiente operación de codificación.If GetBytes is called with flush set to false, the encoder stores trailing bytes at the end of the data block in an internal buffer and uses them in the next encoding operation. La aplicación debe llamar a GetByteCount en un bloque de datos inmediatamente antes de llamar a GetBytes en el mismo bloque, por lo que cualquier finales caracteres del bloque anterior se incluyen en el cálculo.The application should call GetByteCount on a block of data immediately before calling GetBytes on the same block, so that any trailing characters from the previous block are included in the calculation.

Si la aplicación consiste en convertir muchos segmentos de un flujo de entrada, considere el uso de la Convert método.If your application is to convert many segments of an input stream, consider using the Convert method. GetBytes se iniciará una excepción si el búfer de salida no es suficientemente grande, pero Convert se rellenará tanto espacio como sea posible y devolverá los caracteres leídos y bytes escritos.GetBytes will throw an exception if the output buffer isn't large enough, but Convert will fill as much space as possible and return the chars read and bytes written. Consulte también el Encoding.GetBytes tema para obtener más comentarios.Also see the Encoding.GetBytes topic for more comments.

Seguridad

SecurityCriticalAttribute
requiere plena confianza para el llamador inmediato.Requires full trust for the immediate caller. Este miembro no se puede usar código de confianza parcial o transparente.This member cannot be used by partially trusted or transparent code.

Consulte también:

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

Cuando se reemplaza en una clase derivada, codifica un juego de caracteres de la matriz de caracteres especificada y cualquier carácter del búfer interno en la matriz de bytes especificada.When overridden in a derived class, encodes a set of characters from the specified character array and any characters in the internal buffer into the specified byte array. Un parámetro indica si se debe borrar el estado interno del codificador después de la conversión.A parameter indicates whether to clear the internal state of the encoder after the conversion.

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

Matriz de caracteres que contiene el juego de caracteres que se va a codificar.The character array containing the set of characters to encode.

charIndex
Int32 Int32 Int32 Int32

Índice del primer carácter que se va a codificar.The index of the first character to encode.

charCount
Int32 Int32 Int32 Int32

Número de caracteres que se van a codificar.The number of characters to encode.

bytes
Byte[]

Matriz de bytes que contendrá la secuencia de bytes resultante.The byte array to contain the resulting sequence of bytes.

byteIndex
Int32 Int32 Int32 Int32

Índice en el que se inicia la escritura de la secuencia de bytes resultante.The index at which to start writing the resulting sequence of bytes.

flush
Boolean Boolean Boolean Boolean

Es true para borrar el estado interno del codificador después de la conversión; de lo contrario, es false.true to clear the internal state of the encoder after the conversion; otherwise, false.

Devoluciones

Número real de bytes escritos en bytes.The actual number of bytes written into bytes.

Excepciones

chars es null (Nothing).chars is null (Nothing).

O bien-or- bytes es null (Nothing).bytes is null (Nothing).

El valor de charIndex, charCount o byteIndex es menor que cero.charIndex or charCount or byteIndex is less than zero.

O bien-or- charIndex y charCount no denotan un intervalo válido en chars.charIndex and charCount do not denote a valid range in chars.

O bien-or- byteIndex no es un índice válido para bytes.byteIndex is not a valid index in bytes.

bytes no tiene suficiente capacidad desde byteIndex hasta el final de la matriz para alojar los bytes resultantes.bytes does not have enough capacity from byteIndex to the end of the array to accommodate the resulting bytes.

Se ha producido una acción de reserva (vea Codificación de caracteres en .NET Framework para obtener una explicación completa)A fallback occurred (see Character Encoding in the .NET Framework for fuller explanation) - y --and- El valor de Fallback está establecido en EncoderExceptionFallback.Fallback is set to EncoderExceptionFallback.

Ejemplos

El ejemplo siguiente muestra cómo codificar un intervalo de elementos de una matriz de caracteres y almacenar los bytes codificados en un intervalo de elementos de una matriz de bytes.The following example demonstrates how to encode a range of elements from a character array and store the encoded bytes in a range of elements in a byte array. El GetByteCount método se utiliza para determinar el tamaño de la matriz requerido GetBytes.The GetByteCount method is used to determine the size of the array required by GetBytes.

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'};
   Encoder^ uniEncoder = Encoding::Unicode->GetEncoder();
   int byteCount = uniEncoder->GetByteCount( chars, 0, chars->Length, true );
   bytes = gcnew array<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: " );
   IEnumerator^ myEnum = bytes->GetEnumerator();
   while ( myEnum->MoveNext() )
   {
      Byte b = safe_cast<Byte>(myEnum->Current);
      Console::Write( "[{0}]", b );
   }

   Console::WriteLine();
}

/* This code example produces the following output.

8 bytes used to encode characters.
Encoded bytes: [160][3][163][3][166][3][169][3]

*/

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
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 'Main
End Class 'EncoderExample

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

Comentarios

Recuerde que el Encoder objeto guarda el estado entre las llamadas a GetBytes.Remember that the Encoder object saves state between calls to GetBytes. Cuando la aplicación se realiza con un flujo de datos, se debe establecer el flush parámetro true en la última llamada a GetBytes para asegurarse de que se vacíe la información de estado y que los bytes codificados se terminan correctamente.When the application is done with a stream of data, it should set the flush parameter to true in the last call to GetBytes to make sure that the state information is flushed and that the encoded bytes are properly terminated. Con esta configuración, el codificador omite los bytes no válidos al final del bloque de datos, como suplentes no coincidentes o combinación incompleta secuencias y borra el búfer interno.With this setting, the encoder ignores invalid bytes at the end of the data block, such as unmatched surrogates or incomplete combining sequences, and clears the internal buffer.

Para calcular el tamaño del búfer exacto que GetBytes requiere para almacenar los caracteres resultantes, debe usar la aplicación GetByteCount.To calculate the exact buffer size that GetBytes requires to store the resulting characters, the application should use GetByteCount.

Si GetBytes se llama con flush establecido en false, el codificador almacena los bytes finales al final del bloque de datos en un búfer interno y se utilizan en la siguiente operación de codificación.If GetBytes is called with flush set to false, the encoder stores trailing bytes at the end of the data block in an internal buffer and uses them in the next encoding operation. La aplicación debe llamar a GetByteCount en un bloque de datos inmediatamente antes de llamar a GetBytes en el mismo bloque, por lo que cualquier finales caracteres del bloque anterior se incluyen en el cálculo.The application should call GetByteCount on a block of data immediately before calling GetBytes on the same block, so that any trailing characters from the previous block are included in the calculation.

Si la aplicación consiste en convertir muchos segmentos de un flujo de entrada, considere el uso de la Convert método.If your application is to convert many segments of an input stream, consider using the Convert method. GetBytes se iniciará una excepción si el búfer de salida no es suficientemente grande, pero Convert se rellenará tanto espacio como sea posible y devolverá los caracteres leídos y bytes escritos.GetBytes will throw an exception if the output buffer isn't large enough, but Convert will fill as much space as possible and return the chars read and bytes written. Consulte también el Encoding.GetBytes tema para obtener más comentarios.Also see the Encoding.GetBytes topic for more comments.

Consulte también:

Se aplica a