Decoder Class (System.Text)

Collapse All

Language Filter

This page is specific to

Microsoft Visual Studio 2005/.NET Framework 2.0

Other versions are also available for the following:

.NET Framework Class Library

Decoder Class

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

Namespace: System.Text
Assembly: mscorlib (in mscorlib.dll)

Syntax

Visual Basic (Declaration)

<SerializableAttribute> _
<ComVisibleAttribute(True)> _
Public MustInherit Class Decoder

Visual Basic (Usage)

Dim instance As Decoder

[SerializableAttribute] 
[ComVisibleAttribute(true)] 
public abstract class Decoder

C++

[SerializableAttribute] 
[ComVisibleAttribute(true)] 
public ref class Decoder abstract

/** @attribute SerializableAttribute() */ 
/** @attribute ComVisibleAttribute(true) */ 
public abstract class Decoder

JScript

SerializableAttribute 
ComVisibleAttribute(true) 
public abstract class Decoder

Remarks

Encoding is the process of transforming a set of characters into a sequence of bytes. Decoding is the reverse; it is the process of transforming a sequence of encoded bytes into a set of characters.

A Decoder maintains state information between successive calls to GetChars so it can correctly decode byte sequences that span blocks. The Decoder also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. 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.

The GetCharCount method determines how many characters result in decoding a sequence of bytes, and the GetChars method performs the actual decoding.

To obtain an instance of an implementation of this class, use the GetDecoder method of an Encoding implementation.

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.

Notes to Inheritors When you inherit from this class, you must override all the members.

Example

The following code example demonstrates using a Decoder to convert two different byte arrays into a character array. One of the character's bytes spans the arrays. This is similar to what a System.IO.StreamReader does internally when reading a stream.

Visual Basic

Imports System
Imports System.Text

Public Class dec
    
    Public Shared Sub Main()
        ' These bytes in UTF-8 correspond to 3 different Unicode
        ' characters: space (U+0020), # (U+0023), and the biohazard
        ' symbol (U+2623).  Note the biohazard symbol requires 3 bytes
        ' in UTF-8 (hexadecimal e2, 98, a3).  Decoders store state across
        ' multiple calls to GetChars, handling the case when one char
        ' is in multiple byte arrays.
        Dim bytes1 As Byte() =  {&H20, &H23, &HE2}
        Dim bytes2 As Byte() =  {&H98, &HA3}
        Dim chars(3) As Char
        
        Dim d As Decoder = Encoding.UTF8.GetDecoder()
        Dim charLen As Integer = d.GetChars(bytes1, 0, bytes1.Length, chars, 0)
        ' The value of charLen should be 2 now.
        charLen += d.GetChars(bytes2, 0, bytes2.Length, chars, charLen)
        Dim c As Char
        For Each c In  chars
            Console.Write("U+{0:X4}  ", Convert.ToUInt16(c) )
        Next c
    End Sub
End Class

using System;
using System.Text;
public class dec
{
    public static void Main()
    {
        // These bytes in UTF-8 correspond to 3 different Unicode
        // characters: space (U+0020), # (U+0023), and the biohazard
        // symbol (U+2623).  Note the biohazard symbol requires 3 bytes
        // in UTF-8 (hexadecimal e2, 98, a3).  Decoders store state across
        // multiple calls to GetChars, handling the case when one char
        // is in multiple byte arrays.
        byte[] bytes1 = { 0x20, 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);
        // The value of charLen should be 2 now.
        charLen += d.GetChars(bytes2, 0, bytes2.Length, chars, charLen);
        foreach(char c in chars)
            Console.Write("U+{0:X4}  ", (ushort)c);
    }
}

C++

using namespace System;
using namespace System::Text;
int main()
{
   
   // These bytes in UTF-8 correspond to 3 different Unicode
   // characters: space (U+0020), # (U+0023), and the biohazard
   // symbol (U+2623).  Note the biohazard symbol requires 3 bytes
   // in UTF-8 (hexadecimal e2, 98, a3).  Decoders store state across
   // multiple calls to GetChars, handling the case when one char
   // is in multiple byte arrays.
   array<Byte>^bytes1 = {0x20,0x23,0xe2};
   array<Byte>^bytes2 = {0x98,0xa3};
   array<Char>^chars = gcnew array<Char>(3);
   Decoder^ d = Encoding::UTF8->GetDecoder();
   int charLen = d->GetChars( bytes1, 0, bytes1->Length, chars, 0 );
   
   // The value of charLen should be 2 now.
   charLen += d->GetChars( bytes2, 0, bytes2->Length, chars, charLen );
   for ( UInt16 index(0); index < chars->Length; ++index )
   {
      Console::Write( "U+{0:X4}  ", static_cast<UInt16>(chars[ index ]) );

   }
}

import System.*;
import System.Text.*;

public class Dec
{
    public static void main(String[] args)
    {
        // These bytes in UTF-8 correspond to 3 different Unicode
        // characters: space (U+0020), # (U+0023), and the biohazard
        // symbol (U+2623).  Note the biohazard symbol requires 3 bytes
        // in UTF-8 (hexadecimal e2, 98, a3).  Decoders store state across
        // multiple calls to GetChars, handling the case when one char
        // is in multiple byte arrays.
        ubyte bytes1[] =  { 0x20, 0x23, 0xE2 };
        ubyte bytes2[] =  { 0x98, 0xA3 };
        char chars[] = new char[3];
        
        Decoder d = Encoding.get_UTF8().GetDecoder();
        int charLen = d.GetChars(bytes1, 0, bytes1.length, chars, 0);
        
        // The value of charLen should be 2 now.
        charLen += d.GetChars(bytes2, 0, bytes2.length, chars, charLen);

        for (int iCtr = 0; iCtr < chars.length; iCtr++) {
            char c = chars[iCtr];
            Console.Write("U+{0}  ",((Int16)c).ToString("X4"));
        }
    } //main
} //Dec

Inheritance Hierarchy

System.Object
System.Text.Decoder

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Platforms

Windows 98, Windows 2000 SP4, Windows CE, Windows Millennium Edition, Windows Mobile for Pocket PC, Windows Mobile for Smartphone, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see System Requirements.

Version Information