Encoder 類別

定義

命名空間:

System.Text

組件:

netstandard.dll, System.Runtime.dll

來源:

Encoder.cs

將一組字元轉換成一串位元組。

public ref class Encoder abstract

public abstract class Encoder

type Encoder = class

Public MustInherit Class Encoder

繼承

Object

Encoder

範例

以下範例示範如何使用指定的編碼方式將一組 Unicode 字元轉換成位元組區塊。 作為比較，字元陣列首先使用 UTF7Encoding。 接著，字元陣列會用 Encoder編碼。

using System;
using System.Text;

class EncoderTest {
    public static void Main() {
        // The characters to encode.
        Char[] chars = new Char[] {
            '\u0023', // #
            '\u0025', // %
            '\u03a0', // Pi
            '\u03a3'  // Sigma
        };

        // Encode characters using an Encoding object.
        Encoding encoding = Encoding.UTF7;
        Console.WriteLine("Using Encoding\n--------------");

        // Encode complete array for comparison.
        Byte[] allCharactersFromEncoding = encoding.GetBytes(chars);
        Console.WriteLine("All characters encoded:");
        ShowArray(allCharactersFromEncoding);

        // Encode characters, one-by-one.
        // The Encoding object will NOT maintain state between calls.
        Byte[] firstchar = encoding.GetBytes(chars, 0, 1);
        Console.WriteLine("First character:");
        ShowArray(firstchar);

        Byte[] secondchar = encoding.GetBytes(chars, 1, 1);
        Console.WriteLine("Second character:");
        ShowArray(secondchar);

        Byte[] thirdchar = encoding.GetBytes(chars, 2, 1);
        Console.WriteLine("Third character:");
        ShowArray(thirdchar);

        Byte[] fourthchar = encoding.GetBytes(chars, 3, 1);
        Console.WriteLine("Fourth character:");
        ShowArray(fourthchar);

        // Now, encode characters using an Encoder object.
        Encoder encoder = encoding.GetEncoder();
        Console.WriteLine("Using Encoder\n-------------");

        // Encode complete array for comparison.
        Byte[] allCharactersFromEncoder = new Byte[encoder.GetByteCount(chars, 0, chars.Length, true)];
        encoder.GetBytes(chars, 0, chars.Length, allCharactersFromEncoder, 0, true);
        Console.WriteLine("All characters encoded:");
        ShowArray(allCharactersFromEncoder);

        // Do not flush state; i.e. maintain state between calls.
        bool bFlushState = false;

        // Encode characters one-by-one.
        // By maintaining state, the Encoder will not store extra bytes in the output.
        Byte[] firstcharNoFlush = new Byte[encoder.GetByteCount(chars, 0, 1, bFlushState)];
        encoder.GetBytes(chars, 0, 1, firstcharNoFlush, 0, bFlushState);
        Console.WriteLine("First character:");
        ShowArray(firstcharNoFlush);

        Byte[] secondcharNoFlush = new Byte[encoder.GetByteCount(chars, 1, 1, bFlushState)];
        encoder.GetBytes(chars, 1, 1, secondcharNoFlush, 0, bFlushState);
        Console.WriteLine("Second character:");
        ShowArray(secondcharNoFlush);

        Byte[] thirdcharNoFlush = new Byte[encoder.GetByteCount(chars, 2, 1, bFlushState)];
        encoder.GetBytes(chars, 2, 1, thirdcharNoFlush, 0, bFlushState);
        Console.WriteLine("Third character:");
        ShowArray(thirdcharNoFlush);

        // Must flush state on last call to GetBytes().
        bFlushState = true;
        
        Byte[] fourthcharNoFlush = new Byte[encoder.GetByteCount(chars, 3, 1, bFlushState)];
        encoder.GetBytes(chars, 3, 1, fourthcharNoFlush, 0, bFlushState);
        Console.WriteLine("Fourth character:");
        ShowArray(fourthcharNoFlush);
    }

    public static void ShowArray(Array theArray) {
        foreach (Object o in theArray) {
            Console.Write("[{0}]", o);
        }
        Console.WriteLine("\n");
    }
}

/* This code example produces the following output.

Using Encoding
--------------
All characters encoded:
[43][65][67][77][65][74][81][79][103][65][54][77][45]

First character:
[43][65][67][77][45]

Second character:
[43][65][67][85][45]

Third character:
[43][65][54][65][45]

Fourth character:
[43][65][54][77][45]

Using Encoder
-------------
All characters encoded:
[43][65][67][77][65][74][81][79][103][65][54][77][45]

First character:
[43][65][67]

Second character:
[77][65][74]

Third character:
[81][79][103]

Fourth character:
[65][54][77][45]


*/

Imports System.Text
Imports Microsoft.VisualBasic.Strings

Class EncoderTest
    
    Public Shared Sub Main()
        ' Unicode characters.
        ' ChrW(35)  = #
        ' ChrW(37)  = %
        ' ChrW(928) = Pi
        ' ChrW(931) = Sigma
        Dim chars() As Char = {ChrW(35), ChrW(37), ChrW(928), ChrW(931)}
        
        ' Encode characters using an Encoding object.
        Dim encoding As Encoding = Encoding.UTF7
        Console.WriteLine( _
            "Using Encoding" & _
            ControlChars.NewLine & _
            "--------------" _
        )
        
        ' Encode complete array for comparison.
        Dim allCharactersFromEncoding As Byte() = encoding.GetBytes(chars)
        Console.WriteLine("All characters encoded:")
        ShowArray(allCharactersFromEncoding)
        
        ' Encode characters, one-by-one.
        ' The Encoding object will NOT maintain state between calls.
        Dim firstchar As Byte() = encoding.GetBytes(chars, 0, 1)
        Console.WriteLine("First character:")
        ShowArray(firstchar)
        
        Dim secondchar As Byte() = encoding.GetBytes(chars, 1, 1)
        Console.WriteLine("Second character:")
        ShowArray(secondchar)
        
        Dim thirdchar As Byte() = encoding.GetBytes(chars, 2, 1)
        Console.WriteLine("Third character:")
        ShowArray(thirdchar)
        
        Dim fourthchar As Byte() = encoding.GetBytes(chars, 3, 1)
        Console.WriteLine("Fourth character:")
        ShowArray(fourthchar)
        
        
        ' Now, encode characters using an Encoder object.
        Dim encoder As Encoder = encoding.GetEncoder()
        Console.WriteLine( _
            "Using Encoder" & _
            ControlChars.NewLine & _
            "-------------" _
        )
        
        ' Encode complete array for comparison.
        Dim allCharactersFromEncoder( _
            encoder.GetByteCount(chars, 0, chars.Length, True) _
        ) As Byte
        encoder.GetBytes(chars, 0, chars.Length, allCharactersFromEncoder, 0, True)
        Console.WriteLine("All characters encoded:")
        ShowArray(allCharactersFromEncoder)
        
        ' Do not flush state; i.e. maintain state between calls.
        Dim bFlushState As Boolean = False
        
        ' Encode characters one-by-one.
        ' By maintaining state, the Encoder will not store extra bytes in the output.
        Dim firstcharNoFlush( _
            encoder.GetByteCount(chars, 0, 1, bFlushState) _
        ) As Byte
        encoder.GetBytes(chars, 0, 1, firstcharNoFlush, 0, bFlushState)
        Console.WriteLine("First character:")
        ShowArray(firstcharNoFlush)
        
        Dim secondcharNoFlush( _
            encoder.GetByteCount(chars, 1, 1, bFlushState) _
        ) As Byte
        encoder.GetBytes(chars, 1, 1, secondcharNoFlush, 0, bFlushState)
        Console.WriteLine("Second character:")
        ShowArray(secondcharNoFlush)
        
        Dim thirdcharNoFlush( _
            encoder.GetByteCount(chars, 2, 1, bFlushState) _
        ) As Byte
        encoder.GetBytes(chars, 2, 1, thirdcharNoFlush, 0, bFlushState)
        Console.WriteLine("Third character:")
        ShowArray(thirdcharNoFlush)
        
        ' Must flush state on last call to GetBytes().
        bFlushState = True
        
        Dim fourthcharNoFlush( _
            encoder.GetByteCount(chars, 3, 1, bFlushState) _
        ) As Byte
        encoder.GetBytes(chars, 3, 1, fourthcharNoFlush, 0, bFlushState)
        Console.WriteLine("Fourth character:")
        ShowArray(fourthcharNoFlush)
    End Sub
    
    
    Public Shared Sub ShowArray(theArray As Array)
        Dim o As Object
        For Each o In  theArray
            Console.Write("[{0}]", o)
        Next o
        Console.WriteLine(ControlChars.NewLine)
    End Sub
End Class

'This code example produces the following output.
'
'Using Encoding
'--------------
'All characters encoded:
'[43][65][67][77][65][74][81][79][103][65][54][77][45]
'
'First character:
'[43][65][67][77][45]
'
'Second character:
'[43][65][67][85][45]
'
'Third character:
'[43][65][54][65][45]
'
'Fourth character:
'[43][65][54][77][45]
'
'Using Encoder
'-------------
'All characters encoded:
'[43][65][67][77][65][74][81][79][103][65][54][77][45][0]
'
'First character:
'[43][65][67][0]
'
'Second character:
'[77][65][74][0]
'
'Third character:
'[81][79][103][0]
'
'Fourth character:
'[65][54][77][45][0]
'

備註

要取得該 Encoder 類別實作的實例，應用程式應使用 GetEncoder 實 Encoding 作的方法。

該 GetByteCount 方法決定編碼一組 Unicode 字元的位元組數，並 GetBytes 執行實際編碼。 這 Encoder 兩種方法在課程中都有多種版本可供選擇。 如需詳細資訊，請參閱Encoding.GetBytes。

物件 Encoder 會在連續呼叫 GetBytes 或 Convert 方法之間維持狀態資訊，以便正確編碼跨越區塊的字元序列。 它 Encoder 也會保留資料區塊末尾的尾部字元，並在下一次編碼操作中使用這些尾部字元。 例如，一個資料區塊可能以一個未匹配的高代體結尾，而匹配的低代體可能在下一個資料區塊中。 因此， GetDecoder 和 GetEncoder 對於網路傳輸和檔案操作非常有用，因為這些操作通常處理的是資料區塊，而非完整的資料流。

Note

當應用程式處理資料流時，應確保狀態資訊被清除，方法是在適當的方法呼叫中設定flush參數為 。true 若發生例外或應用程式切換串流，應呼叫 Reset 以清除物件的內部狀態 Encoder 。

給實施者的注意事項

當你的應用程式繼承自此類別時，必須覆蓋所有成員。

建構函式

名稱	Description
Encoder()	初始化 Encoder 類別的新執行個體。

屬性

名稱	Description
Fallback	取得或設定EncoderFallback一個物件。Encoder
FallbackBuffer	取得 EncoderFallbackBuffer 與當前 Encoder 物件相關聯的物件。

方法

名稱	Description
Convert(Char[], Int32, Int32, Byte[], Int32, Int32, Boolean, Int32, Int32, Boolean)	將 Unicode 字元陣列轉換為編碼的位元組序列，並將結果儲存在位元組陣列中。
Convert(Char*, Int32, Byte*, Int32, Boolean, Int32, Int32, Boolean)	將一個 Unicode 字元緩衝區轉換成編碼的位元組序列，並將結果儲存在另一個緩衝區中。
Convert(ReadOnlySpan<Char>, Span<Byte>, Boolean, Int32, Int32, Boolean)	將一段 Unicode 字元轉換成編碼的位元組序列，並將結果儲存在另一個緩衝區。
Equals(Object)	判斷指定的物件是否等於目前的物件。 (繼承來源 Object)
GetByteCount(Char[], Int32, Int32, Boolean)	當在派生類別中覆寫時，會計算從指定字元陣列編碼一組字元所產生的位元組數。 一個參數表示計算後是否要清除編碼器的內部狀態。
GetByteCount(Char*, Int32, Boolean)	當在派生類別中覆寫時，會計算從指定字元指標開始編碼一組字元所產生的位元組數。 一個參數表示計算後是否要清除編碼器的內部狀態。
GetByteCount(ReadOnlySpan<Char>, Boolean)	當在衍生類別中覆寫時，會計算出在「char」區間編碼一組字元所產生的位元組數。 一個參數表示計算後是否要清除編碼器的內部狀態。
GetBytes(Char[], Int32, Int32, Byte[], Int32, Boolean)	當在派生類別中覆寫時，會將指定字元陣列中的一組字元及內部緩衝區中的任何字元編碼到指定的位元組陣列中。 一個參數表示轉換後是否要清除編碼器的內部狀態。
GetBytes(Char*, Int32, Byte*, Int32, Boolean)	當在派生類別中覆寫時，會將一組從指定字元指標開始的字元，以及內部緩衝區中的任何字元編碼成一串位元組，從指定的位元組指標開始儲存。 一個參數表示轉換後是否要清除編碼器的內部狀態。
GetBytes(ReadOnlySpan<Char>, Span<Byte>, Boolean)	當在衍生類別中覆寫時，會將輸入字元區間的一組字元及內部緩衝區的字元編碼成一列位元組，這些位元組儲存在輸入位元組區間中。 一個參數表示轉換後是否要清除編碼器的內部狀態。
GetHashCode()	做為預設哈希函式。 (繼承來源 Object)
GetType()	取得目前實例的 Type。 (繼承來源 Object)
MemberwiseClone()	建立目前 Object的淺層複本。 (繼承來源 Object)
Reset()	當在衍生類別中覆寫時，會將編碼器回到初始狀態。
ToString()	傳回表示目前 物件的字串。 (繼承來源 Object)

擴充方法

名稱	Description
Convert(Encoder, ReadOnlySequence<Char>, IBufferWriter<Byte>, Boolean, Int64, Boolean)	將 a ReadOnlySequence<T> 轉換成編碼位元組，並將結果寫入 writer。
Convert(Encoder, ReadOnlySpan<Char>, IBufferWriter<Byte>, Boolean, Int64, Boolean)	將 a ReadOnlySpan<T> 轉換為位元組，並 encoder 寫入 writer。

另請參閱

• Decoder
• Encoding
• 理解編碼