Encoder Encoder Encoder Encoder Class

定義

將一組字元轉換成位元組序列。Converts a set of characters into a sequence of bytes.

public ref class Encoder abstract
[System.Runtime.InteropServices.ComVisible(true)]
[System.Serializable]
public abstract class Encoder
type Encoder = class
Public MustInherit Class Encoder
繼承
EncoderEncoderEncoderEncoder
屬性

範例

下列範例示範如何使用指定的編碼方式,將 Unicode 字元陣列轉換成位元組區塊。The following example demonstrates how to convert an array of Unicode characters into blocks of bytes using a specified encoding. 為了進行比較,會先使用UTF7Encoding來編碼字元陣列。For comparison, the array of characters is first encoded using UTF7Encoding. 接下來,使用Encoder來編碼字元陣列。Next, the array of characters is encoded using an 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執行的方法。To obtain an instance of an implementation of the Encoder class, the application should use the GetEncoder method of an Encoding implementation.

方法會判斷有多少位元組會導致編碼一組 Unicode 字元,而方法則GetBytes會執行實際的編碼。 GetByteCountThe GetByteCount method determines how many bytes result in encoding a set of Unicode characters, and the GetBytes method performs the actual encoding. Encoder類別中,這兩種方法都有數個版本可供使用。There are several versions of both of these methods available in the Encoder class. 如需詳細資訊,請參閱Encoding.GetBytesFor more information, see Encoding.GetBytes.

物件會維護連續GetBytes呼叫或Convert方法之間的狀態資訊,讓它可以正確地編碼跨越區塊的字元序列。 EncoderA Encoder object maintains state information between successive calls to GetBytes or Convert methods so that it can correctly encode character sequences that span blocks. Encoder也會保留資料區塊結尾的尾端字元,並在下一個編碼作業中使用尾端字元。The Encoder also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. 例如,資料區塊的結尾可能會是不相符的高代理,而相符的低代理可能會在下一個資料區塊中。For example, a data block might end with an unmatched high surrogate, and the matching low surrogate might be in the next data block. 因此, GetDecoderGetEncoder適用于網路傳輸和檔案作業,因為這些作業通常會處理資料區塊,而不是完整的資料流程。Therefore, GetDecoder and GetEncoder are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream.

注意

當應用程式使用資料流程完成時,應在適當的方法呼叫中,將flush參數設定為true ,以確定狀態資訊已排清。When the application is done with a stream of data it should make sure that the state information is flushed by setting the flush parameter to true in the appropriate method call. 如果發生例外狀況,或應用程式切換資料流程,則應該呼叫Reset以清除Encoder物件的內部狀態。If an exception occurs or if the application switches streams, it should call Reset to clear the internal state of the Encoder object.

版本考慮Version Considerations

Decoder轉換Encoder作業期間,可以序列化或物件。A Decoder or Encoder object can be serialized during a conversion operation. 如果物件已在相同版本的 .NET Framework 中還原序列化,則會保留該物件的狀態,但如果另一個版本還原序列化,則會遺失。The state of the object is retained if it is deserialized in the same version of the .NET Framework, but lost if it is deserialized in another version.

給繼承者的注意事項

當您的應用程式繼承自這個類別時,它必須覆寫所有成員。When your application inherits from this class, it must override all the members.

建構函式

Encoder() Encoder() Encoder() Encoder()

初始化 Encoder 類別的新執行個體。Initializes a new instance of the Encoder class.

屬性

Fallback Fallback Fallback Fallback

取得或設定目前 EncoderFallback 物件的 Encoder 物件。Gets or sets a EncoderFallback object for the current Encoder object.

FallbackBuffer FallbackBuffer FallbackBuffer FallbackBuffer

取得與目前 EncoderFallbackBuffer 物件關聯的 Encoder 物件。Gets the EncoderFallbackBuffer object associated with the current Encoder object.

方法

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

將 Unicode 字元的緩衝區轉換成編碼的位元組序列,並將結果儲存在另一個緩衝區。Converts a buffer of Unicode characters to an encoded byte sequence and stores the result in another buffer.

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

將 Unicode 字元的陣列轉換成編碼的位元組序列,並將結果儲存在位元組陣列中。Converts an array of Unicode characters to an encoded byte sequence and stores the result in an array of bytes.

Convert(ReadOnlySpan<Char>, Span<Byte>, Boolean, Int32, Int32, Boolean) Convert(ReadOnlySpan<Char>, Span<Byte>, Boolean, Int32, Int32, Boolean) Convert(ReadOnlySpan<Char>, Span<Byte>, Boolean, Int32, Int32, Boolean) Convert(ReadOnlySpan<Char>, Span<Byte>, Boolean, Int32, Int32, Boolean)
Equals(Object) Equals(Object) Equals(Object) Equals(Object)

判斷指定的物件是否等於目前的物件。Determines whether the specified object is equal to the current object.

(Inherited from Object)
GetByteCount(Char*, Int32, Boolean) GetByteCount(Char*, Int32, Boolean) GetByteCount(Char*, Int32, Boolean) GetByteCount(Char*, Int32, Boolean)

在衍生類別中覆寫時,計算從指定的字元指標開始,編碼一組字元所產生的位元組數目。When overridden in a derived class, calculates the number of bytes produced by encoding a set of characters starting at the specified character pointer. 參數會指示,在計算之後是否要清除編碼器的內部狀態。A parameter indicates whether to clear the internal state of the encoder after the calculation.

GetByteCount(Char[], Int32, Int32, Boolean) GetByteCount(Char[], Int32, Int32, Boolean) GetByteCount(Char[], Int32, Int32, Boolean) GetByteCount(Char[], Int32, Int32, Boolean)

在衍生類別中覆寫時,計算從指定的字元陣列編碼一組字元所產生的位元組數目。When overridden in a derived class, calculates the number of bytes produced by encoding a set of characters from the specified character array. 參數會指示,在計算之後是否要清除編碼器的內部狀態。A parameter indicates whether to clear the internal state of the encoder after the calculation.

GetByteCount(ReadOnlySpan<Char>, Boolean) GetByteCount(ReadOnlySpan<Char>, Boolean) GetByteCount(ReadOnlySpan<Char>, Boolean) GetByteCount(ReadOnlySpan<Char>, Boolean)
GetBytes(Char*, Int32, Byte*, Int32, Boolean) GetBytes(Char*, Int32, Byte*, Int32, Boolean) GetBytes(Char*, Int32, Byte*, Int32, Boolean) GetBytes(Char*, Int32, Byte*, Int32, Boolean)

在衍生類別中覆寫時,將以指定字元指標開始的一組字元以及內部緩衝區內的任何字元,編碼成位元組序列 (會從指定的位元組指標開始存放此序列)。When overridden in a derived class, encodes a set of characters starting at the specified character pointer and any characters in the internal buffer into a sequence of bytes that are stored starting at the specified byte pointer. 參數會指示,在轉換之後是否要清除編碼器的內部狀態。A parameter indicates whether to clear the internal state of the encoder after the conversion.

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

在衍生類別中覆寫時,將指定字元陣列中的一組字元以及內部緩衝區內的任何字元,編碼成指定的位元組陣列。When overridden in a derived class, encodes a set of characters from the specified character array and any characters in the internal buffer into the specified byte array. 參數會指示,在轉換之後是否要清除編碼器的內部狀態。A parameter indicates whether to clear the internal state of the encoder after the conversion.

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

做為預設雜湊函式。Serves as the default hash function.

(Inherited from Object)
GetType() GetType() GetType() GetType()

取得目前執行個體的 TypeGets the Type of the current instance.

(Inherited from Object)
MemberwiseClone() MemberwiseClone() MemberwiseClone() MemberwiseClone()

建立目前 Object 的淺層複本 (Shallow Copy)。Creates a shallow copy of the current Object.

(Inherited from Object)
Reset() Reset() Reset() Reset()

在衍生類別中覆寫時,將編碼器設定回其初始狀態。When overridden in a derived class, sets the encoder back to its initial state.

ToString() ToString() ToString() ToString()

傳回代表目前物件的字串。Returns a string that represents the current object.

(Inherited from Object)

適用於

另請參閱