System.Text.Decoder Class

Converts a sequence of encoded bytes into a set of characters.

See Also: Decoder Members


public abstract class Decoder


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.


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 Decoder.Reset to clear the internal state of the Decoder object.

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.

Thread Safety

All public static members of this type are safe for multithreaded operations. No instance members are guaranteed to be thread safe.


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.

C# Example

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

U+41 U+23 U+2623


Namespace: System.Text
Assembly: mscorlib (in mscorlib.dll)
Assembly Versions: 1.0.5000.0,,