This documentation is archived and is not being maintained.

UTF8Encoding.GetEncoder Method

Obtains an encoder that can convert a sequence of Unicode characters into a UTF-8 encoded sequence of bytes.

[Visual Basic]
Overrides Public Function GetEncoder() As Encoder
[C#]
public override Encoder GetEncoder();
[C++]
public: Encoder* GetEncoder();
[JScript]
public override function GetEncoder() : Encoder;

Return Value

An Encoder.

Remarks

The Encoder.GetBytes method converts adjacent blocks of characters into adjacent blocks of bytes, in a manner similar to the GetBytes method. However, an Encoder maintains state information between calls so it can correctly encode characters that span blocks.

If this UTF8Encoding is constructed with error detection turned on (that is, the throwOnInvalidBytes parameter is true), the Encoder returned by this method also has error detection turned on.

The GetEncoder method obtains an Encoder that preserves trailing characters (such as a high-surrogate), at the end of a block and uses the trailing Unicode characters in the next encoding operation. GetDecoder and GetEncoder are useful for network transmission and file operations since those operations often deal with blocks of data instead of a complete stream.

Example

[Visual Basic, C#, C++] The following example demonstrates how to use the GetEncoder method to obtain an encoder to convert a sequence of characters in chars into a UTF-8 encoded sequence of bytes in bytes.

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

Class UTF8EncodingExample
    
    Public Shared Sub Main()
        'Characters:
        ' ChrW(97) = a
        ' ChrW(98) = b
        ' ChrW(99) = c
        ' ChrW(768) = `
        ' ChrW(41120) = valid unicode code point, but not a character
        Dim chars() As Char = {ChrW(97), ChrW(98), ChrW(99), ChrW(768), ChrW(41120)}
        Dim bytes() As Byte
        
        Dim utf8Encoder As Encoder = Encoding.UTF8.GetEncoder()
        
        Dim byteCount As Integer = utf8Encoder.GetByteCount(chars, 2, 3, True)
        bytes = New Byte(byteCount - 1) {}
        Dim bytesEncodedCount As Integer = utf8Encoder.GetBytes( _
            chars, 2, 3, bytes, 0, True _
        )
        
        Console.WriteLine("{0} bytes used to encode characters.", bytesEncodedCount)
        
        Console.Write("Encoded bytes: ")
        Dim b As Byte
        For Each b In  bytes
            Console.Write("[{0}]", b)
        Next b
        Console.WriteLine()
    End Sub 'Main
End Class 'UTF8EncodingExample

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

class UTF8EncodingExample {
    public static void Main() {
        Char[] chars = new Char[] {'a', 'b', 'c', '\u0300', '\ua0a0'};
        Byte[] bytes;

        Encoder utf8Encoder = Encoding.UTF8.GetEncoder();

        int byteCount = utf8Encoder.GetByteCount(chars, 2, 3, true);
        bytes = new Byte[byteCount];
        int bytesEncodedCount = utf8Encoder.GetBytes(chars, 2, 3, bytes, 0, true);

        Console.WriteLine(
            "{0} bytes used to encode characters.", bytesEncodedCount
        );

        Console.Write("Encoded bytes: ");
        foreach (Byte b in bytes) {
            Console.Write("[{0}]", b);
        }
        Console.WriteLine();
    }
}

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

int main()
{
   Char chars[] = {'a', 'b', 'c', L'\u0300', L'\ua0a0'};
   Byte bytes[];

   Encoder * utf8Encoder = Encoding::UTF8 -> GetEncoder();

   int byteCount = utf8Encoder -> GetByteCount(chars, 2, 3, true);
   bytes = new Byte[byteCount];
   int bytesEncodedCount = utf8Encoder -> GetBytes(chars, 2, 3, bytes, 0, true);

   Console::WriteLine(S"{0} bytes used to encode characters.", __box(bytesEncodedCount));

   Console::Write(S"Encoded bytes: ");
   IEnumerator* myEnum = bytes->GetEnumerator();
   while (myEnum->MoveNext())
   {
      Byte b = *__try_cast<Byte*>(myEnum->Current);
      Console::Write(S"[{0}]", __box(b));
   }
   Console::WriteLine();
}

[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

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, Common Language Infrastructure (CLI) Standard

See Also

UTF8Encoding Class | UTF8Encoding Members | System.Text Namespace | GetByteCount | GetBytes

Show: