UTF8Encoding.GetBytes 方法

定義

命名空間:

System.Text

組件:

System.Text.Encoding.Extensions.dll

將一組字元編碼成位元組序列。

多載

GetBytes(ReadOnlySpan<Char>, Span<Byte>)	將指定的字元範圍編碼為指定的位元組範圍。
GetBytes(Char*, Int32, Byte*, Int32)	將起始於指定字元指標的一組字元編碼成位元組序列；儲存該位元組序列時，係以指定的位元組指標為起始點。
GetBytes(Char[], Int32, Int32, Byte[], Int32)	將指定字元陣列中的一組字元編碼成指定的位元組陣列。
GetBytes(String, Int32, Int32, Byte[], Int32)	將指定 String 中的一組字元編碼成指定的位元組陣列。

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

來源:

UTF8Encoding.cs

將指定的字元範圍編碼為指定的位元組範圍。

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

public override int GetBytes (ReadOnlySpan<char> chars, Span<byte> bytes);

override this.GetBytes : ReadOnlySpan<char> * Span<byte> -> int

Public Overrides Function GetBytes (chars As ReadOnlySpan(Of Char), bytes As Span(Of Byte)) As Integer

參數

chars

ReadOnlySpan<Char>

要編碼的字元範圍。

bytes

Span<Byte>

包含所產生之位元組集合的範圍。

傳回

Int32

寫入 bytes 的實際位元組數。

備註

若要計算儲存所產生位元組所需的 GetBytes 確切大小，請呼叫 GetByteCount 方法。 若要計算大小上限，請呼叫 GetMaxByteCount 方法。 方法 GetByteCount 通常會配置較少的記憶體，而 GetMaxByteCount 方法通常會更快執行。

發生錯誤偵測時，無效的序列會導致這個方法擲回 ArgumentException 例外狀況。 若未偵測錯誤，則會忽略無效的序列，而且不會擲回例外狀況。

要轉換的數據，例如從數據流讀取的數據，可能只能在循序區塊中使用。 在此情況下，或者，如果數據量太大，因此需要分成較小的區塊，請分別使用 DecoderEncoder 方法或 方法所GetDecoder傳回的 。GetEncoder

為了確保編碼的位元組在儲存為檔案或數據流時正確譯碼，您可以使用前置詞來前置編碼位元組的數據流。 將前置詞插入位元組數據流開頭 (，例如要寫入檔案的一系列位元組開頭，) 是開發人員的責任。 方法 GetBytes 不會在一連串編碼位元組的開頭加上前置詞。

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

來源:

UTF8Encoding.cs

重要

此 API 不符合 CLS 規範。

將起始於指定字元指標的一組字元編碼成位元組序列；儲存該位元組序列時，係以指定的位元組指標為起始點。

public:
 override int GetBytes(char* chars, int charCount, System::Byte* bytes, int byteCount);

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

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

參數

chars

Char*

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

charCount

Int32

要編碼的字元數。

bytes

Byte*

開始寫入結果位元組序列的位置指標。

byteCount

Int32

寫入的最大位元組數。

傳回

Int32

在 bytes 所表示的位置上寫入的實際位元組數目。

屬性

CLSCompliantAttribute

例外狀況

ArgumentNullException

chars 為 null。

-或-

bytes 為 null。

ArgumentOutOfRangeException

charCount 或 byteCount 小於零。

ArgumentException

已啟用錯誤偵測，而 chars 包含無效的字元序列。

-或-

byteCount 小於結果位元組數。

EncoderFallbackException

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

-和-

EncoderFallback 設定為 EncoderExceptionFallback。

備註

若要計算儲存結果位元組所需的 GetBytes 確切數位大小，請呼叫 GetByteCount 方法。 若要計算數位大小上限，請呼叫 GetMaxByteCount 方法。 方法 GetByteCount 通常會配置較少的記憶體，而 GetMaxByteCount 方法通常會更快執行。

發生錯誤偵測時，無效的序列會導致這個方法擲回 ArgumentException 例外狀況。 若未偵測錯誤，則會忽略無效的序列，而且不會擲回例外狀況。

要轉換的數據，例如從數據流讀取的數據，可能只能在循序區塊中使用。 在此情況下，或者，如果數據量太大，因此需要分成較小的區塊，請分別使用 DecoderEncoder 方法或 方法所GetDecoder傳回的 。GetEncoder

為了確保編碼的位元組在儲存為檔案或數據流時正確譯碼，您可以使用前置詞來前置編碼位元組的數據流。 將前置詞插入位元組數據流開頭 (，例如要寫入檔案的一系列位元組開頭，) 是開發人員的責任。 方法 GetBytes 不會在一連串編碼位元組的開頭加上前置詞。

另請參閱

• GetEncoder()
• GetByteCount(Char[], Int32, Int32)
• GetMaxByteCount(Int32)

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

來源:

UTF8Encoding.cs

將指定字元陣列中的一組字元編碼成指定的位元組陣列。

public:
 override int GetBytes(cli::array <char> ^ chars, int charIndex, int charCount, cli::array <System::Byte> ^ bytes, int byteIndex);

public override int GetBytes (char[] chars, int charIndex, int charCount, byte[] bytes, int byteIndex);

override this.GetBytes : char[] * int * int * byte[] * int -> int

Public Overrides Function GetBytes (chars As Char(), charIndex As Integer, charCount As Integer, bytes As Byte(), byteIndex As Integer) As Integer

參數

chars

Char[]

包含要解碼之一組字元的字元陣列。

charIndex

Int32

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

charCount

Int32

要編碼的字元數。

bytes

Byte[]

要包含結果位元組序列的位元組陣列。

byteIndex

Int32

要開始寫入結果位元組序列的索引。

傳回

Int32

寫入 bytes 的實際位元組數。

例外狀況

ArgumentNullException

chars 為 null。

-或-

bytes 為 null。

ArgumentOutOfRangeException

charIndex、charCount 或 byteIndex 小於零。

-或-

charIndex 與 charCount 不代表 chars 中有效的範圍。

-或-

byteIndex 在 bytes 中不是有效的索引。

ArgumentException

已啟用錯誤偵測，而 chars 包含無效的字元序列。

-或-

從 bytes 到陣列結尾處，byteIndex 沒有足夠的容量容納結果位元組。

EncoderFallbackException

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

-和-

EncoderFallback 設定為 EncoderExceptionFallback。

範例

下列範例會 GetBytes 使用 方法來編碼字串中的字元範圍，並將編碼的位元組儲存在位元組陣列中的元素範圍內。

using namespace System;
using namespace System::Text;
using namespace System::Collections;
int main()
{
   array<Byte>^bytes;
   String^ chars = "UTF8 Encoding Example";
   UTF8Encoding^ utf8 = gcnew UTF8Encoding;
   int byteCount = utf8->GetByteCount( chars->ToCharArray(), 0, 13 );
   bytes = gcnew array<Byte>(byteCount);
   int bytesEncodedCount = utf8->GetBytes( chars, 0, 13, bytes, 0 );
   Console::WriteLine( "{0} bytes used to encode string.", 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();
}

using System;
using System.Text;

class UTF8EncodingExample {
    public static void Main() {
        Byte[] bytes;
        String chars = "UTF8 Encoding Example";
        
        UTF8Encoding utf8 = new UTF8Encoding();
        
        int byteCount = utf8.GetByteCount(chars.ToCharArray(), 0, 13);
        bytes = new Byte[byteCount];
        int bytesEncodedCount = utf8.GetBytes(chars, 0, 13, bytes, 0);
        
        Console.WriteLine(
            "{0} bytes used to encode string.", bytesEncodedCount
        );

        Console.Write("Encoded bytes: ");
        foreach (Byte b in bytes) {
            Console.Write("[{0}]", b);
        }
        Console.WriteLine();
    }
}

Imports System.Text

Class UTF8EncodingExample
    
    Public Shared Sub Main()
        Dim bytes() As Byte
        Dim chars As String = "UTF8 Encoding Example"
        
        Dim utf8 As New UTF8Encoding()
        
        Dim byteCount As Integer = utf8.GetByteCount(chars.ToCharArray(), 0, 13)
        bytes = New Byte(byteCount - 1) {}
        Dim bytesEncodedCount As Integer = utf8.GetBytes(chars, 0, 13, bytes, 0)
        
        Console.WriteLine("{0} bytes used to encode string.", 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

備註

若要計算儲存結果位元組所需的 GetBytes 確切數位大小，請呼叫 GetByteCount 方法。 若要計算數位大小上限，請呼叫 GetMaxByteCount 方法。 方法 GetByteCount 通常會配置較少的記憶體，而 GetMaxByteCount 方法通常會更快執行。

發生錯誤偵測時，無效的序列會導致這個方法擲回 ArgumentException 例外狀況。 若未偵測錯誤，則會忽略無效的序列，而且不會擲回例外狀況。

要轉換的數據，例如從數據流讀取的數據，可能只能在循序區塊中使用。 在此情況下，或者，如果資料量太大，因此需要分成較小的區塊，請分別使用 DecoderEncoder 方法或 方法所提供的 GetDecoder 或 GetEncoder 。

為了確保編碼的位元組在儲存為檔案或數據流時正確譯碼，您可以使用前置詞來前置編碼位元組的數據流。 將前置詞插入位元組數據流開頭 (，例如要寫入檔案的一系列位元組開頭，) 是開發人員的責任。 方法 GetBytes 不會在一連串編碼位元組的開頭加上前置詞。

另請參閱

• GetEncoder()
• GetByteCount(Char[], Int32, Int32)
• GetMaxByteCount(Int32)

GetBytes(String, Int32, Int32, Byte[], Int32)

來源:

UTF8Encoding.cs

將指定 String 中的一組字元編碼成指定的位元組陣列。

public:
 override int GetBytes(System::String ^ s, int charIndex, int charCount, cli::array <System::Byte> ^ bytes, int byteIndex);

public override int GetBytes (string s, int charIndex, int charCount, byte[] bytes, int byteIndex);

override this.GetBytes : string * int * int * byte[] * int -> int

Public Overrides Function GetBytes (s As String, charIndex As Integer, charCount As Integer, bytes As Byte(), byteIndex As Integer) As Integer

參數

s

String

String，包含要編碼的一組字元。

charIndex

Int32

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

charCount

Int32

要編碼的字元數。

bytes

Byte[]

要包含結果位元組序列的位元組陣列。

byteIndex

Int32

要開始寫入結果位元組序列的索引。

傳回

Int32

寫入 bytes 的實際位元組數。

例外狀況

ArgumentNullException

s 為 null。

-或-

bytes 為 null。

ArgumentOutOfRangeException

charIndex、charCount 或 byteIndex 小於零。

-或-

charIndex 與 charCount 不代表 chars 中有效的範圍。

-或-

byteIndex 在 bytes 中不是有效的索引。

ArgumentException

已啟用錯誤偵測，而 s 包含無效的字元序列。

-或-

從 bytes 到陣列結尾處，byteIndex 沒有足夠的容量容納結果位元組。

EncoderFallbackException

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

-和-

EncoderFallback 設定為 EncoderExceptionFallback。

範例

下列範例會 GetBytes 使用 方法來編碼 Unicode 字元陣列中的專案範圍，並將編碼的位元組儲存在位元組數位中的元素範圍內。

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'};
   UTF8Encoding^ utf8 = gcnew UTF8Encoding;
   int byteCount = utf8->GetByteCount( chars, 1, 2 );
   bytes = gcnew array<Byte>(byteCount);
   int bytesEncodedCount = utf8->GetBytes( chars, 1, 2, bytes, 0 );
   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();
}

using System;
using System.Text;

class UTF8EncodingExample {
    public static void Main() {
        Byte[] bytes;
        // Unicode characters.
        Char[] chars = new Char[] {
            '\u0023', // #
            '\u0025', // %
            '\u03a0', // Pi
            '\u03a3'  // Sigma
        };
        
        UTF8Encoding utf8 = new UTF8Encoding();
        
        int byteCount = utf8.GetByteCount(chars, 1, 2);
        bytes = new Byte[byteCount];
        int bytesEncodedCount = utf8.GetBytes(chars, 1, 2, bytes, 0);
        
        Console.WriteLine(
            "{0} bytes used to encode characters.", bytesEncodedCount
        );

        Console.Write("Encoded bytes: ");
        foreach (Byte b in bytes) {
            Console.Write("[{0}]", b);
        }
        Console.WriteLine();
    }
}

Imports System.Text
Imports Microsoft.VisualBasic.Strings

Class UTF8EncodingExample
    
    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 utf8 As New UTF8Encoding()
        
        Dim byteCount As Integer = utf8.GetByteCount(chars, 1, 2)
        bytes = New Byte(byteCount - 1) {}
        Dim bytesEncodedCount As Integer = utf8.GetBytes(chars, 1, 2, bytes, 0)
        
        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

備註

若要計算儲存結果位元組所需的 GetBytes 確切數位大小，請呼叫 GetByteCount 方法。 若要計算數位大小上限，請呼叫 GetMaxByteCount 方法。 方法 GetByteCount 通常會配置較少的記憶體，而 GetMaxByteCount 方法通常會更快執行。

發生錯誤偵測時，無效的序列會導致這個方法擲回 ArgumentException 例外狀況。 若未偵測錯誤，則會忽略無效的序列，而且不會擲回例外狀況。

要轉換的數據，例如從數據流讀取的數據，可能只能在循序區塊中使用。 在此情況下，或者，如果資料量太大，因此需要分成較小的區塊，請分別使用 DecoderEncoder 方法或 方法所提供的 GetDecoder 或 GetEncoder 。

為了確保編碼的位元組在儲存為檔案或數據流時正確譯碼，您可以使用前置詞來前置編碼位元組的數據流。 將前置詞插入位元組數據流開頭 (，例如要寫入檔案的一系列位元組開頭，) 是開發人員的責任。 方法 GetBytes 不會在一連串編碼位元組的開頭加上前置詞。

另請參閱

• GetEncoder()
• GetByteCount(Char[], Int32, Int32)
• GetMaxByteCount(Int32)