Encoder.GetBytes 方法

定義

命名空間:

System.Text

組件:

mscorlib.dll

當在衍生類別中被覆寫時，會將一組字元編碼成一串位元組。

多載

名稱	Description
GetBytes(Char*, Int32, Byte*, Int32, Boolean)	當在派生類別中覆寫時，會將一組從指定字元指標開始的字元，以及內部緩衝區中的任何字元編碼成一串位元組，從指定的位元組指標開始儲存。 一個參數表示轉換後是否要清除編碼器的內部狀態。
GetBytes(Char[], Int32, Int32, Byte[], Int32, Boolean)	當在派生類別中覆寫時，會將指定字元陣列中的一組字元及內部緩衝區中的任何字元編碼到指定的位元組陣列中。 一個參數表示轉換後是否要清除編碼器的內部狀態。

備註

請記住， Encoder 物件會在呼叫 之間 GetBytes儲存狀態。 當應用程式完成資料串流時，應在最後一次呼叫中將參數設 flush 為 true ， GetBytes 以確保狀態資訊被清除且編碼的位元組被正確終止。 使用此設定，編碼器會忽略資料區塊末端的無效位元組，如未匹配的替代或不完整的合併序列，並清除內部緩衝區。

為了計算儲存所得字元所需的精確緩衝區大小 GetBytes ，應用程式應使用 GetByteCount。

若 GetBytes 被 設定flushfalse為 ，編碼器會在資料區塊末尾的後續位元組儲存在內部緩衝區，並在下一次編碼操作中使用。 應用程式應在呼叫GetBytes同一區塊前立即呼叫GetByteCount該資料區塊，使前一個區塊的後續字元被納入計算中。

如果你的應用程式是轉換輸入串流的多個區段，建議考慮使用此 Convert 方法。 GetBytes 如果輸出緩衝區不夠大，會拋出例外，但 Convert 會盡可能填滿空間並回傳字元的讀取和寫入的位元組數。 還有更多評論請參見主題 Encoding.GetBytes 。

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

重要

此 API 不符合 CLS 規範。

當在派生類別中覆寫時，會將一組從指定字元指標開始的字元，以及內部緩衝區中的任何字元編碼成一串位元組，從指定的位元組指標開始儲存。 一個參數表示轉換後是否要清除編碼器的內部狀態。

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

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

參數

chars

Char*

一個指向第一個要編碼字元的指標。

charCount

Int32

需要編碼的字元數。

bytes

Byte*

一個指向開始寫入產生的位元組序列位置的指標。

byteCount

Int32

最大可寫入位元組數。

flush

Boolean

true轉換後清除編碼器內部狀態;否則，。 false

傳回

Int32

參數所示 bytes 位置實際寫入的位元組數。

屬性

CLSCompliantAttribute ComVisibleAttribute SecurityCriticalAttribute

例外狀況

ArgumentNullException

chars 是 null （Nothing）。

-或-

bytes 是 null （Nothing）。

ArgumentOutOfRangeException

charCount 或 byteCount 小於零。

ArgumentException

byteCount 小於所得位元組數。

EncoderFallbackException

後來出現了備用機制（更多資訊請參見 .NET 中的字元編碼）

-及-

Fallback 設定為 EncoderExceptionFallback。

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

當在派生類別中覆寫時，會將指定字元陣列中的一組字元及內部緩衝區中的任何字元編碼到指定的位元組陣列中。 一個參數表示轉換後是否要清除編碼器的內部狀態。

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

參數

chars

Char[]

包含要編碼字元集合的字元陣列。

charIndex

Int32

第一個要編碼字元的索引。

charCount

Int32

需要編碼的字元數。

bytes

Byte[]

這個位元組陣列用來包含產生的位元組序列。

byteIndex

Int32

索引開始寫入產生的位元組序列。

flush

Boolean

true轉換後清除編碼器內部狀態;否則，。 false

傳回

Int32

寫入 bytes的實際位元組數。

例外狀況

ArgumentNullException

chars 是 null （Nothing）。

-或-

bytes 是 null （Nothing）。

ArgumentOutOfRangeException

charIndex 或 charCount 或 byteIndex 小於零。

-或-

charIndex 且 charCount 不表示在 中的 chars有效範圍。

-或-

byteIndex 在 中 不是有效的指標 bytes。

ArgumentException

bytes 從陣列到末端的容量 byteIndex 不足以容納產生的位元組。

EncoderFallbackException

後來出現了備用機制（更多資訊請參見 .NET 中的字元編碼）

-及-

Fallback 設定為 EncoderExceptionFallback。

範例

以下範例示範如何從字元陣列編碼一組元素，並將編碼的位元組儲存在位元組陣列中的元素範圍中。 此 GetByteCount 方法用於決定所需 GetBytes陣列的大小。

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