System.Text.Decoder Class

public abstract class Decoder

Base Types

Object
  Decoder

Assembly

mscorlib

Library

BCL

Summary

Converts blocks of bytes into blocks of characters, maintaining state across successive calls for reading from a Stream.

Description

[Note: Following instantiation of a decoder, sequential blocks of bytes are converted into blocks of characters through calls to the System.Text.Decoder.GetChars(System.Byte[],System.Int32,System.Int32,System.Char[],System.Int32) method. The decoder maintains state between the conversions, allowing it to correctly decode a character whose bytes span multiple blocks. This greatly assists decoding streams of bytes into characters. An instance of a specific implementation of the Decoder class is typically obtained through a call to the System.Text.Encoding.GetDecoder method of a Encoding object.]

Example

The following example demonstrates using the UTF8Encoding implementation of the 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 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

U+41 U+23 U+2623

See Also

System.Text Namespace

Members

Decoder Constructors

Decoder Constructor

Decoder Methods

Decoder.GetCharCount Method
Decoder.GetChars Method

Constructs a new instance of the Decoder class.

Description

This constructor is called only by classes that inherit from the Decoder class.

See Also

System.Text.Decoder Class, System.Text Namespace

bytes

A Byte array to decode.

index

A Int32 that specifies the first index in bytes to decode.

count

A Int32 that specifies the number elements in bytes to decode.

Return Value

A Int32 containing the number of characters the next call to System.Text.Decoder.GetChars(System.Byte[],System.Int32,System.Int32,System.Char[],System.Int32) will produce if presented with the specified range of bytes .

[Note: This value takes into account the state in which the current instance was left following the last call to System.Text.Decoder.GetChars(System.Byte[],System.Int32,System.Int32,System.Char[],System.Int32). This contrasts with System.Text.Encoding.GetChars(System.Byte[]), which does not maintain state information across subsequent calls.]

Exceptions

Exception Type	Condition
ArgumentNullException	bytes is null .
ArgumentOutOfRangeException	index < 0. -or- count < 0. -or- index and count do not specify a valid range in bytes (i.e. (index + count) > bytes.Length).

Description

[Behaviors: As described above.]

[Overrides: Override this method to return the appropriate value for a particular encoding.]

[Usage: Use this method to determine the appropriate size of a buffer to contain the decoded values.]

See Also

System.Text.Decoder Class, System.Text Namespace

bytes

A Byte array to decode.

byteIndex

A Int32 that specifies the first index of bytes from which to decode.

byteCount

A Int32 that specifies the number elements in bytes to decode.

chars

A Char array of characters to decode into.

charIndex

A Int32 that specifies the first index of chars to store the decoded bytes.

Return Value

A Int32 containing the number of characters decoded into chars for a particular encoding.

Exceptions

Exception Type	Condition
ArgumentException	chars does not contain sufficient space to store the decoded characters.
ArgumentNullException	bytes is null . -or- chars is null .
ArgumentOutOfRangeException	byteIndex < 0. -or- byteCount < 0. -or- charIndex < 0. -or- byteIndex and byteCount do not specify a valid range in bytes (i.e. (byteIndex + byteCount ) > bytes.Length). -or- charIndex > chars.Length.

Description

[Note: System.Text.Decoder.GetCharCount(System.Byte[],System.Int32,System.Int32) can be used to determine the exact number of characters that will be produced for a specified range of bytes. Alternatively, System.Text.Encoding.GetMaxCharCount(System.Int32) of the Encoding object that produced the current instance can be used to determine the maximum number of characters that may be produced for a specified number of bytes, regardless of the actual byte values.]

[Behaviors: As described above.]

[Overrides: Override this method to decode the values of a Byte array for a particular encoding.]

[Usage: Use this method to decode the elements of a byte array for a particular encoding.]

See Also

System.Text.Decoder Class, System.Text Namespace