Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

Encoder Class

Converts blocks of characters into encoded blocks of bytes.

For a list of all members of this type, see Encoder Members.

System.Object
   System.Text.Encoder

[Visual Basic]
<Serializable>
MustInherit Public Class Encoder
[C#]
[Serializable]
public abstract class Encoder
[C++]
[Serializable]
public __gc __abstract class Encoder
[JScript]
public
   Serializable
abstract class Encoder

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.

Remarks

This is an abstract class. You must implement and override all its methods in a derived class.

An implementation of this class converts blocks of characters into blocks of encoded bytes through successive calls of the GetBytes method. This class maintains state information between successive calls of GetBytes, enabling it to encode a character into a sequence of bytes, such as surrogate pairs, that span adjacent blocks. For example, this is useful for encoding a character into a surrogate pair.

The GetByteCount method calculates the number of bytes required to encode a specified block of characters.

An instance of Encoder is typically obtained by calling the Encoding.GetEncoder method of a class derived from the Encoding class.

Example

[Visual Basic, C#, C++] The following example demonstrates how to convert an array of Unicode characters into blocks of bytes using a specified encoding. For comparison, the array of characters is first encoded using a UTF7Encoding. Next, the array of characters is encoded using an Encoder. Using the GetByteCount method and setting the flush parameter to false, causes the encoder to maintain state between calls and not store extra bytes in the output.

[Visual Basic] 
Imports System
Imports System.Text
Imports Microsoft.VisualBasic
Imports Microsoft.VisualBasic.Strings

Class EncoderTest
    
    Public Shared Sub Main()
        ' 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.UTF7
        Console.WriteLine( _
            "Using Encoding" & _
            ControlChars.NewLine & _
            "--------------" _
        )
        
        ' Encode complete array for comparison.
        Dim allCharactersFromEncoding As Byte() = encoding.GetBytes(chars)
        Console.WriteLine("All characters encoded:")
        ShowArray(allCharactersFromEncoding)
        
        ' Encode characters, one-by-one.
        ' The Encoding object will NOT maintain state between calls.
        Dim firstchar As Byte() = encoding.GetBytes(chars, 0, 1)
        Console.WriteLine("First character:")
        ShowArray(firstchar)
        
        Dim secondchar As Byte() = encoding.GetBytes(chars, 1, 1)
        Console.WriteLine("Second character:")
        ShowArray(secondchar)
        
        Dim thirdchar As Byte() = encoding.GetBytes(chars, 2, 1)
        Console.WriteLine("Third character:")
        ShowArray(thirdchar)
        
        Dim fourthchar As Byte() = encoding.GetBytes(chars, 3, 1)
        Console.WriteLine("Fourth character:")
        ShowArray(fourthchar)
        
        
        ' Now, encode characters using an Encoder object.
        Dim encoder As Encoder = encoding.GetEncoder()
        Console.WriteLine( _
            "Using Encoder" & _
            ControlChars.NewLine & _
            "-------------" _
        )
        
        ' Encode complete array for comparison.
        Dim allCharactersFromEncoder( _
            encoder.GetByteCount(chars, 0, chars.Length, True) _
        ) As Byte
        encoder.GetBytes(chars, 0, chars.Length, allCharactersFromEncoder, 0, True)
        Console.WriteLine("All characters encoded:")
        ShowArray(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) _
        ) As Byte
        encoder.GetBytes(chars, 0, 1, firstcharNoFlush, 0, bFlushState)
        Console.WriteLine("First character:")
        ShowArray(firstcharNoFlush)
        
        Dim secondcharNoFlush( _
            encoder.GetByteCount(chars, 1, 1, bFlushState) _
        ) As Byte
        encoder.GetBytes(chars, 1, 1, secondcharNoFlush, 0, bFlushState)
        Console.WriteLine("Second character:")
        ShowArray(secondcharNoFlush)
        
        Dim thirdcharNoFlush( _
            encoder.GetByteCount(chars, 2, 1, bFlushState) _
        ) As Byte
        encoder.GetBytes(chars, 2, 1, thirdcharNoFlush, 0, bFlushState)
        Console.WriteLine("Third character:")
        ShowArray(thirdcharNoFlush)
        
        ' Must flush state on last call to GetBytes().
        bFlushState = True
        
        Dim fourthcharNoFlush( _
            encoder.GetByteCount(chars, 3, 1, bFlushState) _
        ) As Byte
        encoder.GetBytes(chars, 3, 1, fourthcharNoFlush, 0, bFlushState)
        Console.WriteLine("Fourth character:")
        ShowArray(fourthcharNoFlush)
    End Sub 'Main
    
    
    Public Shared Sub ShowArray(theArray As Array)
        Dim o As Object
        For Each o In  theArray
            Console.Write("[{0}]", o)
        Next o
        Console.WriteLine(ControlChars.NewLine)
    End Sub 'ShowArray
End Class 'EncoderTest

[C#] 
using System;
using System.Text;

class EncoderTest {
    public static void Main() {
        // The characters to encode.
        Char[] chars = new Char[] {
            '\u0023', // #
            '\u0025', // %
            '\u03a0', // Pi
            '\u03a3'  // Sigma
        };

        // Encode characters using an Encoding object.
        Encoding encoding = Encoding.UTF7;
        Console.WriteLine("Using Encoding\n--------------");

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

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

        Byte[] secondchar = encoding.GetBytes(chars, 1, 1);
        Console.WriteLine("Second character:");
        ShowArray(secondchar);

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

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


        // Now, encode characters using an Encoder object.
        Encoder encoder = encoding.GetEncoder();
        Console.WriteLine("Using Encoder\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);
        Console.WriteLine("All characters encoded:");
        ShowArray(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);
        Console.WriteLine("First character:");
        ShowArray(firstcharNoFlush);

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

        Byte[] thirdcharNoFlush = new Byte[encoder.GetByteCount(chars, 2, 1, bFlushState)];
        encoder.GetBytes(chars, 2, 1, thirdcharNoFlush, 0, bFlushState);
        Console.WriteLine("Third character:");
        ShowArray(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);
        Console.WriteLine("Fourth character:");
        ShowArray(fourthcharNoFlush);
    }

    public static void ShowArray(Array theArray) {
        foreach (Object o in theArray) {
            Console.Write("[{0}]", o);
        }
        Console.WriteLine("\n");
    }
}

[C++] 
#using <mscorlib.dll>
using namespace System;
using namespace System::Text;
using namespace System::Collections;

void ShowArray(Array * theArray)
{
   IEnumerator* myEnum = theArray->GetEnumerator();
   while (myEnum->MoveNext())
   {
      Object* o = __try_cast<Object*>(myEnum->Current);
      Console::Write(S"[{0}]", o);
   }
   Console::WriteLine(S"\n");
}

int main()
{
   // The characters to encode.
   Char chars[] =
   {
      L'\u03a0', // Pi
      L'\u03a3',  // Sigma
      L'\u03a6',
      L'\u03a9',
   };

   // Encode characters using an Encoding Object*.
   Encoding * encoding = Encoding::UTF7;
   Console::WriteLine(S"Using Encoding\n--------------");

   // Encode complete array for comparison.
   Byte allCharactersFromEncoding[] = encoding -> GetBytes(chars);
   Console::WriteLine(S"All characters encoded:");
   ShowArray(allCharactersFromEncoding);

   // Encode characters, one-by-one.
   // The Encoding Object* will NOT maintain state between calls.
   Byte firstchar[] = encoding -> GetBytes(chars, 0, 1);
   Console::WriteLine(S"First character:");
   ShowArray(firstchar);

   Byte secondchar[] = encoding -> GetBytes(chars, 1, 1);
   Console::WriteLine(S"Second character:");
   ShowArray(secondchar);

   Byte thirdchar[] = encoding -> GetBytes(chars, 2, 1);
   Console::WriteLine(S"Third character:");
   ShowArray(thirdchar);

   Byte fourthchar[] = encoding -> GetBytes(chars, 3, 1);
   Console::WriteLine(S"Fourth character:");
   ShowArray(fourthchar);

   // Now, encode characters using an Encoder Object*.
   Encoder * encoder = encoding -> GetEncoder();
   Console::WriteLine(S"Using Encoder\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);
   Console::WriteLine(S"All characters encoded:");
   ShowArray(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);
   Console::WriteLine(S"First character:");
   ShowArray(firstcharNoFlush);

   Byte secondcharNoFlush[] = new Byte[encoder -> GetByteCount(chars, 1, 1, bFlushState)];
   encoder -> GetBytes(chars, 1, 1, secondcharNoFlush, 0, bFlushState);
   Console::WriteLine(S"Second character:");
   ShowArray(secondcharNoFlush);

   Byte thirdcharNoFlush[] = new Byte[encoder -> GetByteCount(chars, 2, 1, bFlushState)];
   encoder -> GetBytes(chars, 2, 1, thirdcharNoFlush, 0, bFlushState);
   Console::WriteLine(S"Third character:");
   ShowArray(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);
   Console::WriteLine(S"Fourth character:");
   ShowArray(fourthcharNoFlush);
}

[JScript] No example is available for JScript. To view a Visual Basic, C#, or C++ example, click the Language Filter button Language Filter in the upper-left corner of the page.

Requirements

Namespace: System.Text

Platforms: Windows 98, Windows NT 4.0, Windows Millennium Edition, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 family, .NET Compact Framework

Assembly: Mscorlib (in Mscorlib.dll)

See Also

Encoder Members | System.Text Namespace | Encoding

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft