Encoder Class
Converts a set of characters into a sequence of bytes.
Assembly: mscorlib (in mscorlib.dll)
To obtain an instance of an implementation of the Encoder class, the application should use the GetEncoder method of an Encoding implementation.
The GetByteCount method determines how many bytes result in encoding a set of Unicode characters, and the GetBytes method performs the actual encoding. There are several versions of both of these methods available in the Encoder class. For more information, see GetBytes.
A Encoder object maintains state information between successive calls to GetBytes or Convert methods so that it can correctly encode character sequences that span blocks. 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. 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.
Note: |
|---|
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. 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
A Decoder or Encoder object can be serialized during a conversion operation. 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.
The following example demonstrates how to convert an array of Unicode characters into blocks of bytes using a specified encoding. For comparison, the array of characters is first encoded using UTF7Encoding. Next, the array of characters is encoded using an Encoder.
Imports System Imports System.Text Imports Microsoft.VisualBasic 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 'Main 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 'ShowArray End Class 'EncoderTest '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] '
Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98, Windows CE, Windows Mobile for Smartphone, Windows Mobile for Pocket PC, Xbox 360, Zune
The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.
Note: