Article
11/18/2011

Encoder Class

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

Converts a set of characters into a sequence of bytes.

Inheritance Hierarchy

System.Object
System.Text.Encoder

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

Syntax

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

[ComVisibleAttribute(true)]
public abstract class Encoder

The Encoder type exposes the following members.

Constructors

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

Top

Methods

	Name	Description
	Convert(Char, Int32, Byte, Int32, Boolean, Int32%, Int32%, Boolean%)	Security Critical. Converts a buffer of Unicode characters to an encoded byte sequence and stores the result in another buffer.
	Convert(array<Char[], Int32, Int32, array<Byte[], Int32, Int32, Boolean, Int32%, Int32%, Boolean%)	Converts an array of Unicode characters to an encoded byte sequence and stores the result in an array of bytes.
	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.)
	GetByteCount(Char*, Int32, Boolean)	Security Critical. When overridden in a derived class, calculates the number of bytes produced by encoding a set of characters starting at the specified character pointer. A parameter indicates whether to clear the internal state of the encoder after the calculation.
	GetByteCount(array<Char[], Int32, Int32, Boolean)	When overridden in a derived class, calculates the number of bytes produced by encoding a set of characters from the specified character array. A parameter indicates whether to clear the internal state of the encoder after the calculation.
	GetBytes(Char, Int32, Byte, Int32, Boolean)	Security Critical. When overridden in a derived class, encodes a set of characters starting at the specified character pointer and any characters in the internal buffer into a sequence of bytes that are stored starting at the specified byte pointer. A parameter indicates whether to clear the internal state of the encoder after the conversion.
	GetBytes(array<Char[], Int32, Int32, array<Byte[], Int32, Boolean)	When overridden in a derived class, encodes a set of characters from the specified character array and any characters in the internal buffer into the specified byte array. A parameter indicates whether to clear the internal state of the encoder 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.)
	ToString	Returns a string that represents the current object. (Inherited from Object.)

Top

Remarks

To obtain an instance of an implementation of the Encoder class, call the GetEncoder 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 GetByteCount method determines how many bytes result in encoding a set of Unicode characters, and the GetBytes method performs the actual encoding. The Encoder class includes Several overloads of both methods.

An Encoder object maintains state information between successive calls to the GetBytes or Convert methods so that it can correctly encode character sequences that span blocks. The Encoder also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. For example, a data block might end with an unmatched high surrogate, and the matching low surrogate might be in the next data block.

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.

Notes to Inheritors

When your application inherits from this class, it must override all the members.

Examples

The following example demonstrates how to convert an array of Unicode characters into blocks of UTF8-encoded bytes.

Imports System.Text

Class Example
   Public Shared Sub Demo(ByVal outputBlock As System.Windows.Controls.TextBlock)
      ' Unicode characters.
      ' ChrW(35)  = #
      ' ChrW(37)  = %
      ' ChrW(928) = Pi
      ' ChrW(931) = Sigma
      Dim chars() As Char = {ChrW(35), ChrW(37), ChrW(928), ChrW(931)}

      ' Encode characters using an Encoding object.
      Dim encoding As Encoding = encoding.UTF8
      outputBlock.Text &= _
          "Using Encoding" & vbCrLf & _
          "--------------" & vbCrLf

      ' Encode complete array for comparison.
      Dim allCharactersFromEncoding As Byte() = encoding.GetBytes(chars)
      outputBlock.Text &= "All characters encoded: " 
      ShowArray(outputBlock, allCharactersFromEncoding)

      ' Encode characters, one-by-one.
      ' The Encoding object will NOT maintain state between calls.
      Dim firstchar As Byte() = encoding.GetBytes(chars, 0, 1)
      outputBlock.Text &= "First character: " 
      ShowArray(outputBlock, firstchar)

      Dim secondchar As Byte() = encoding.GetBytes(chars, 1, 1)
      outputBlock.Text &= "Second character: " 
      ShowArray(outputBlock, secondchar)

      Dim thirdchar As Byte() = encoding.GetBytes(chars, 2, 1)
      outputBlock.Text &= "Third character: " 
      ShowArray(outputBlock, thirdchar)

      Dim fourthchar As Byte() = encoding.GetBytes(chars, 3, 1)
      outputBlock.Text &= "Fourth character: "
      ShowArray(outputBlock, fourthchar)


      ' Now, encode characters using an Encoder object.
      Dim encoder As Encoder = encoding.GetEncoder()
      outputBlock.Text &= vbCrLf & _
          "Using Encoder" & vbCrLf & _
          "-------------" & vbCrLf

      ' Encode complete array for comparison.
      Dim allCharactersFromEncoder( _
          encoder.GetByteCount(chars, 0, chars.Length, True) - 1) As Byte
      encoder.GetBytes(chars, 0, chars.Length, allCharactersFromEncoder, 0, True)
      outputBlock.Text &= "All characters encoded: "
      ShowArray(outputBlock, allCharactersFromEncoder)

      ' Do not flush state; i.e. maintain state between calls.
      Dim bFlushState As Boolean = False

      ' Encode characters one-by-one.
      ' By maintaining state, the Encoder will not store extra bytes in the output.
      Dim firstcharNoFlush( _
          encoder.GetByteCount(chars, 0, 1, bFlushState) -1 ) As Byte
      encoder.GetBytes(chars, 0, 1, firstcharNoFlush, 0, bFlushState)
      outputBlock.Text &= "First character: "
      ShowArray(outputBlock, firstcharNoFlush)

      Dim secondcharNoFlush( _
          encoder.GetByteCount(chars, 1, 1, bFlushState) -1 ) As Byte
      encoder.GetBytes(chars, 1, 1, secondcharNoFlush, 0, bFlushState)
      outputBlock.Text &= "Second character: " 
      ShowArray(outputBlock, secondcharNoFlush)

      Dim thirdcharNoFlush( _
          encoder.GetByteCount(chars, 2, 1, bFlushState) - 1) As Byte
      encoder.GetBytes(chars, 2, 1, thirdcharNoFlush, 0, bFlushState)
      outputBlock.Text &= "Third character: "
      ShowArray(outputBlock, thirdcharNoFlush)

      ' Must flush state on last call to GetBytes().
      bFlushState = True

      Dim fourthcharNoFlush( _
          encoder.GetByteCount(chars, 3, 1, bFlushState) -1 ) As Byte
      encoder.GetBytes(chars, 3, 1, fourthcharNoFlush, 0, bFlushState)
      outputBlock.Text &= "Fourth character: "
      ShowArray(outputBlock, fourthcharNoFlush)
   End Sub 

   Public Shared Sub ShowArray(ByVal outputBlock As System.Windows.Controls.TextBlock, _
                               ByVal theArray As Array)
      Dim o As Object
      For Each o In theArray
         outputBlock.Text &= String.Format("[{0}] ", o)
      Next o
      outputBlock.Text &= vbCrLf
   End Sub 
End Class 
' The example displays the following output:
'       Using Encoding
'       --------------
'       All characters encoded: [35] [37] [206] [160] [206] [163] 
'       First character: [35] 
'       Second character: [37] 
'       Third character: [206] [160] 
'       Fourth character: [206] [163] 
'       
'       Using Encoder
'       -------------
'       All characters encoded: [35] [37] [206] [160] [206] [163] 
'       First character: [35] 
'       Second character: [37] 
'       Third character: [206] [160] 
'       Fourth character: [206] [163]

using System;
using System.Text;

class Example
{
   public static void Demo(System.Windows.Controls.TextBlock outputBlock)
   {
      // The characters to encode.
      Char[] chars = new Char[] {
            '\u0023', // #
            '\u0025', // %
            '\u03a0', // Pi
            '\u03a3'  // Sigma
        };

      // Encode characters using an Encoding object.
      Encoding encoding = Encoding.UTF8;
      outputBlock.Text += "Using Encoding\n--------------\n";

      // Encode complete array for comparison.
      Byte[] allCharactersFromEncoding = encoding.GetBytes(chars);
      outputBlock.Text += "All characters encoded: ";
      ShowArray(outputBlock, allCharactersFromEncoding);

      // Encode characters, one-by-one.
      // The Encoding object will NOT maintain state between calls.
      Byte[] firstchar = encoding.GetBytes(chars, 0, 1);
      outputBlock.Text += "First character: ";
      ShowArray(outputBlock, firstchar);

      Byte[] secondchar = encoding.GetBytes(chars, 1, 1);
      outputBlock.Text += "Second character: ";
      ShowArray(outputBlock, secondchar);

      Byte[] thirdchar = encoding.GetBytes(chars, 2, 1);
      outputBlock.Text += "Third character: ";
      ShowArray(outputBlock, thirdchar);

      Byte[] fourthchar = encoding.GetBytes(chars, 3, 1);
      outputBlock.Text += "Fourth character: ";
      ShowArray(outputBlock, fourthchar);

      // Now, encode characters using an Encoder object.
      Encoder encoder = encoding.GetEncoder();
      outputBlock.Text += "\nUsing Encoder\n-------------\n";

      // Encode complete array for comparison.
      Byte[] allCharactersFromEncoder = new Byte[encoder.GetByteCount(chars, 0, chars.Length, true)];
      encoder.GetBytes(chars, 0, chars.Length, allCharactersFromEncoder, 0, true);
      outputBlock.Text += "All characters encoded: ";
      ShowArray(outputBlock, allCharactersFromEncoder);

      // Do not flush state; i.e. maintain state between calls.
      bool bFlushState = false;

      // Encode characters one-by-one.
      // By maintaining state, the Encoder will not store extra bytes in the output.
      Byte[] firstcharNoFlush = new Byte[encoder.GetByteCount(chars, 0, 1, bFlushState)];
      encoder.GetBytes(chars, 0, 1, firstcharNoFlush, 0, bFlushState);
      outputBlock.Text += "First character: ";
      ShowArray(outputBlock, firstcharNoFlush);

      Byte[] secondcharNoFlush = new Byte[encoder.GetByteCount(chars, 1, 1, bFlushState)];
      encoder.GetBytes(chars, 1, 1, secondcharNoFlush, 0, bFlushState);
      outputBlock.Text += "Second character: ";
      ShowArray(outputBlock, secondcharNoFlush);

      Byte[] thirdcharNoFlush = new Byte[encoder.GetByteCount(chars, 2, 1, bFlushState)];
      encoder.GetBytes(chars, 2, 1, thirdcharNoFlush, 0, bFlushState);
      outputBlock.Text += "Third character: ";
      ShowArray(outputBlock, thirdcharNoFlush);

      // Must flush state on last call to GetBytes().
      bFlushState = true;

      Byte[] fourthcharNoFlush = new Byte[encoder.GetByteCount(chars, 3, 1, bFlushState)];
      encoder.GetBytes(chars, 3, 1, fourthcharNoFlush, 0, bFlushState);
      outputBlock.Text += "Fourth character: ";
      ShowArray(outputBlock, fourthcharNoFlush);
   }

   public static void ShowArray(System.Windows.Controls.TextBlock outputBlock, Array theArray)
   {
      foreach (Object o in theArray)
      {
         outputBlock.Text += String.Format("[{0}] ", o);
      }
      outputBlock.Text += "\n";
   }
}
// The example displays the following output;
//       Using Encoding
//       --------------
//       All characters encoded: [35] [37] [206] [160] [206] [163] 
//       First character: [35] 
//       Second character: [37] 
//       Third character: [206] [160] 
//       Fourth character: [206] [163] 
//       
//       Using Encoder
//       -------------
//       All characters encoded: [35] [37] [206] [160] [206] [163] 
//       First character: [35] 
//       Second character: [37] 
//       Third character: [206] [160] 
//       Fourth character: [206] [163]

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.