Export (0) Print
Expand All

UTF8Encoding.GetDecoder Method

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

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

Return Value

A Decoder.

Remarks

The Decoder.GetChars method converts adjacent blocks of bytes into adjacent blocks of characters, in a manner similar to the GetChars method. However, a Decoder maintains state information between calls so it can correctly decode byte sequences that span blocks.

If this UTF8Encoding is constructed with error detection turned on (that is, the throwOnInvalidBytes parameter is true), the Decoder returned by this method also has error detection turned on. If an error is detected, the decoder is in an undefined state and should not be reused. Use error detection if you intend to stop processing after an error is encountered. Otherwise, if you intend to continue processing after an error is found, do not use error detection.

The GetDecoder method obtains a Decoder that preserves trailing bytes at the end of decoded blocks and uses the trailing bytes in the next decoding 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 GetDecoder method to obtain a UTF-8 decoder. The decoder is used to convert a sequence of bytes in bytes into a sequence of characters in chars.

[Visual Basic] 
Imports System
Imports System.Text

Class UTF8EncodingExample
    
    Public Shared Sub Main()
        Dim chars() As Char
        Dim bytes() As Byte = {99, 204, 128, 234, 130, 160}
        
        Dim utf8Decoder As Decoder = Encoding.UTF8.GetDecoder()
        
        Dim charCount As Integer = utf8Decoder.GetCharCount(bytes, 0, bytes.Length)
        chars = New Char(charCount - 1) {}
        Dim charsDecodedCount As Integer = utf8Decoder.GetChars( _
            bytes, 0, bytes.Length, chars, 0 _
        )
        
        Console.WriteLine("{0} characters used to decode bytes.", charsDecodedCount)
        
        Console.Write("Decoded chars: ")
        Dim c As Char
        For Each c In  chars
            Console.Write("[{0}]", c)
        Next c
        Console.WriteLine()
    End Sub 'Main
End Class 'UTF8EncodingExample

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

class UTF8EncodingExample {
    public static void Main() {
        Char[] chars;
        Byte[] bytes = new Byte[] {
            99, 204, 128, 234, 130, 160
        };

        Decoder utf8Decoder = Encoding.UTF8.GetDecoder();

        int charCount = utf8Decoder.GetCharCount(bytes, 0, bytes.Length);
        chars = new Char[charCount];
        int charsDecodedCount = utf8Decoder.GetChars(bytes, 0, bytes.Length, chars, 0);

        Console.WriteLine(
            "{0} characters used to decode bytes.", charsDecodedCount
        );

        Console.Write("Decoded chars: ");
        foreach (Char c in chars) {
            Console.Write("[{0}]", c);
        }
        Console.WriteLine();
    }
}

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

int main()
{
   Char chars[];
   Byte bytes[] = 
   {
      99, 204, 128, 234, 130, 160
   };

   Decoder * utf8Decoder = Encoding::UTF8 -> GetDecoder();

   int charCount = utf8Decoder -> GetCharCount(bytes, 0, bytes -> Length);
   chars = new Char[charCount];
   int charsDecodedCount = utf8Decoder -> GetChars(bytes, 0, bytes -> Length, chars, 0);

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

   Console::Write(S"Decoded chars: ");
   IEnumerator* myEnum = chars->GetEnumerator();
   while (myEnum->MoveNext())
   {
      Char* c = __try_cast<Char*>(myEnum->Current);
      Console::Write(S"[{0}]", c -> ToString());
   }
   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 | GetCharCount | GetChars

Show:
© 2015 Microsoft