Encoder.GetBytes Methode

Definition

Beim Überschreiben in einer abgeleiteten Klasse werden die Zeichen in eine Bytefolge codiert.When overridden in a derived class, encodes a set of characters into a sequence of bytes.

Überlädt

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

Beim Überschreiben in einer abgeleiteten Klasse werden Zeichen beginnend am angegebenen Zeichenzeiger und Zeichen im internen Puffer in eine Bytefolge codiert, die beginnend am angegebenen Bytezeiger gespeichert werden.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. Ein Parameter gibt an, ob der interne Zustand des Encoders nach der Konvertierung zu löschen ist.A parameter indicates whether to clear the internal state of the encoder after the conversion.

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

Beim Überschreiben in einer abgeleiteten Klasse werden Zeichen aus dem angegebenen Zeichenarray und Zeichen im internen Puffer in den angegebenen Bytearray codiert.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. Ein Parameter gibt an, ob der interne Zustand des Encoders nach der Konvertierung zu löschen ist.A parameter indicates whether to clear the internal state of the encoder after the conversion.

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

Parameter

bytes
Span<Byte>
flush
Boolean

Gibt zurück

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

Wichtig

Diese API ist nicht CLS-kompatibel.

Beim Überschreiben in einer abgeleiteten Klasse werden Zeichen beginnend am angegebenen Zeichenzeiger und Zeichen im internen Puffer in eine Bytefolge codiert, die beginnend am angegebenen Bytezeiger gespeichert werden.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. Ein Parameter gibt an, ob der interne Zustand des Encoders nach der Konvertierung zu löschen ist.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

Parameter

chars
Char*

Ein Zeiger auf das erste zu codierende Zeichen.A pointer to the first character to encode.

charCount
Int32

Die Anzahl der zu codierenden Zeichen.The number of characters to encode.

bytes
Byte*

Ein Zeiger auf die Position, an der mit dem Schreiben der sich ergebenden Bytefolge begonnen werden soll.A pointer to the location at which to start writing the resulting sequence of bytes.

byteCount
Int32

Die maximale Anzahl der zu schreibenden Bytes.The maximum number of bytes to write.

flush
Boolean

true löscht nach der Konvertierung den internen Zustand des Encoders, andernfalls false.true to clear the internal state of the encoder after the conversion; otherwise, false.

Gibt zurück

Die tatsächliche Anzahl an Bytes, die an der durch den bytes-Parameter angegebenen Position geschrieben wurden.The actual number of bytes written at the location indicated by the bytes parameter.

Attribute

Ausnahmen

chars ist null(Nothing).chars is null (Nothing).

- oder --or- bytes ist null (Nothing).bytes is null (Nothing).

charCount oder byteCount ist kleiner als 0.charCount or byteCount is less than zero.

byteCount ist niedriger als die sich ergebende Anzahl von Bytes.byteCount is less than the resulting number of bytes.

Es ist ein Fallback aufgetreten (eine ausführliche Erläuterung finden Sie unter Zeichencodierung in .NET Framework).A fallback occurred (see Character Encoding in the .NET Framework for fuller explanation) - und --and- Für Fallback ist EncoderExceptionFallback festgelegt.Fallback is set to EncoderExceptionFallback.

Hinweise

Beachten Sie, Encoder dass das-Objekt den Zustand GetByteszwischen Aufrufen von speichert.Remember that the Encoder object saves state between calls to GetBytes. Wenn die Anwendung mit einem Datenstream ausgeführt wird, sollte Sie den flush - true Parameter GetBytes im letzten-Befehl auf festlegen, um sicherzustellen, dass die Zustandsinformationen geleert werden und dass die codierten Bytes ordnungsgemäß beendet werden.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. Mit dieser Einstellung ignoriert der Encoder ungültige Bytes am Ende des Datenblocks, z. b. nicht übereinstimmende Ersatz Zeichen oder unvollständige Kombinations Sequenzen, und löscht den internen Puffer.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.

Zum Berechnen der exakten Puffergröße GetBytes , die zum Speichern der resultierenden Zeichen benötigt, sollte die Anwendung verwenden. GetByteCountTo calculate the exact buffer size that GetBytes requires to store the resulting characters, the application should use GetByteCount.

Wenn GetBytes aufgerufen wird, flush wobei auf falsefestgelegt ist, speichert der Encoder nachfolgende Bytes am Ende des Datenblocks in einem internen Puffer und verwendet diese im nächsten Codierungs Vorgang.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. Die Anwendung sollte direkt GetByteCount vor dem Aufruf GetBytes von für einen Block von Daten aufrufen, sodass alle nachfolgenden Zeichen aus dem vorherigen Block in die Berechnung eingeschlossen werden.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.

Wenn die Anwendung viele Segmente eines Eingabedaten Stroms konvertieren soll, sollten Sie die Verwendung Convert der-Methode in Erwägung gezogen.If your application is to convert many segments of an input stream, consider using the Convert method. GetByteslöst eine Ausnahme aus, wenn der Ausgabepuffer nicht groß genug ist Convert , und gibt so viel Speicherplatz wie möglich aus und gibt den gelesenen Schreibvorgang und die geschriebenen Bytes zurück.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. Weitere Kommentare finden Encoding.GetBytes Sie auch im Thema.Also see the Encoding.GetBytes topic for more comments.

Sicherheit

SecurityCriticalAttribute
Erfordert volle Vertrauenswürdigkeit für den unmittelbaren Aufrufer.Requires full trust for the immediate caller. Dieser Member kann nicht von teilweise vertrauenswürdigem oder transparentem Code verwendet werden.This member cannot be used by partially trusted or transparent code.

Siehe auch

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

Beim Überschreiben in einer abgeleiteten Klasse werden Zeichen aus dem angegebenen Zeichenarray und Zeichen im internen Puffer in den angegebenen Bytearray codiert.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. Ein Parameter gibt an, ob der interne Zustand des Encoders nach der Konvertierung zu löschen ist.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

Parameter

chars
Char[]

Das Zeichenarray, das die zu codierenden Zeichen enthält.The character array containing the set of characters to encode.

charIndex
Int32

Der Index des ersten zu codierenden Zeichens.The index of the first character to encode.

charCount
Int32

Die Anzahl der zu codierenden Zeichen.The number of characters to encode.

bytes
Byte[]

Das Bytearray, das die sich ergebende Bytefolge enthalten soll.The byte array to contain the resulting sequence of bytes.

byteIndex
Int32

Der Index, an dem mit dem Schreiben der sich ergebenden Bytefolge begonnen werden soll.The index at which to start writing the resulting sequence of bytes.

flush
Boolean

true löscht nach der Konvertierung den internen Zustand des Encoders, andernfalls false.true to clear the internal state of the encoder after the conversion; otherwise, false.

Gibt zurück

Die tatsächliche Anzahl der Bytes, die in bytes geschrieben werden.The actual number of bytes written into bytes.

Ausnahmen

chars ist null(Nothing).chars is null (Nothing).

- oder --or- bytes ist null(Nothing).bytes is null (Nothing).

charIndex, charCount oder byteIndex ist kleiner als 0 (null).charIndex or charCount or byteIndex is less than zero.

- oder --or- charIndex und charCount geben keinen gültigen Bereich in charsan.charIndex and charCount do not denote a valid range in chars.

- oder --or- byteIndex ist kein gültiger Index in bytes.byteIndex is not a valid index in bytes.

bytes hat von byteIndex bis zum Ende des Arrays nicht genügend Kapazität, um die sich ergebenden Bytes aufzunehmen.bytes does not have enough capacity from byteIndex to the end of the array to accommodate the resulting bytes.

Es ist ein Fallback aufgetreten (eine ausführliche Erläuterung finden Sie unter Zeichencodierung in .NET Framework).A fallback occurred (see Character Encoding in the .NET Framework for fuller explanation) - und --and- Für Fallback ist EncoderExceptionFallback festgelegt.Fallback is set to EncoderExceptionFallback.

Beispiele

Im folgenden Beispiel wird veranschaulicht, wie ein Bereich von Elementen aus einem Zeichen Array codiert und die codierten Bytes in einem Bereich von Elementen in einem Bytearray gespeichert werden.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. Die GetByteCount -Methode wird verwendet, um die Größe des Arrays zu ermitteln GetBytes, das von benötigt wird.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.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]
'

Hinweise

Beachten Sie, Encoder dass das-Objekt den Zustand GetByteszwischen Aufrufen von speichert.Remember that the Encoder object saves state between calls to GetBytes. Wenn die Anwendung mit einem Datenstream ausgeführt wird, sollte Sie den flush - true Parameter GetBytes im letzten-Befehl auf festlegen, um sicherzustellen, dass die Zustandsinformationen geleert werden und dass die codierten Bytes ordnungsgemäß beendet werden.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. Mit dieser Einstellung ignoriert der Encoder ungültige Bytes am Ende des Datenblocks, z. b. nicht übereinstimmende Ersatz Zeichen oder unvollständige Kombinations Sequenzen, und löscht den internen Puffer.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.

Zum Berechnen der exakten Puffergröße GetBytes , die zum Speichern der resultierenden Zeichen benötigt, sollte die Anwendung verwenden. GetByteCountTo calculate the exact buffer size that GetBytes requires to store the resulting characters, the application should use GetByteCount.

Wenn GetBytes aufgerufen wird, flush wobei auf falsefestgelegt ist, speichert der Encoder nachfolgende Bytes am Ende des Datenblocks in einem internen Puffer und verwendet diese im nächsten Codierungs Vorgang.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. Die Anwendung sollte direkt GetByteCount vor dem Aufruf GetBytes von für einen Block von Daten aufrufen, sodass alle nachfolgenden Zeichen aus dem vorherigen Block in die Berechnung eingeschlossen werden.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.

Wenn die Anwendung viele Segmente eines Eingabedaten Stroms konvertieren soll, sollten Sie die Verwendung Convert der-Methode in Erwägung gezogen.If your application is to convert many segments of an input stream, consider using the Convert method. GetByteslöst eine Ausnahme aus, wenn der Ausgabepuffer nicht groß genug ist Convert , und gibt so viel Speicherplatz wie möglich aus und gibt den gelesenen Schreibvorgang und die geschriebenen Bytes zurück.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. Weitere Kommentare finden Encoding.GetBytes Sie auch im Thema.Also see the Encoding.GetBytes topic for more comments.

Siehe auch

Gilt für: