Encoding.GetChars Methode

Definition

Namespace:

System.Text

Assembly:

mscorlib.dll

Wenn eine abgeleitete Klasse außer Kraft gesetzt wird, decodieren Sie eine Bytesequenz in eine Reihe von Zeichen.

Überlädt

Name	Beschreibung
GetChars(Byte[], Int32, Int32, Char[], Int32)	Wenn eine abgeleitete Klasse überschrieben wird, decodiert eine Bytesequenz aus dem angegebenen Bytearray in das angegebene Zeichenarray.
GetChars(Byte*, Int32, Char*, Int32)	Wenn sie in einer abgeleiteten Klasse überschrieben werden, decodieren Sie eine Bytesequenz ab dem angegebenen Bytezeiger in eine Reihe von Zeichen, die ab dem angegebenen Zeichenzeiger gespeichert werden.
GetChars(Byte[])	Wenn sie in einer abgeleiteten Klasse außer Kraft gesetzt wird, decodieren Sie alle Bytes im angegebenen Bytearray in eine Reihe von Zeichen.
GetChars(Byte[], Int32, Int32)	Wenn eine abgeleitete Klasse überschrieben wird, decodiert eine Bytesequenz aus dem angegebenen Bytearray in eine Reihe von Zeichen.

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

Wenn eine abgeleitete Klasse überschrieben wird, decodiert eine Bytesequenz aus dem angegebenen Bytearray in das angegebene Zeichenarray.

public:
 abstract int GetChars(cli::array <System::Byte> ^ bytes, int byteIndex, int byteCount, cli::array <char> ^ chars, int charIndex);

public abstract int GetChars(byte[] bytes, int byteIndex, int byteCount, char[] chars, int charIndex);

abstract member GetChars : byte[] * int * int * char[] * int -> int

Public MustOverride Function GetChars (bytes As Byte(), byteIndex As Integer, byteCount As Integer, chars As Char(), charIndex As Integer) As Integer

Parameter

bytes

Byte[]

Das Bytearray, das die Abfolge von Bytes enthält, die decodiert werden sollen.

byteIndex

Int32

Der Index des ersten zu decodierenden Bytes.

byteCount

Int32

Die Anzahl der Bytes, die decodiert werden sollen.

chars

Char[]

Das Zeichenarray, das den resultierenden Satz von Zeichen enthält.

charIndex

Int32

Der Index, an dem mit dem Schreiben der resultierenden Zeichenmenge begonnen werden soll.

Gibt zurück

Int32

Die tatsächliche Anzahl der Zeichen, in charsdie geschrieben wurde.

Ausnahmen

ArgumentNullException

bytes ist null.

-oder-

chars ist null.

ArgumentOutOfRangeException

byteIndex oder byteCountcharIndex ist kleiner als Null.

-oder-

byteIndex und byteCount keinen gültigen Bereich in bytes.

-oder-

charIndex ist kein gültiger Index in chars.

ArgumentException

chars verfügt nicht über genügend Kapazität vom charIndex Ende des Arrays, um die resultierenden Zeichen aufzunehmen.

DecoderFallbackException

Ein Fallback ist aufgetreten (weitere Informationen finden Sie unter "Zeichencodierung in .NET")

-und-

DecoderFallback ist auf DecoderExceptionFallback festgelegt.

Beispiele

Im folgenden Beispiel wird eine Zeichenfolge von einer Codierung in eine andere konvertiert.

using System;
using System.Text;

class Example
{
   static void Main()
   {
      string unicodeString = "This string contains the unicode character Pi (\u03a0)";

      // Create two different encodings.
      Encoding ascii = Encoding.ASCII;
      Encoding unicode = Encoding.Unicode;

      // Convert the string into a byte array.
      byte[] unicodeBytes = unicode.GetBytes(unicodeString);

      // Perform the conversion from one encoding to the other.
      byte[] asciiBytes = Encoding.Convert(unicode, ascii, unicodeBytes);
         
      // Convert the new byte[] into a char[] and then into a string.
      char[] asciiChars = new char[ascii.GetCharCount(asciiBytes, 0, asciiBytes.Length)];
      ascii.GetChars(asciiBytes, 0, asciiBytes.Length, asciiChars, 0);
      string asciiString = new string(asciiChars);

      // Display the strings created before and after the conversion.
      Console.WriteLine("Original string: {0}", unicodeString);
      Console.WriteLine("Ascii converted string: {0}", asciiString);
   }
}
// The example displays the following output:
//    Original string: This string contains the unicode character Pi (Π)
//    Ascii converted string: This string contains the unicode character Pi (?)

Imports System.Text

Class Example
   Shared Sub Main()
      Dim unicodeString As String = "This string contains the unicode character Pi (" & ChrW(&H03A0) & ")"

      ' Create two different encodings.
      Dim ascii As Encoding = Encoding.ASCII
      Dim unicode As Encoding = Encoding.Unicode

      ' Convert the string into a byte array.
      Dim unicodeBytes As Byte() = unicode.GetBytes(unicodeString)

      ' Perform the conversion from one encoding to the other.
      Dim asciiBytes As Byte() = Encoding.Convert(unicode, ascii, unicodeBytes)

      ' Convert the new byte array into a char array and then into a string.
      Dim asciiChars(ascii.GetCharCount(asciiBytes, 0, asciiBytes.Length)-1) As Char
      ascii.GetChars(asciiBytes, 0, asciiBytes.Length, asciiChars, 0)
      Dim asciiString As New String(asciiChars)

      ' Display the strings created before and after the conversion.
      Console.WriteLine("Original string: {0}", unicodeString)
      Console.WriteLine("Ascii converted string: {0}", asciiString)
   End Sub
End Class
' The example displays the following output:
'    Original string: This string contains the unicode character Pi (Π)
'    Ascii converted string: This string contains the unicode character Pi (?)

Im folgenden Beispiel wird eine Zeichenfolge in ein Bytearray codiert und dann ein Bereich der Bytes in ein Array von Zeichen decodiert.

using System;
using System.Text;

public class SamplesEncoding  {

   public static void Main()  {

      // Create two instances of UTF32Encoding: one with little-endian byte order and one with big-endian byte order.
      Encoding u32LE = Encoding.GetEncoding( "utf-32" );
      Encoding u32BE = Encoding.GetEncoding( "utf-32BE" );

      // Use a string containing the following characters:
      //    Latin Small Letter Z (U+007A)
      //    Latin Small Letter A (U+0061)
      //    Combining Breve (U+0306)
      //    Latin Small Letter AE With Acute (U+01FD)
      //    Greek Small Letter Beta (U+03B2)
      String myStr = "za\u0306\u01FD\u03B2";

      // Encode the string using the big-endian byte order.
      byte[] barrBE = new byte[u32BE.GetByteCount( myStr )];
      u32BE.GetBytes( myStr, 0, myStr.Length, barrBE, 0 );

      // Encode the string using the little-endian byte order.
      byte[] barrLE = new byte[u32LE.GetByteCount( myStr )];
      u32LE.GetBytes( myStr, 0, myStr.Length, barrLE, 0 );

      // Get the char counts, decode eight bytes starting at index 0,
      // and print out the counts and the resulting bytes.
      Console.Write( "BE array with BE encoding : " );
      PrintCountsAndChars( barrBE, 0, 8, u32BE );
      Console.Write( "LE array with LE encoding : " );
      PrintCountsAndChars( barrLE, 0, 8, u32LE );
   }

   public static void PrintCountsAndChars( byte[] bytes, int index, int count, Encoding enc )  {

      // Display the name of the encoding used.
      Console.Write( "{0,-25} :", enc.ToString() );

      // Display the exact character count.
      int iCC  = enc.GetCharCount( bytes, index, count );
      Console.Write( " {0,-3}", iCC );

      // Display the maximum character count.
      int iMCC = enc.GetMaxCharCount( count );
      Console.Write( " {0,-3} :", iMCC );

      // Decode the bytes and display the characters.
      char[] chars = enc.GetChars( bytes, index, count );

      // The following is an alternative way to decode the bytes:
      // char[] chars = new char[iCC];
      // enc.GetChars( bytes, index, count, chars, 0 );

      Console.WriteLine( chars );
   }
}


/* 
This code produces the following output.  The question marks take the place of characters that cannot be displayed at the console.

BE array with BE encoding : System.Text.UTF32Encoding : 2   6   :za
LE array with LE encoding : System.Text.UTF32Encoding : 2   6   :za

*/

Imports System.Text

Public Class SamplesEncoding   

   Public Shared Sub Main()

      ' Create two instances of UTF32Encoding: one with little-endian byte order and one with big-endian byte order.
      Dim u32LE As Encoding = Encoding.GetEncoding("utf-32")
      Dim u32BE As Encoding = Encoding.GetEncoding("utf-32BE")

      ' Use a string containing the following characters:
      '    Latin Small Letter Z (U+007A)
      '    Latin Small Letter A (U+0061)
      '    Combining Breve (U+0306)
      '    Latin Small Letter AE With Acute (U+01FD)
      '    Greek Small Letter Beta (U+03B2)
      Dim myStr As String = "za" & ChrW(&H0306) & ChrW(&H01FD) & ChrW(&H03B2)

      ' Encode the string using the big-endian byte order.
      ' NOTE: In VB.NET, arrays contain one extra element by default.
      '       The following line creates barrBE with the exact number of elements required.
      Dim barrBE(u32BE.GetByteCount(myStr) - 1) As Byte
      u32BE.GetBytes(myStr, 0, myStr.Length, barrBE, 0)

      ' Encode the string using the little-endian byte order.
      ' NOTE: In VB.NET, arrays contain one extra element by default.
      '       The following line creates barrLE with the exact number of elements required.
      Dim barrLE(u32LE.GetByteCount(myStr) - 1) As Byte
      u32LE.GetBytes(myStr, 0, myStr.Length, barrLE, 0)

      ' Get the char counts, decode eight bytes starting at index 0,
      ' and print out the counts and the resulting bytes.
      Console.Write("BE array with BE encoding : ")
      PrintCountsAndChars(barrBE, 0, 8, u32BE)
      Console.Write("LE array with LE encoding : ")
      PrintCountsAndChars(barrLE, 0, 8, u32LE)

   End Sub


   Public Shared Sub PrintCountsAndChars(bytes() As Byte, index As Integer, count As Integer, enc As Encoding)

      ' Display the name of the encoding used.
      Console.Write("{0,-25} :", enc.ToString())

      ' Display the exact character count.
      Dim iCC As Integer = enc.GetCharCount(bytes, index, count)
      Console.Write(" {0,-3}", iCC)

      ' Display the maximum character count.
      Dim iMCC As Integer = enc.GetMaxCharCount(count)
      Console.Write(" {0,-3} :", iMCC)

      ' Decode the bytes.
      Dim chars As Char() = enc.GetChars(bytes, index, count)

      ' The following is an alternative way to decode the bytes:
      ' NOTE: In VB.NET, arrays contain one extra element by default.
      '       The following line creates the array with the exact number of elements required.
      ' Dim chars(iCC - 1) As Char
      ' enc.GetChars( bytes, index, count, chars, 0 )

      ' Display the characters.
      Console.WriteLine(chars)

   End Sub

End Class


'This code produces the following output.  The question marks take the place of characters that cannot be displayed at the console.
'
'BE array with BE encoding : System.Text.UTF32Encoding : 2   6   :za
'LE array with LE encoding : System.Text.UTF32Encoding : 2   6   :za

Hinweise

Um die genaue Arraygröße zu berechnen, die zum GetChars Speichern der resultierenden Zeichen erforderlich ist, sollten Sie die GetCharCount Methode verwenden. Verwenden Sie die GetMaxCharCount Methode, um die maximale Arraygröße zu berechnen. Die GetCharCount Methode ermöglicht in der Regel die Zuordnung von weniger Arbeitsspeicher, während die GetMaxCharCount Methode im Allgemeinen schneller ausgeführt wird.

GetChars(Byte[], Int32, Int32, Char[], Int32) ruft Zeichen aus einer Eingabebytesequenz ab. Encoding.GetChars unterscheidet sich davon Decoder.GetChars , dass Encoding diskrete Konvertierungen erwartet werden, während Decoder sie für mehrere Übergänge für einen einzelnen Eingabedatenstrom ausgelegt sind.

Wenn die zu konvertierenden Daten nur in sequenziellen Blöcken (z. B. aus einem Datenstrom gelesene Daten) verfügbar sind oder die Datenmenge so groß ist, dass sie in kleinere Blöcke unterteilt werden muss, sollten Sie die Decoder oder die Encoder von der GetDecoder Methode bzw. methode bereitgestellte Methode bzw. Methode GetEncoder einer abgeleiteten Klasse verwenden.

Note

Diese Methode dient zum Arbeiten mit Unicode-Zeichen, nicht auf beliebigen Binärdaten, z. B. Bytearrays. Wenn Sie beliebige Binärdaten in Text codieren müssen, sollten Sie ein Protokoll wie uuencode verwenden, das von Methoden wie z Convert.ToBase64CharArray. B. implementiert wird.

Die GetCharCount Methode bestimmt, wie viele Zeichen dazu führen, dass eine Folge von Bytes decodiert wird, und die GetChars Methode führt die eigentliche Decodierung aus. Die Encoding.GetChars Methode erwartet diskrete Konvertierungen, im Gegensatz zur Decoder.GetChars Methode, die mehrere Übergeben an einen einzelnen Eingabedatenstrom verarbeitet.

Mehrere Versionen von GetCharCount und GetChars werden unterstützt. Im Folgenden finden Sie einige Programmierüberlegungen für die Verwendung dieser Methoden:

• Ihre App muss möglicherweise mehrere Eingabebytes von einer Codeseite decodieren und die Bytes mithilfe mehrerer Aufrufe verarbeiten. In diesem Fall müssen Sie wahrscheinlich den Zustand zwischen Aufrufen beibehalten, da Bytesequenzen beim Verarbeiten in Batches unterbrochen werden können. (Ein Teil einer ISO-2022-Schichtsequenz kann z. B. einen GetChars Aufruf beenden und am Anfang des nächsten GetChars Aufrufs fortfahren. Encoding.GetChars Ruft den Fallback für diese unvollständigen Sequenzen auf, merkt sich aber Decoder diese Sequenzen für den nächsten Aufruf.)

• Wenn Ihre App Zeichenfolgenausgaben verarbeitet, wird die GetString Methode empfohlen. Da diese Methode die Länge der Zeichenfolge überprüfen und einen Puffer zuordnen muss, ist sie etwas langsamer, aber der resultierende String Typ muss bevorzugt werden.

• Die Byteversion ermöglicht GetChars(Byte*, Int32, Char*, Int32) einige schnelle Techniken, insbesondere bei mehreren Aufrufen großer Puffer. Bedenken Sie jedoch, dass diese Methodenversion manchmal unsicher ist, da Zeiger erforderlich sind.

• Wenn Ihre App eine große Datenmenge konvertieren muss, sollte sie den Ausgabepuffer wiederverwenden. In diesem Fall ist die Version, die GetChars(Byte[], Int32, Int32, Char[], Int32) Ausgabezeichenpuffer unterstützt, die beste Wahl.

• Erwägen Sie die Verwendung der Decoder.Convert Methode anstelle von GetCharCount. Die Konvertierungsmethode konvertiert so viele Daten wie möglich und löst eine Ausnahme aus, wenn der Ausgabepuffer zu klein ist. Bei der kontinuierlichen Decodierung eines Datenstroms ist diese Methode häufig die beste Wahl.

Weitere Informationen

• GetCharCount(Byte[])
• GetMaxCharCount(Int32)
• GetDecoder()
• GetString(Byte[])

GetChars(Byte*, Int32, Char*, Int32)

Wichtig

Diese API ist nicht CLS-kompatibel.

Wenn sie in einer abgeleiteten Klasse überschrieben werden, decodieren Sie eine Bytesequenz ab dem angegebenen Bytezeiger in eine Reihe von Zeichen, die ab dem angegebenen Zeichenzeiger gespeichert werden.

public:
 virtual int GetChars(System::Byte* bytes, int byteCount, char* chars, int charCount);

[System.CLSCompliant(false)]
[System.Security.SecurityCritical]
[System.Runtime.InteropServices.ComVisible(false)]
public virtual int GetChars(byte* bytes, int byteCount, char* chars, int charCount);

[<System.CLSCompliant(false)>]
[<System.Security.SecurityCritical>]
[<System.Runtime.InteropServices.ComVisible(false)>]
abstract member GetChars : nativeptr<byte> * int * nativeptr<char> * int -> int
override this.GetChars : nativeptr<byte> * int * nativeptr<char> * int -> int

Parameter

bytes

Byte*

Ein Zeiger auf das erste Byte, das decodiert werden soll.

byteCount

Int32

Die Anzahl der Bytes, die decodiert werden sollen.

chars

Char*

Ein Zeiger auf die Position, an der mit dem Schreiben der resultierenden Zeichenmenge begonnen werden soll.

charCount

Int32

Die maximale Anzahl von Zeichen, die geschrieben werden sollen.

Gibt zurück

Int32

Die tatsächliche Anzahl von Zeichen, die an der durch den chars Parameter angegebenen Position geschrieben wurden.

Attribute

CLSCompliantAttribute SecurityCriticalAttribute ComVisibleAttribute

Ausnahmen

ArgumentNullException

bytes ist null.

-oder-

chars ist null.

ArgumentOutOfRangeException

byteCount oder charCount ist kleiner als Null.

ArgumentException

charCount ist kleiner als die resultierende Anzahl von Zeichen.

DecoderFallbackException

Ein Fallback ist aufgetreten (weitere Informationen finden Sie unter "Zeichencodierung in .NET")

-und-

DecoderFallback ist auf DecoderExceptionFallback festgelegt.

Hinweise

Um die genaue Arraygröße zu berechnen, die GetChars zum Speichern der resultierenden Zeichen erforderlich ist, sollten Sie die GetCharCount Methode verwenden. Verwenden Sie die GetMaxCharCount Methode, um die maximale Arraygröße zu berechnen. Die GetCharCount Methode ermöglicht in der Regel die Zuordnung von weniger Arbeitsspeicher, während die GetMaxCharCount Methode im Allgemeinen schneller ausgeführt wird.

Encoding.GetChars ruft Zeichen aus einer Eingabebytesequenz ab. Encoding.GetChars unterscheidet sich davon Decoder.GetChars , dass Encoding diskrete Konvertierungen erwartet werden, während Decoder sie für mehrere Übergänge für einen einzelnen Eingabedatenstrom ausgelegt sind.

Wenn die zu konvertierenden Daten nur in sequenziellen Blöcken (z. B. aus einem Datenstrom gelesene Daten) verfügbar sind oder die Datenmenge so groß ist, dass sie in kleinere Blöcke unterteilt werden muss, sollten Sie das Decoder oder das objekt verwenden, das bzw. das Encoder von der GetDecoder oder der GetEncoder Methode bereitgestellte Objekt einer abgeleiteten Klasse ist.

Note

Diese Methode dient zum Arbeiten mit Unicode-Zeichen, nicht auf beliebigen Binärdaten, z. B. Bytearrays. Wenn Sie beliebige Binärdaten in Text codieren müssen, sollten Sie ein Protokoll wie uuencode verwenden, das von Methoden wie z Convert.ToBase64CharArray. B. implementiert wird.

Die GetCharCount Methode bestimmt, wie viele Zeichen dazu führen, dass eine Folge von Bytes decodiert wird, und die GetChars Methode führt die eigentliche Decodierung aus. Die Encoding.GetChars Methode erwartet diskrete Konvertierungen, im Gegensatz zur Decoder.GetChars Methode, die mehrere Übergeben an einen einzelnen Eingabedatenstrom verarbeitet.

Mehrere Versionen von GetCharCount und GetChars werden unterstützt. Im Folgenden finden Sie einige Programmierüberlegungen für die Verwendung dieser Methoden:

• Ihre App muss möglicherweise mehrere Eingabebytes von einer Codeseite decodieren und die Bytes mithilfe mehrerer Aufrufe verarbeiten. In diesem Fall müssen Sie wahrscheinlich den Zustand zwischen Aufrufen beibehalten, da Bytesequenzen beim Verarbeiten in Batches unterbrochen werden können. (Ein Teil einer ISO-2022-Schichtsequenz kann z. B. einen GetChars Aufruf beenden und am Anfang des nächsten GetChars Aufrufs fortfahren. Encoding.GetChars Ruft den Fallback für diese unvollständigen Sequenzen auf, merkt sich aber Decoder diese Sequenzen für den nächsten Aufruf.)

• Wenn Ihre App Zeichenfolgenausgaben verarbeitet, wird die GetString Methode empfohlen. Da diese Methode die Länge der Zeichenfolge überprüfen und einen Puffer zuordnen muss, ist sie etwas langsamer, aber der resultierende String Typ muss bevorzugt werden.

• Die Byteversion ermöglicht GetChars(Byte*, Int32, Char*, Int32) einige schnelle Techniken, insbesondere bei mehreren Aufrufen großer Puffer. Bedenken Sie jedoch, dass diese Methodenversion manchmal unsicher ist, da Zeiger erforderlich sind.

• Wenn Ihre App eine große Datenmenge konvertieren muss, sollte sie den Ausgabepuffer wiederverwenden. In diesem Fall ist die Version, die GetChars(Byte[], Int32, Int32, Char[], Int32) Ausgabezeichenpuffer unterstützt, die beste Wahl.

• Erwägen Sie die Verwendung der Decoder.Convert Methode anstelle von GetCharCount. Die Konvertierungsmethode konvertiert so viele Daten wie möglich und löst eine Ausnahme aus, wenn der Ausgabepuffer zu klein ist. Bei der kontinuierlichen Decodierung eines Datenstroms ist diese Methode häufig die beste Wahl.

Weitere Informationen

• GetCharCount(Byte[])
• GetMaxCharCount(Int32)
• GetDecoder()
• GetString(Byte[])

GetChars(Byte[])

Wenn sie in einer abgeleiteten Klasse außer Kraft gesetzt wird, decodieren Sie alle Bytes im angegebenen Bytearray in eine Reihe von Zeichen.

public:
 virtual cli::array <char> ^ GetChars(cli::array <System::Byte> ^ bytes);

public virtual char[] GetChars(byte[] bytes);

abstract member GetChars : byte[] -> char[]
override this.GetChars : byte[] -> char[]

Public Overridable Function GetChars (bytes As Byte()) As Char()

Parameter

bytes

Byte[]

Das Bytearray, das die Abfolge von Bytes enthält, die decodiert werden sollen.

Gibt zurück

Char[]

Ein Zeichenarray, das die Ergebnisse der Decodierung der angegebenen Bytesequenz enthält.

Ausnahmen

ArgumentNullException

bytes ist null.

DecoderFallbackException

Ein Fallback ist aufgetreten (weitere Informationen finden Sie unter "Zeichencodierung in .NET")

-und-

DecoderFallback ist auf DecoderExceptionFallback festgelegt.

Beispiele

Im folgenden Beispiel wird eine Zeichenfolge in ein Bytearray codiert und dann die Bytes in ein Array von Zeichen decodiert.

using System;
using System.Text;

public class SamplesEncoding  {

   public static void Main()  {

      // Create two instances of UTF32Encoding: one with little-endian byte order and one with big-endian byte order.
      Encoding u32LE = Encoding.GetEncoding( "utf-32" );
      Encoding u32BE = Encoding.GetEncoding( "utf-32BE" );

      // Use a string containing the following characters:
      //    Latin Small Letter Z (U+007A)
      //    Latin Small Letter A (U+0061)
      //    Combining Breve (U+0306)
      //    Latin Small Letter AE With Acute (U+01FD)
      //    Greek Small Letter Beta (U+03B2)
      String myStr = "za\u0306\u01FD\u03B2";

      // Encode the string using the big-endian byte order.
      byte[] barrBE = new byte[u32BE.GetByteCount( myStr )];
      u32BE.GetBytes( myStr, 0, myStr.Length, barrBE, 0 );

      // Encode the string using the little-endian byte order.
      byte[] barrLE = new byte[u32LE.GetByteCount( myStr )];
      u32LE.GetBytes( myStr, 0, myStr.Length, barrLE, 0 );

      // Get the char counts, and decode the byte arrays.
      Console.Write( "BE array with BE encoding : " );
      PrintCountsAndChars( barrBE, u32BE );
      Console.Write( "LE array with LE encoding : " );
      PrintCountsAndChars( barrLE, u32LE );
   }

   public static void PrintCountsAndChars( byte[] bytes, Encoding enc )  {

      // Display the name of the encoding used.
      Console.Write( "{0,-25} :", enc.ToString() );

      // Display the exact character count.
      int iCC  = enc.GetCharCount( bytes );
      Console.Write( " {0,-3}", iCC );

      // Display the maximum character count.
      int iMCC = enc.GetMaxCharCount( bytes.Length );
      Console.Write( " {0,-3} :", iMCC );

      // Decode the bytes and display the characters.
      char[] chars = enc.GetChars( bytes );
      Console.WriteLine( chars );
   }
}


/* 
This code produces the following output.  The question marks take the place of characters that cannot be displayed at the console.

BE array with BE encoding : System.Text.UTF32Encoding : 5   12  :zăǽβ
LE array with LE encoding : System.Text.UTF32Encoding : 5   12  :zăǽβ

*/

Imports System.Text

Public Class SamplesEncoding   

   Public Shared Sub Main()

      ' Create two instances of UTF32Encoding: one with little-endian byte order and one with big-endian byte order.
      Dim u32LE As Encoding = Encoding.GetEncoding("utf-32")
      Dim u32BE As Encoding = Encoding.GetEncoding("utf-32BE")

      ' Use a string containing the following characters:
      '    Latin Small Letter Z (U+007A)
      '    Latin Small Letter A (U+0061)
      '    Combining Breve (U+0306)
      '    Latin Small Letter AE With Acute (U+01FD)
      '    Greek Small Letter Beta (U+03B2)
      Dim myStr As String = "za" & ChrW(&H0306) & ChrW(&H01FD) & ChrW(&H03B2) 

      ' Encode the string using the big-endian byte order.
      ' NOTE: In VB.NET, arrays contain one extra element by default.
      '       The following line creates the array with the exact number of elements required.
      Dim barrBE(u32BE.GetByteCount(myStr) - 1) As Byte
      u32BE.GetBytes(myStr, 0, myStr.Length, barrBE, 0)

      ' Encode the string using the little-endian byte order.
      ' NOTE: In VB.NET, arrays contain one extra element by default.
      '       The following line creates the array with the exact number of elements required.
      Dim barrLE(u32LE.GetByteCount(myStr) - 1) As Byte
      u32LE.GetBytes(myStr, 0, myStr.Length, barrLE, 0)

      ' Get the char counts, and decode the byte arrays.
      Console.Write("BE array with BE encoding : ")
      PrintCountsAndChars(barrBE, u32BE)
      Console.Write("LE array with LE encoding : ")
      PrintCountsAndChars(barrLE, u32LE)

   End Sub


   Public Shared Sub PrintCountsAndChars(bytes() As Byte, enc As Encoding)

      ' Display the name of the encoding used.
      Console.Write("{0,-25} :", enc.ToString())

      ' Display the exact character count.
      Dim iCC As Integer = enc.GetCharCount(bytes)
      Console.Write(" {0,-3}", iCC)

      ' Display the maximum character count.
      Dim iMCC As Integer = enc.GetMaxCharCount(bytes.Length)
      Console.Write(" {0,-3} :", iMCC)

      ' Decode the bytes and display the characters.
      Dim chars As Char() = enc.GetChars(bytes)
      Console.WriteLine(chars)

   End Sub

End Class


'This code produces the following output.  The question marks take the place of characters that cannot be displayed at the console.
'
'BE array with BE encoding : System.Text.UTF32Encoding : 5   12  :zăǽβ
'LE array with LE encoding : System.Text.UTF32Encoding : 5   12  :zăǽβ

Hinweise

Encoding.GetChars ruft Zeichen aus einer Eingabebytesequenz ab. Encoding.GetChars unterscheidet sich davon Decoder.GetChars , dass Encoding diskrete Konvertierungen erwartet werden, während Decoder sie für mehrere Übergänge für einen einzelnen Eingabedatenstrom ausgelegt sind.

Wenn die zu konvertierenden Daten nur in sequenziellen Blöcken (z. B. aus einem Datenstrom gelesene Daten) verfügbar sind oder die Datenmenge so groß ist, dass sie in kleinere Blöcke unterteilt werden muss, sollten Sie die Decoder oder die Encoder von der GetDecoder Methode bzw. methode bereitgestellte Methode bzw. Methode GetEncoder einer abgeleiteten Klasse verwenden.

Note

Diese Methode dient zum Arbeiten mit Unicode-Zeichen, nicht auf beliebigen Binärdaten, z. B. Bytearrays. Wenn Sie beliebige Binärdaten in Text codieren müssen, sollten Sie ein Protokoll wie uuencode verwenden, das von Methoden wie z Convert.ToBase64CharArray. B. implementiert wird.

Die GetCharCount Methode bestimmt, wie viele Zeichen dazu führen, dass eine Folge von Bytes decodiert wird, und die GetChars Methode führt die eigentliche Decodierung aus. Die Encoding.GetChars Methode erwartet diskrete Konvertierungen, im Gegensatz zur Decoder.GetChars Methode, die mehrere Übergeben an einen einzelnen Eingabedatenstrom verarbeitet.

Mehrere Versionen von GetCharCount und GetChars werden unterstützt. Im Folgenden finden Sie einige Programmierüberlegungen für die Verwendung dieser Methoden:

• Ihre App muss möglicherweise mehrere Eingabebytes von einer Codeseite decodieren und die Bytes mithilfe mehrerer Aufrufe verarbeiten. In diesem Fall müssen Sie wahrscheinlich den Zustand zwischen Aufrufen beibehalten, da Bytesequenzen beim Verarbeiten in Batches unterbrochen werden können. (Ein Teil einer ISO-2022-Schichtsequenz kann z. B. einen GetChars Aufruf beenden und am Anfang des nächsten GetChars Aufrufs fortfahren. Encoding.GetChars Ruft den Fallback für diese unvollständigen Sequenzen auf, merkt sich aber Decoder diese Sequenzen für den nächsten Aufruf.)

• Wenn Ihre App Zeichenfolgenausgabeen verarbeitet, empfiehlt es sich, die GetString Methode zu verwenden. Da diese Methode die Länge der Zeichenfolge überprüfen und einen Puffer zuordnen muss, ist sie etwas langsamer, aber der resultierende String Typ muss bevorzugt werden.

• Die Byteversion ermöglicht GetChars(Byte*, Int32, Char*, Int32) einige schnelle Techniken, insbesondere bei mehreren Aufrufen großer Puffer. Bedenken Sie jedoch, dass diese Methodenversion manchmal unsicher ist, da Zeiger erforderlich sind.

• Wenn Ihre App eine große Datenmenge konvertieren muss, sollte sie den Ausgabepuffer wiederverwenden. In diesem Fall ist die Version, die GetChars(Byte[], Int32, Int32, Char[], Int32) Ausgabezeichenpuffer unterstützt, die beste Wahl.

• Erwägen Sie die Verwendung der Decoder.Convert Methode anstelle von GetCharCount. Die Konvertierungsmethode konvertiert so viele Daten wie möglich und löst eine Ausnahme aus, wenn der Ausgabepuffer zu klein ist. Bei der kontinuierlichen Decodierung eines Datenstroms ist diese Methode häufig die beste Wahl.

Weitere Informationen

• GetCharCount(Byte[])
• GetMaxCharCount(Int32)
• GetDecoder()
• GetString(Byte[])

GetChars(Byte[], Int32, Int32)

Wenn eine abgeleitete Klasse überschrieben wird, decodiert eine Bytesequenz aus dem angegebenen Bytearray in eine Reihe von Zeichen.

public:
 virtual cli::array <char> ^ GetChars(cli::array <System::Byte> ^ bytes, int index, int count);

public virtual char[] GetChars(byte[] bytes, int index, int count);

abstract member GetChars : byte[] * int * int -> char[]
override this.GetChars : byte[] * int * int -> char[]

Public Overridable Function GetChars (bytes As Byte(), index As Integer, count As Integer) As Char()

Parameter

bytes

Byte[]

Das Bytearray, das die Abfolge von Bytes enthält, die decodiert werden sollen.

index

Int32

Der Index des ersten zu decodierenden Bytes.

count

Int32

Die Anzahl der Bytes, die decodiert werden sollen.

Gibt zurück

Char[]

Ein Zeichenarray, das die Ergebnisse der Decodierung der angegebenen Bytesequenz enthält.

Ausnahmen

ArgumentNullException

bytes ist null.

ArgumentOutOfRangeException

index oder count ist kleiner als Null.

-oder-

index und count keinen gültigen Bereich in bytes.

DecoderFallbackException

Ein Fallback ist aufgetreten (weitere Informationen finden Sie unter "Zeichencodierung in .NET")

-und-

DecoderFallback ist auf DecoderExceptionFallback festgelegt.

Beispiele

Im folgenden Beispiel wird eine Zeichenfolge in ein Bytearray codiert und dann ein Bereich der Bytes in ein Array von Zeichen decodiert.

using System;
using System.Text;

public class SamplesEncoding  {

   public static void Main()  {

      // Create two instances of UTF32Encoding: one with little-endian byte order and one with big-endian byte order.
      Encoding u32LE = Encoding.GetEncoding( "utf-32" );
      Encoding u32BE = Encoding.GetEncoding( "utf-32BE" );

      // Use a string containing the following characters:
      //    Latin Small Letter Z (U+007A)
      //    Latin Small Letter A (U+0061)
      //    Combining Breve (U+0306)
      //    Latin Small Letter AE With Acute (U+01FD)
      //    Greek Small Letter Beta (U+03B2)
      String myStr = "za\u0306\u01FD\u03B2";

      // Encode the string using the big-endian byte order.
      byte[] barrBE = new byte[u32BE.GetByteCount( myStr )];
      u32BE.GetBytes( myStr, 0, myStr.Length, barrBE, 0 );

      // Encode the string using the little-endian byte order.
      byte[] barrLE = new byte[u32LE.GetByteCount( myStr )];
      u32LE.GetBytes( myStr, 0, myStr.Length, barrLE, 0 );

      // Get the char counts, decode eight bytes starting at index 0,
      // and print out the counts and the resulting bytes.
      Console.Write( "BE array with BE encoding : " );
      PrintCountsAndChars( barrBE, 0, 8, u32BE );
      Console.Write( "LE array with LE encoding : " );
      PrintCountsAndChars( barrLE, 0, 8, u32LE );
   }

   public static void PrintCountsAndChars( byte[] bytes, int index, int count, Encoding enc )  {

      // Display the name of the encoding used.
      Console.Write( "{0,-25} :", enc.ToString() );

      // Display the exact character count.
      int iCC  = enc.GetCharCount( bytes, index, count );
      Console.Write( " {0,-3}", iCC );

      // Display the maximum character count.
      int iMCC = enc.GetMaxCharCount( count );
      Console.Write( " {0,-3} :", iMCC );

      // Decode the bytes and display the characters.
      char[] chars = enc.GetChars( bytes, index, count );

      // The following is an alternative way to decode the bytes:
      // char[] chars = new char[iCC];
      // enc.GetChars( bytes, index, count, chars, 0 );

      Console.WriteLine( chars );
   }
}


/* 
This code produces the following output.  The question marks take the place of characters that cannot be displayed at the console.

BE array with BE encoding : System.Text.UTF32Encoding : 2   6   :za
LE array with LE encoding : System.Text.UTF32Encoding : 2   6   :za

*/

Imports System.Text

Public Class SamplesEncoding   

   Public Shared Sub Main()

      ' Create two instances of UTF32Encoding: one with little-endian byte order and one with big-endian byte order.
      Dim u32LE As Encoding = Encoding.GetEncoding("utf-32")
      Dim u32BE As Encoding = Encoding.GetEncoding("utf-32BE")

      ' Use a string containing the following characters:
      '    Latin Small Letter Z (U+007A)
      '    Latin Small Letter A (U+0061)
      '    Combining Breve (U+0306)
      '    Latin Small Letter AE With Acute (U+01FD)
      '    Greek Small Letter Beta (U+03B2)
      Dim myStr As String = "za" & ChrW(&H0306) & ChrW(&H01FD) & ChrW(&H03B2)

      ' Encode the string using the big-endian byte order.
      ' NOTE: In VB.NET, arrays contain one extra element by default.
      '       The following line creates barrBE with the exact number of elements required.
      Dim barrBE(u32BE.GetByteCount(myStr) - 1) As Byte
      u32BE.GetBytes(myStr, 0, myStr.Length, barrBE, 0)

      ' Encode the string using the little-endian byte order.
      ' NOTE: In VB.NET, arrays contain one extra element by default.
      '       The following line creates barrLE with the exact number of elements required.
      Dim barrLE(u32LE.GetByteCount(myStr) - 1) As Byte
      u32LE.GetBytes(myStr, 0, myStr.Length, barrLE, 0)

      ' Get the char counts, decode eight bytes starting at index 0,
      ' and print out the counts and the resulting bytes.
      Console.Write("BE array with BE encoding : ")
      PrintCountsAndChars(barrBE, 0, 8, u32BE)
      Console.Write("LE array with LE encoding : ")
      PrintCountsAndChars(barrLE, 0, 8, u32LE)

   End Sub


   Public Shared Sub PrintCountsAndChars(bytes() As Byte, index As Integer, count As Integer, enc As Encoding)

      ' Display the name of the encoding used.
      Console.Write("{0,-25} :", enc.ToString())

      ' Display the exact character count.
      Dim iCC As Integer = enc.GetCharCount(bytes, index, count)
      Console.Write(" {0,-3}", iCC)

      ' Display the maximum character count.
      Dim iMCC As Integer = enc.GetMaxCharCount(count)
      Console.Write(" {0,-3} :", iMCC)

      ' Decode the bytes.
      Dim chars As Char() = enc.GetChars(bytes, index, count)

      ' The following is an alternative way to decode the bytes:
      ' NOTE: In VB.NET, arrays contain one extra element by default.
      '       The following line creates the array with the exact number of elements required.
      ' Dim chars(iCC - 1) As Char
      ' enc.GetChars( bytes, index, count, chars, 0 )

      ' Display the characters.
      Console.WriteLine(chars)

   End Sub

End Class


'This code produces the following output.  The question marks take the place of characters that cannot be displayed at the console.
'
'BE array with BE encoding : System.Text.UTF32Encoding : 2   6   :za
'LE array with LE encoding : System.Text.UTF32Encoding : 2   6   :za

Hinweise

Encoding.GetChars ruft Zeichen aus einer Eingabebytesequenz ab. Encoding.GetChars unterscheidet sich davon Decoder.GetChars , dass Encoding diskrete Konvertierungen erwartet werden, während Decoder sie für mehrere Übergänge für einen einzelnen Eingabedatenstrom ausgelegt sind.

Wenn die zu konvertierenden Daten nur in sequenziellen Blöcken (z. B. aus einem Datenstrom gelesene Daten) verfügbar sind oder die Datenmenge so groß ist, dass sie in kleinere Blöcke unterteilt werden muss, sollten Sie die Decoder oder die Encoder von der GetDecoder Methode bzw. methode bereitgestellte Methode bzw. Methode GetEncoder einer abgeleiteten Klasse verwenden.

Note

Diese Methode dient zum Arbeiten mit Unicode-Zeichen, nicht auf beliebigen Binärdaten, z. B. Bytearrays. Wenn Sie beliebige Binärdaten in Text codieren müssen, sollten Sie ein Protokoll wie uuencode verwenden, das von Methoden wie z Convert.ToBase64CharArray. B. implementiert wird.

Die GetCharCount Methode bestimmt, wie viele Zeichen dazu führen, dass eine Folge von Bytes decodiert wird, und die GetChars Methode führt die eigentliche Decodierung aus. Die Encoding.GetChars Methode erwartet diskrete Konvertierungen, im Gegensatz zur Decoder.GetChars Methode, die mehrere Übergeben an einen einzelnen Eingabedatenstrom verarbeitet.

Mehrere Versionen von GetCharCount und GetChars werden unterstützt. Im Folgenden finden Sie einige Programmierüberlegungen für die Verwendung dieser Methoden:

• Ihre App muss möglicherweise mehrere Eingabebytes von einer Codeseite decodieren und die Bytes mithilfe mehrerer Aufrufe verarbeiten. In diesem Fall müssen Sie wahrscheinlich den Zustand zwischen Aufrufen beibehalten, da Bytesequenzen beim Verarbeiten in Batches unterbrochen werden können. (Ein Teil einer ISO-2022-Schichtsequenz kann z. B. einen GetChars Aufruf beenden und am Anfang des nächsten GetChars Aufrufs fortfahren. Encoding.GetChars Ruft den Fallback für diese unvollständigen Sequenzen auf, merkt sich aber Decoder diese Sequenzen für den nächsten Aufruf.)

• Wenn Ihre App Zeichenfolgenausgabeen verarbeitet, empfiehlt es sich, die GetString Methode zu verwenden. Da diese Methode die Länge der Zeichenfolge überprüfen und einen Puffer zuordnen muss, ist sie etwas langsamer, aber der resultierende String Typ muss bevorzugt werden.

• Die Byteversion ermöglicht GetChars(Byte*, Int32, Char*, Int32) einige schnelle Techniken, insbesondere bei mehreren Aufrufen großer Puffer. Bedenken Sie jedoch, dass diese Methodenversion manchmal unsicher ist, da Zeiger erforderlich sind.

• Wenn Ihre App eine große Datenmenge konvertieren muss, sollte sie den Ausgabepuffer wiederverwenden. In diesem Fall ist die Version, die GetChars(Byte[], Int32, Int32, Char[], Int32) Ausgabezeichenpuffer unterstützt, die beste Wahl.

• Erwägen Sie die Verwendung der Decoder.Convert Methode anstelle von GetCharCount. Die Konvertierungsmethode konvertiert so viele Daten wie möglich und löst eine Ausnahme aus, wenn der Ausgabepuffer zu klein ist. Bei der kontinuierlichen Decodierung eines Datenstroms ist diese Methode häufig die beste Wahl.

Weitere Informationen

• GetCharCount(Byte[])
• GetMaxCharCount(Int32)
• GetDecoder()
• GetString(Byte[])