Encoding.GetChars 方法

定義

命名空間:

System.Text

組件:

System.Runtime.dll

在衍生類別中覆寫時，將位元組序列解碼成一組字元。

多載

GetChars(Byte[], Int32, Int32, Char[], Int32)	在衍生類別中覆寫時，將指定位元組陣列中的位元組序列解碼成指定的字元陣列。
GetChars(Byte*, Int32, Char*, Int32)	在衍生類別中覆寫時，從指定位元組指標開始將位元組序列解碼成一組字元 (會從指定的字元指標開始存放這些字元)。
GetChars(Byte[], Int32, Int32)	在衍生類別中覆寫時，將指定位元組陣列中的位元組序列解碼成一組字元。
GetChars(ReadOnlySpan<Byte>, Span<Char>)	在衍生類別中覆寫時，將指定唯讀位元組範圍中的所有位元組解碼成字元範圍。
GetChars(Byte[])	在衍生類別中覆寫時，將指定位元組陣列中的所有位元組解碼成一組字元。

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

來源:

Encoding.cs

在衍生類別中覆寫時，將指定位元組陣列中的位元組序列解碼成指定的字元陣列。

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

參數

bytes

Byte[]

包含要解碼之位元組序列的位元組陣列。

byteIndex

Int32

要解碼的第一個位元組索引。

byteCount

Int32

要解碼的位元組數。

chars

Char[]

包含產生的一組字元之字元陣列。

charIndex

Int32

要開始寫入產生的一組字元之索引。

傳回

Int32

寫入 chars 的實際字元數。

例外狀況

ArgumentNullException

bytes 為 null。

-或-

chars 為 null。

ArgumentOutOfRangeException

byteIndex、byteCount 或 charIndex 小於零。

-或-

byteindex 與 byteCount 不代表 bytes 中有效的範圍。

-或-

charIndex 在 chars 中不是有效的索引。

ArgumentException

從 chars 到陣列結尾處，charIndex 沒有足夠的容量容納結果字元。

DecoderFallbackException

發生後援 (如需詳細資訊，請參閱 .NET 中的字元編碼)

-和-

DecoderFallback 設定為 DecoderExceptionFallback。

範例

下列範例會將字串從一個編碼轉換成另一個編碼。

using namespace System;
using namespace System::Text;

int 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.
   array<Byte>^unicodeBytes = unicode->GetBytes( unicodeString );
   
   // Perform the conversion from one encoding to the other.
   array<Byte>^asciiBytes = Encoding::Convert( unicode, ascii, unicodeBytes );
   
   // Convert the new Byte into[] a char and[] then into a string.
   array<Char>^asciiChars = gcnew array<Char>(ascii->GetCharCount( asciiBytes, 0, asciiBytes->Length ));
   ascii->GetChars( asciiBytes, 0, asciiBytes->Length, asciiChars, 0 );
   String^ asciiString = gcnew 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 (?)

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 (?)

下列範例會將字元串編碼為位元組陣列，然後將位元組範圍譯碼為字元陣列。

using namespace System;
using namespace System::Text;
void PrintCountsAndChars( array<Byte>^bytes, int index, int count, Encoding^ enc );
int 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.
   array<Byte>^barrBE = gcnew array<Byte>(u32BE->GetByteCount( myStr ));
   u32BE->GetBytes( myStr, 0, myStr->Length, barrBE, 0 );
   
   // Encode the string using the little-endian byte order.
   array<Byte>^barrLE = gcnew array<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 );
}

void PrintCountsAndChars( array<Byte>^bytes, int index, int count, Encoding^ enc )
{
   
   // Display the name of the encoding used.
   Console::Write( "{0,-25} :", enc );
   
   // 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.
   array<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

*/

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

備註

若要計算儲存結果字元所需的 GetChars 確切數位大小，您應該使用 GetCharCount 方法。 若要計算數位大小上限，請使用 GetMaxCharCount 方法。 方法 GetCharCount 通常允許配置較少的記憶體，而 GetMaxCharCount 方法通常執行速度較快。

GetChars(Byte[], Int32, Int32, Char[], Int32) 從輸入位元組序列取得字元。 Encoding.GetChars 不同於 Decoder.GetChars ，因為 Encoding 預期會進行離散轉換，而 Decoder 是針對單一輸入數據流上的多個傳遞所設計。

如果要轉換的數據只能在循序區塊中使用， (例如從數據流讀取的數據) ，或如果數據量太大而需要分割成較小的區塊，則您應該分別使用 DecoderEncoder 方法或 方法所提供的 GetDecoder 或 GetEncoder 方法。

注意

這個方法的目的是在 Unicode 字元上運作，而不是在任意二進位數據上運作，例如位元組陣列。 如果您需要將任意二進位數據編碼為文字，您應該使用 uuencode 之類的通訊協定，其是由 之類的 Convert.ToBase64CharArray方法實作。

方法 GetCharCount 會決定譯碼位元組序列所產生的字元數，而 GetChars 方法會執行實際的譯碼。 方法 Encoding.GetChars 預期會進行離散轉換，與方法相反 Decoder.GetChars ，此方法會處理單一輸入數據流上的多個傳遞。

支持數個和 GetCharCountGetChars 版本。 以下是使用這些方法的一些程式設計考慮：

• 您的應用程式可能需要從代碼頁譯碼多個輸入位元組，並使用多個呼叫處理位元組。 在此情況下，您可能需要維護呼叫之間的狀態，因為位元組序列可以在批次中處理時中斷。 (例如，ISO-2022 班次序列的一部分可能會結束一個GetChars呼叫，並在下一個呼叫的開頭繼續。將會針對這些不完整的序列呼叫後援，但Decoder會記住下一GetChars個呼叫Encoding.GetChars的序列。)

• 如果您的應用程式處理字串輸出， GetString 建議使用 方法。 由於這個方法必須檢查字串長度並配置緩衝區，所以會稍微慢一點，但建議使用產生的 String 類型。

• 的位元組版本 GetChars(Byte*, Int32, Char*, Int32) 允許一些快速技術，特別是對大型緩衝區的多個呼叫。 不過，請記住，此方法版本有時不安全，因為需要指標。

• 如果您的應用程式必須轉換大量數據，它應該重複使用輸出緩衝區。 在此情況下， GetChars(Byte[], Int32, Int32, Char[], Int32) 支持輸出字元緩衝區的版本是最佳選擇。

• 請考慮使用 Decoder.Convert 方法，而不是 GetCharCount。 轉換方法會儘可能轉換數據，並在輸出緩衝區太小時擲回例外狀況。 針對數據流的連續譯碼，此方法通常是最佳選擇。

另請參閱

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

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

來源:

Encoding.cs

重要

此 API 不符合 CLS 規範。

在衍生類別中覆寫時，從指定位元組指標開始將位元組序列解碼成一組字元 (會從指定的字元指標開始存放這些字元)。

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

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

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

參數

bytes

Byte*

要解碼的第一個位元組指標。

byteCount

Int32

要解碼的位元組數。

chars

Char*

開始寫入產生的一組字元之位置指標。

charCount

Int32

要寫入的最大字元數。

傳回

Int32

chars 參數所指示位置上寫入的實際字元數目。

屬性

CLSCompliantAttribute

例外狀況

ArgumentNullException

bytes 為 null。

-或-

chars 為 null。

ArgumentOutOfRangeException

byteCount 或 charCount 小於零。

ArgumentException

charCount 小於結果字元數。

DecoderFallbackException

發生後援 (如需詳細資訊，請參閱 .NET 中的字元編碼)

-和-

DecoderFallback 設定為 DecoderExceptionFallback。

備註

若要計算儲存結果字元所需的確切數位大小 GetChars ，您應該使用 GetCharCount 方法。 若要計算數位大小上限，請使用 GetMaxCharCount 方法。 方法 GetCharCount 通常允許配置較少的記憶體，而 GetMaxCharCount 方法通常執行速度較快。

Encoding.GetChars 從輸入位元組序列取得字元。 Encoding.GetChars 不同於 Decoder.GetChars ，因為 Encoding 預期會進行離散轉換，而 Decoder 是針對單一輸入數據流上的多個傳遞所設計。

如果要轉換的數據僅在順序塊中可用（例如從流中讀取的數據），或者如果數據量太大以至於需要將其分成較小的塊，則應使用提供的Decoder或Encoder對象 分別由GetDecoder或GetEncoder種方法派生的類。

注意

這個方法的目的是在 Unicode 字元上運作，而不是在任意二進位數據上運作，例如位元組陣列。 如果您需要將任意二進位數據編碼為文字，您應該使用 uuencode 之類的通訊協定，其是由 之類的 Convert.ToBase64CharArray方法實作。

方法 GetCharCount 會決定譯碼位元組序列所產生的字元數，而 GetChars 方法會執行實際的譯碼。 方法 Encoding.GetChars 預期會進行離散轉換，與方法相反 Decoder.GetChars ，此方法會處理單一輸入數據流上的多個傳遞。

支持數個和 GetCharCountGetChars 版本。 以下是使用這些方法的一些程式設計考慮：

• 您的應用程式可能需要從代碼頁譯碼多個輸入位元組，並使用多個呼叫處理位元組。 在此情況下，您可能需要維護呼叫之間的狀態，因為位元組序列可以在批次中處理時中斷。 (例如，ISO-2022 班次序列的一部分可能會結束一個GetChars呼叫，並在下一個呼叫的開頭繼續。將會針對這些不完整的序列呼叫後援，但Decoder會記住下一GetChars個呼叫Encoding.GetChars的序列。)

• 如果您的應用程式處理字串輸出， GetString 建議使用 方法。 由於這個方法必須檢查字串長度並配置緩衝區，所以會稍微慢一點，但建議使用產生的 String 類型。

• 的位元組版本 GetChars(Byte*, Int32, Char*, Int32) 允許一些快速技術，特別是對大型緩衝區的多個呼叫。 不過，請記住，此方法版本有時不安全，因為需要指標。

• 如果您的應用程式必須轉換大量數據，它應該重複使用輸出緩衝區。 在此情況下， GetChars(Byte[], Int32, Int32, Char[], Int32) 支持輸出字元緩衝區的版本是最佳選擇。

• 請考慮使用 Decoder.Convert 方法，而不是 GetCharCount。 轉換方法會儘可能轉換數據，並在輸出緩衝區太小時擲回例外狀況。 針對數據流的連續譯碼，此方法通常是最佳選擇。

另請參閱

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

GetChars(Byte[], Int32, Int32)

來源:

Encoding.cs

在衍生類別中覆寫時，將指定位元組陣列中的位元組序列解碼成一組字元。

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()

參數

bytes

Byte[]

包含要解碼之位元組序列的位元組陣列。

index

Int32

要解碼的第一個位元組索引。

count

Int32

要解碼的位元組數。

傳回

Char[]

字元陣列，包含解碼指定位元組序列的結果。

例外狀況

ArgumentNullException

bytes 為 null。

ArgumentOutOfRangeException

index 或 count 小於零。

-或-

index 與 count 不代表 bytes 中有效的範圍。

DecoderFallbackException

發生後援 (如需詳細資訊，請參閱 .NET 中的字元編碼)

-和-

DecoderFallback 設定為 DecoderExceptionFallback。

範例

下列範例會將字元串編碼為位元組陣列，然後將位元組範圍譯碼為字元陣列。

using namespace System;
using namespace System::Text;
void PrintCountsAndChars( array<Byte>^bytes, int index, int count, Encoding^ enc );
int 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.
   array<Byte>^barrBE = gcnew array<Byte>(u32BE->GetByteCount( myStr ));
   u32BE->GetBytes( myStr, 0, myStr->Length, barrBE, 0 );
   
   // Encode the string using the little-endian byte order.
   array<Byte>^barrLE = gcnew array<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 );
}

void PrintCountsAndChars( array<Byte>^bytes, int index, int count, Encoding^ enc )
{
   
   // Display the name of the encoding used.
   Console::Write( "{0,-25} :", enc );
   
   // 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.
   array<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

*/

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

備註

Encoding.GetChars 從輸入位元組序列取得字元。 Encoding.GetChars 不同於 Decoder.GetChars ，因為 Encoding 預期會進行離散轉換，而 Decoder 是針對單一輸入數據流上的多個傳遞所設計。

如果要轉換的數據只能在循序區塊中使用， (例如從數據流讀取的數據) ，或如果數據量太大而需要分割成較小的區塊，則您應該分別使用 DecoderEncoder 方法或 方法所提供的 GetDecoder 或 GetEncoder 方法。

注意

這個方法的目的是在 Unicode 字元上運作，而不是在任意二進位數據上運作，例如位元組陣列。 如果您需要將任意二進位數據編碼為文字，您應該使用 uuencode 之類的通訊協定，其是由 之類的 Convert.ToBase64CharArray方法實作。

方法 GetCharCount 會決定譯碼位元組序列所產生的字元數，而 GetChars 方法會執行實際的譯碼。 方法 Encoding.GetChars 預期會進行離散轉換，與方法相反 Decoder.GetChars ，此方法會處理單一輸入數據流上的多個傳遞。

支持數個和 GetCharCountGetChars 版本。 以下是使用這些方法的一些程式設計考慮：

• 您的應用程式可能需要從代碼頁譯碼多個輸入位元組，並使用多個呼叫處理位元組。 在此情況下，您可能需要維護呼叫之間的狀態，因為位元組序列可以在批次中處理時中斷。 (例如，ISO-2022 班次序列的一部分可能會結束一個GetChars呼叫，並在下一個呼叫的開頭繼續。將會針對這些不完整的序列呼叫後援，但Decoder會記住下一GetChars個呼叫Encoding.GetChars的序列。)

• 如果您的應用程式處理字串輸出，建議您使用 GetString 方法。 由於這個方法必須檢查字串長度並配置緩衝區，所以會稍微慢一點，但建議使用產生的 String 類型。

• 的位元組版本 GetChars(Byte*, Int32, Char*, Int32) 允許一些快速技術，特別是對大型緩衝區的多個呼叫。 不過，請記住，此方法版本有時不安全，因為需要指標。

• 如果您的應用程式必須轉換大量數據，它應該重複使用輸出緩衝區。 在此情況下， GetChars(Byte[], Int32, Int32, Char[], Int32) 支持輸出字元緩衝區的版本是最佳選擇。

• 請考慮使用 Decoder.Convert 方法，而不是 GetCharCount。 轉換方法會儘可能轉換數據，並在輸出緩衝區太小時擲回例外狀況。 針對數據流的連續譯碼，此方法通常是最佳選擇。

另請參閱

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

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

來源:

Encoding.cs

在衍生類別中覆寫時，將指定唯讀位元組範圍中的所有位元組解碼成字元範圍。

public:
 virtual int GetChars(ReadOnlySpan<System::Byte> bytes, Span<char> chars);

public virtual int GetChars (ReadOnlySpan<byte> bytes, Span<char> chars);

abstract member GetChars : ReadOnlySpan<byte> * Span<char> -> int
override this.GetChars : ReadOnlySpan<byte> * Span<char> -> int

Public Overridable Function GetChars (bytes As ReadOnlySpan(Of Byte), chars As Span(Of Char)) As Integer

參數

bytes

ReadOnlySpan<Byte>

唯讀範圍，其包含要解碼的位元組序列。

chars

Span<Char>

接收已解碼位元組的字元範圍。

傳回

Int32

寫入 chars 參數所指出範圍的實際字元數。

備註

Encoding.GetChars 從輸入位元組範圍取得字元。 Encoding.GetChars 不同於 Decoder.GetChars ，因為 Encoding 預期會進行離散轉換，而 Decoder 是針對單一輸入數據流上的多個傳遞所設計。

如果要轉換的數據只能在循序區塊中使用， (例如從數據流讀取的數據) ，或如果數據量太大而需要分割成較小的區塊，則您應該分別使用 DecoderEncoder 方法或 方法所提供的 GetDecoder 或 GetEncoder 方法。

方法 GetCharCount 會決定譯碼位元組序列所產生的字元數，而 GetChars 方法會執行實際的譯碼。 方法 Encoding.GetChars 預期會進行離散轉換，與方法相反 Decoder.GetChars ，此方法會處理單一輸入數據流上的多個傳遞。

支持數個和 GetCharCountGetChars 版本。 以下是使用這些方法的一些程式設計考慮：

• 您的應用程式可能需要從代碼頁譯碼多個輸入位元組，並使用多個呼叫處理位元組。 在此情況下，您可能需要維護呼叫之間的狀態，因為位元組序列可以在批次中處理時中斷。 (例如，ISO-2022 班次序列的一部分可能會結束一個GetChars呼叫，並在下一個呼叫的開頭繼續。將會針對這些不完整的序列呼叫後援，但Decoder會記住下一GetChars個呼叫Encoding.GetChars的序列。)

• 如果您的應用程式處理字串輸出，建議您使用 GetString 方法。 由於這個方法必須檢查字串長度並配置緩衝區，所以會稍微慢一點，但建議使用產生的 String 類型。

• 的位元組版本 GetChars(Byte*, Int32, Char*, Int32) 允許一些快速技術，特別是對大型緩衝區的多個呼叫。 不過，請記住，此方法版本有時不安全，因為需要指標。

• 如果您的應用程式必須轉換大量數據，它應該重複使用輸出緩衝區。 在此情況下， GetChars(Byte[], Int32, Int32, Char[], Int32) 支持輸出字元緩衝區的版本是最佳選擇。

• 請考慮使用 Decoder.Convert 方法，而不是 GetCharCount。 轉換方法會儘可能轉換數據，並在輸出緩衝區太小時擲回例外狀況。 針對數據流的連續譯碼，此方法通常是最佳選擇。

GetChars(Byte[])

來源:

Encoding.cs

在衍生類別中覆寫時，將指定位元組陣列中的所有位元組解碼成一組字元。

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()

參數

bytes

Byte[]

包含要解碼之位元組序列的位元組陣列。

傳回

Char[]

字元陣列，包含解碼指定位元組序列的結果。

例外狀況

ArgumentNullException

bytes 為 null。

DecoderFallbackException

發生後援 (如需詳細資訊，請參閱 .NET 中的字元編碼)

-和-

DecoderFallback 設定為 DecoderExceptionFallback。

範例

下列範例會將字元串編碼為位元組陣列，然後將位元組譯碼為字元陣列。

using namespace System;
using namespace System::Text;
void PrintCountsAndChars( array<Byte>^bytes, Encoding^ enc );
int 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.
   array<Byte>^barrBE = gcnew array<Byte>(u32BE->GetByteCount( myStr ));
   u32BE->GetBytes( myStr, 0, myStr->Length, barrBE, 0 );
   
   // Encode the string using the little-endian byte order.
   array<Byte>^barrLE = gcnew array<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 );
}

void PrintCountsAndChars( array<Byte>^bytes, Encoding^ enc )
{
   
   // Display the name of the encoding used.
   Console::Write( "{0,-25} :", enc );
   
   // 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.
   array<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ăǽβ

*/

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ăǽβ

備註

Encoding.GetChars 從輸入位元組序列取得字元。 Encoding.GetChars 不同於 Decoder.GetChars ，因為 Encoding 預期會進行離散轉換，而 Decoder 是針對單一輸入數據流上的多個傳遞所設計。

如果要轉換的數據只能在循序區塊中使用， (例如從數據流讀取的數據) ，或如果數據量太大而需要分割成較小的區塊，則您應該分別使用 DecoderEncoder 方法或 方法所提供的 GetDecoder 或 GetEncoder 方法。

注意

這個方法的目的是在 Unicode 字元上運作，而不是在任意二進位數據上運作，例如位元組陣列。 如果您需要將任意二進位數據編碼為文字，您應該使用 uuencode 之類的通訊協定，其是由 之類的 Convert.ToBase64CharArray方法實作。

方法 GetCharCount 會決定譯碼位元組序列所產生的字元數，而 GetChars 方法會執行實際的譯碼。 方法 Encoding.GetChars 預期會進行離散轉換，與方法相反 Decoder.GetChars ，此方法會處理單一輸入數據流上的多個傳遞。

支持數個和 GetCharCountGetChars 版本。 以下是使用這些方法的一些程式設計考慮：

• 您的應用程式可能需要從代碼頁譯碼多個輸入位元組，並使用多個呼叫處理位元組。 在此情況下，您可能需要維護呼叫之間的狀態，因為位元組序列可以在批次中處理時中斷。 (例如，ISO-2022 班次序列的一部分可能會結束一個GetChars呼叫，並在下一個呼叫的開頭繼續。將會針對這些不完整的序列呼叫後援，但Decoder會記住下一GetChars個呼叫Encoding.GetChars的序列。)

• 如果您的應用程式處理字串輸出，建議您使用 GetString 方法。 由於這個方法必須檢查字串長度並配置緩衝區，所以會稍微慢一點，但建議使用產生的 String 類型。

• 的位元組版本 GetChars(Byte*, Int32, Char*, Int32) 允許一些快速技術，特別是對大型緩衝區的多個呼叫。 不過，請記住，此方法版本有時不安全，因為需要指標。

• 如果您的應用程式必須轉換大量數據，它應該重複使用輸出緩衝區。 在此情況下， GetChars(Byte[], Int32, Int32, Char[], Int32) 支持輸出字元緩衝區的版本是最佳選擇。

• 請考慮使用 Decoder.Convert 方法，而不是 GetCharCount。 轉換方法會儘可能轉換數據，並在輸出緩衝區太小時擲回例外狀況。 針對數據流的連續譯碼，此方法通常是最佳選擇。

另請參閱

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