To obtain an instance of an implementation of the System.Text.Decoder class, the application should use the Encoding.GetDecoder method of an System.Text.Encoding implementation.

The Decoder.GetCharCount(Byte*, int, bool) method determines how many characters result in decoding a sequence of bytes, and the Decoder.GetChars(Byte*, int, Char*, int, bool) method performs the actual decoding. There are several versions of both of these methods available in the System.Text.Decoder class. For more information, see Encoding.GetChars(Byte[]). A System.Text.Decoder object maintains state information between successive calls to GetChars or Decoder.Convert(Byte[], int, int, Char[], int, int, bool, Int32@, Int32@, Boolean@) methods so it can correctly decode byte sequences that span blocks. The System.Text.Decoder also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, Encoding.GetDecoder and Encoding.GetEncoder are useful for network transmission and file operations because those operations often deal with blocks of data instead of a complete data stream.

Version Considerations

A System.Text.Decoder or System.Text.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.

The following example demonstrates using the System.Text.UTF8Encoding implementation of the System.Text.Decoder class to convert two byte arrays to a character array, where one character's bytes span multiple byte arrays. This demonstrates how to use a System.Text.Decoder in streaming-like situations.

using System;
using System.Text;

public class DecoderExample 
{
   public static void Main() 
   {
      // These bytes in UTF-8 correspond to 3 different
      // Unicode characters - A (U+0041), # (U+0023),
      // and the biohazard symbol (U+2623). Note the 
      // biohazard symbol requires 3 bytes in UTF-8 
      // (in hex, e2, 98, a3). Decoders store state across
      // multiple calls to GetChars, handling the case 
      // when one char spans multiple byte arrays.

      byte[] bytes1 = { 0x41, 0x23, 0xe2 };
      byte[] bytes2 = { 0x98, 0xa3 };
      char[] chars = new char[3]; 

      Decoder d = Encoding.UTF8.GetDecoder();
      int charLen = d.GetChars(bytes1, 0, bytes1.Length,
                               chars, 0);
      // charLen is 2.

      charLen += d.GetChars(bytes2, 0, bytes2.Length,
                            chars, charLen);
      // charLen is now 3. 

      foreach(char c in chars) 
         Console.Write("U+{0:x} ", (ushort)c);
   }
}

The output is