Encoder 類別

定義

命名空間:

System.Text

組件:

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 namespace System;
using namespace System::Text;
using namespace System::Collections;
void ShowArray( Array^ theArray )
{
   IEnumerator^ myEnum = theArray->GetEnumerator();
   while ( myEnum->MoveNext() )
   {
      Object^ o = safe_cast<Object^>(myEnum->Current);
      Console::Write( "[{0}]", o );
   }

   Console::WriteLine( "\n" );
}

int main()
{
   
   // The characters to encode.
   
   // Pi
   // Sigma
   array<Char>^chars = {L'\u03a0',L'\u03a3',L'\u03a6',L'\u03a9'};
   
   // Encode characters using an Encoding Object*.
   Encoding^ encoding = Encoding::UTF7;
   Console::WriteLine( "Using Encoding\n--------------" );
   
   // Encode complete array for comparison.
   array<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.
   array<Byte>^firstchar = encoding->GetBytes( chars, 0, 1 );
   Console::WriteLine( "First character:" );
   ShowArray( firstchar );
   array<Byte>^secondchar = encoding->GetBytes( chars, 1, 1 );
   Console::WriteLine( "Second character:" );
   ShowArray( secondchar );
   array<Byte>^thirdchar = encoding->GetBytes( chars, 2, 1 );
   Console::WriteLine( "Third character:" );
   ShowArray( thirdchar );
   array<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.
   array<Byte>^allCharactersFromEncoder = gcnew array<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.
   array<Byte>^firstcharNoFlush = gcnew array<Byte>(encoder->GetByteCount( chars, 0, 1, bFlushState ));
   encoder->GetBytes( chars, 0, 1, firstcharNoFlush, 0, bFlushState );
   Console::WriteLine( "First character:" );
   ShowArray( firstcharNoFlush );
   array<Byte>^secondcharNoFlush = gcnew array<Byte>(encoder->GetByteCount( chars, 1, 1, bFlushState ));
   encoder->GetBytes( chars, 1, 1, secondcharNoFlush, 0, bFlushState );
   Console::WriteLine( "Second character:" );
   ShowArray( secondcharNoFlush );
   array<Byte>^thirdcharNoFlush = gcnew array<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;
   array<Byte>^fourthcharNoFlush = gcnew array<Byte>(encoder->GetByteCount( chars, 3, 1, bFlushState ));
   encoder->GetBytes( chars, 3, 1, fourthcharNoFlush, 0, bFlushState );
   Console::WriteLine( "Fourth character:" );
   ShowArray( fourthcharNoFlush );
}

/* This code example produces the following output.

Using Encoding
--------------
All characters encoded:
[43][65][54][65][68][111][119][79][109][65][54][107][45]

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

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

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

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

Using Encoder
-------------
All characters encoded:
[43][65][54][65][68][111][119][79][109][65][54][107][45]

First character:
[43][65][54]

Second character:
[65][68][111]

Third character:
[119][79][109]

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


*/

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也會在數據區塊結尾保留尾端的字元，並在下一個編碼作業中使用尾端字元。 例如，數據區塊的結尾可能是不相符的高 Surrogate，而相符的低 Surrogate 可能位於下一個數據區塊中。 因此， GetDecoder 和 GetEncoder 對於網路傳輸和檔案作業很有用，因為這些作業通常會處理數據區塊，而不是完整的數據流。

注意

當應用程式使用數據流完成時，應該在適當的方法呼叫中將 參數true設定flush為 ，以確定狀態資訊已排清。 如果發生例外狀況，或應用程式切換數據流，則應該呼叫 Reset 以清除對象的內部狀態 Encoder 。

給實施者的注意事項

當您的應用程式繼承自這個類別時，它必須覆寫所有成員。

建構函式

Encoder()

初始化 Encoder 類別的新執行個體。

屬性

Fallback	取得或設定目前 EncoderFallback 物件的 Encoder 物件。
FallbackBuffer	取得與目前 EncoderFallbackBuffer 物件關聯的 Encoder 物件。

方法

Convert(Char*, Int32, Byte*, Int32, Boolean, Int32, Int32, Boolean)	將 Unicode 字元的緩衝區轉換成編碼的位元組序列，並將結果儲存在另一個緩衝區。
Convert(Char[], Int32, Int32, Byte[], Int32, Int32, Boolean, Int32, Int32, Boolean)	將 Unicode 字元的陣列轉換成編碼的位元組序列，並將結果儲存在位元組陣列中。
Convert(ReadOnlySpan<Char>, Span<Byte>, Boolean, Int32, Int32, Boolean)	將 Unicode 字元範圍轉換為編碼的位元組序列，並將結果儲存在另一個緩衝區內。
Equals(Object)	判斷指定的物件是否等於目前的物件。 (繼承來源 Object)
GetByteCount(Char*, Int32, Boolean)	在衍生類別中覆寫時，計算從指定的字元指標開始，編碼一組字元所產生的位元組數目。 參數會指示，在計算之後是否要清除編碼器的內部狀態。
GetByteCount(Char[], Int32, Int32, Boolean)	在衍生類別中覆寫時，計算從指定的字元陣列編碼一組字元所產生的位元組數目。 參數會指示，在計算之後是否要清除編碼器的內部狀態。
GetByteCount(ReadOnlySpan<Char>, Boolean)	在衍生類別中覆寫時，計算藉由編碼 'chars' 範圍中一組字元所產生的位元組數。 參數會指示，在計算之後是否要清除編碼器的內部狀態。
GetBytes(Char*, Int32, Byte*, Int32, Boolean)	在衍生類別中覆寫時，將以指定字元指標開始的一組字元以及內部緩衝區內的任何字元，編碼成位元組序列 (會從指定的位元組指標開始存放此序列)。 參數會指示，在轉換之後是否要清除編碼器的內部狀態。
GetBytes(Char[], Int32, Int32, Byte[], Int32, Boolean)	在衍生類別中覆寫時，將指定字元陣列中的一組字元以及內部緩衝區內的任何字元，編碼成指定的位元組陣列。 參數會指示，在轉換之後是否要清除編碼器的內部狀態。
GetBytes(ReadOnlySpan<Char>, Span<Byte>, Boolean)	在衍生類別中覆寫時，將輸入字元範圍中一組字元和內部緩衝區內的任何字元編碼成儲存在輸入位元組範圍內的位元組序列。 參數會指示，在轉換之後是否要清除編碼器的內部狀態。
GetHashCode()	做為預設雜湊函式。 (繼承來源 Object)
GetType()	取得目前執行個體的 Type。 (繼承來源 Object)
MemberwiseClone()	建立目前 Object 的淺層複製。 (繼承來源 Object)
Reset()	在衍生類別中覆寫時，將編碼器設定回其初始狀態。
ToString()	傳回代表目前物件的字串。 (繼承來源 Object)

擴充方法

Convert(Encoder, ReadOnlySequence<Char>, IBufferWriter<Byte>, Boolean, Int64, Boolean)	將 ReadOnlySequence<T> 轉換成編碼的位元組，並將結果寫入到 writer。
Convert(Encoder, ReadOnlySpan<Char>, IBufferWriter<Byte>, Boolean, Int64, Boolean)	使用 encoder 來將 ReadOnlySpan<T> 轉換成位元組，並將結果寫入到 writer。

另請參閱

• Decoder
• Encoding
• 瞭解編碼