Articolo
11/18/2011

Decoder Class

Microsoft Silverlight will reach end of support after October 2021. Learn more.

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

Inheritance Hierarchy

System.Object
System.Text.Decoder

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

Syntax

'Declaration
<ComVisibleAttribute(True)> _
Public MustInherit Class Decoder

[ComVisibleAttribute(true)]
public abstract class Decoder

The Decoder type exposes the following members.

Constructors

	Name	Description
	Decoder	Initializes a new instance of the Decoder class.

Top

Methods

	Name	Description
	Convert(Byte, Int32, Char, Int32, Boolean, Int32%, Int32%, Boolean%)	Security Critical. Converts a buffer of encoded bytes to UTF-16 encoded characters and stores the result in another buffer.
	Convert(array<Byte[], Int32, Int32, array<Char[], Int32, Int32, Boolean, Int32%, Int32%, Boolean%)	Converts an array of encoded bytes to Unicode characters and stores the result in a byte array.
	Equals(Object)	Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
	Finalize	Allows an object to try to free resources and perform other cleanup operations before the Object is reclaimed by garbage collection. (Inherited from Object.)
	GetCharCount(array<Byte[], Int32, Int32)	When overridden in a derived class, calculates the number of characters produced by decoding a sequence of bytes from the specified byte array.
	GetCharCount(Byte*, Int32, Boolean)	Security Critical. When overridden in a derived class, calculates the number of characters produced by decoding a sequence of bytes starting at the specified byte pointer. A parameter indicates whether to clear the internal state of the decoder after the calculation.
	GetCharCount(array<Byte[], Int32, Int32, Boolean)	When overridden in a derived class, calculates the number of characters produced by decoding a sequence of bytes from the specified byte array. A parameter indicates whether to clear the internal state of the decoder after the calculation.
	GetChars(array<Byte[], Int32, Int32, array<Char[], Int32)	When overridden in a derived class, decodes a sequence of bytes from the specified byte array and any bytes in the internal buffer into the specified character array.
	GetChars(Byte, Int32, Char, Int32, Boolean)	Security Critical. When overridden in a derived class, decodes a sequence of bytes starting at the specified byte pointer and any bytes in the internal buffer into a set of characters that are stored starting at the specified character pointer. A parameter indicates whether to clear the internal state of the decoder after the conversion.
	GetChars(array<Byte[], Int32, Int32, array<Char[], Int32, Boolean)	When overridden in a derived class, decodes a sequence of bytes from the specified byte array and any bytes in the internal buffer into the specified character array. A parameter indicates whether to clear the internal state of the decoder after the conversion.
	GetHashCode	Serves as a hash function for a particular type. (Inherited from Object.)
	GetType	Gets the Type of the current instance. (Inherited from Object.)
	MemberwiseClone	Creates a shallow copy of the current Object. (Inherited from Object.)
	Reset	When overridden in a derived class, sets the decoder back to its initial state.
	ToString	Returns a string that represents the current object. (Inherited from Object.)

Top

Remarks

To obtain an instance of an implementation of the Decoder class, call the GetDecoder method of an Encoding implementation. There are two such implementations available in the .NET Framework for Silverlight: UTF8Encoding and UnicodeEncoding. The UnicodeEncoding implementation supports both big-endian and little-endian Unicode.

The GetCharCount method determines how many characters result in decoding a sequence of bytes, and the GetChars method performs the actual decoding. The Decoder class includes several overloads of both methods.

A Decoder object maintains state information between successive calls to the GetChars or Convert methods so it can correctly decode byte sequences that span blocks. A Decoder object also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation.

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 Decoder object.

Notes to Inheritors

Derived classes must override all the members of the Decoder class.

Examples

The following example demonstrates the use of a Decoder to convert two different byte arrays into a character array. One of the character's bytes spans the arrays.

Imports System.Text

Public Class Example
   Public Shared Sub Demo(ByVal outputBlock As System.Windows.Controls.TextBlock)
      ' 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 d As Decoder = Encoding.UTF8.GetDecoder()

      Dim arraySize As Integer = d.GetCharCount(bytes1, 0, bytes1.Length)
      arraySize += d.GetCharCount(bytes2, 0, bytes2.Length)

      Dim chars(arraySize - 1) As Char

      Dim charLen As Integer = d.GetChars(bytes1, 0, bytes1.Length, chars, 0)
      ' Use charLen to determine where new characters are written.
      charLen += d.GetChars(bytes2, 0, bytes2.Length, chars, charLen)

      Dim output As New String(chars, 0, charLen)
      outputBlock.Text += String.Format("'{0}'\n", output)
   End Sub
End Class

using System;
using System.Text;
public class Example
{
   public static void Demo(System.Windows.Controls.TextBlock outputBlock)
   {
      // 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 };

      Decoder d = Encoding.UTF8.GetDecoder();

      int arraySize = d.GetCharCount(bytes1, 0, bytes1.Length);
      arraySize += d.GetCharCount(bytes2, 0, bytes2.Length);  

      char[] chars = new char[arraySize];

      int charLen = d.GetChars(bytes1, 0, bytes1.Length, chars, 0);
      // Use charLen to determine where new characters are written.
      charLen += d.GetChars(bytes2, 0, bytes2.Length, chars, charLen);

      string output = new string(chars, 0, charLen);
      outputBlock.Text += String.Format("'{0}'\n", output);
   }
}

Version Information

Silverlight

Supported in: 5, 4, 3

Silverlight for Windows Phone

Supported in: Windows Phone OS 7.1, Windows Phone OS 7.0

XNA Framework

Supported in: Xbox 360, Windows Phone OS 7.0

Platforms

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.

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.

Condividi tramite