UTF8Encoding.GetEncoder-Methode

Ruft einen Encoder ab, der eine Unicode-Zeichenfolge in eine UTF-8-codierte Bytefolge konvertiert.

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

Syntax

'Declaration
Public Overrides Function GetEncoder As Encoder
'Usage
Dim instance As UTF8Encoding
Dim returnValue As Encoder

returnValue = instance.GetEncoder

public override Encoder GetEncoder ()

public:
virtual Encoder^ GetEncoder () override

public Encoder GetEncoder ()

public override function GetEncoder () : Encoder

Rückgabewert

Ein Encoder, der eine Unicode-Zeichenfolge in eine UTF-8-codierte Bytefolge konvertiert.

Hinweise

Ähnlich wie die GetBytes-Methode dieser Klasse konvertiert die Encoder.GetBytes-Methode Blöcke von Zeichenfolgen in Blöcke von Bytefolgen. Ein Encoder behält Zustandsinformationen zwischen Aufrufen bei, damit Zeichenfolgen, die mehrere Blöcke umfassen, korrekt codiert werden können. Der Encoder behält nachfolgende Zeichen am Ende von Datenblöcken bei und verwendet diese im nächsten Codierungsvorgang. Beispielsweise kann ein Datenblock mit einem hohen Ersatzzeichen ohne Entsprechung enden, während sich das entsprechende niedrige Ersatzzeichen im nächsten Datenblock befindet. Deshalb empfehlen sich GetDecoder und GetEncoder für Netzwerkübertragungs- und Dateivorgänge, da bei diesen Vorgängen oft Datenblöcke und keine vollständigen Datenstreams verwendet werden.

Wenn die Fehlererkennung in dieser Instanz aktiviert ist (d. h, der throwOnInvalidCharacters-Parameter des Konstruktors wurde auf true festgelegt), wird die Fehlererkennung auch im Encoder aktiviert, der von dieser Methode zurückgegeben wird. Wenn die Fehlererkennung aktiviert ist und eine ungültige Folge gefunden wird, ist der Zustand des Encoders nicht definiert, und daher muss die Verarbeitung beendet werden.

Beispiel

Im folgenden Beispiel wird veranschaulicht, wie mit der GetEncoder-Methode ein Encoder für die Konvertierung einer Folge von Zeichen in eine UTF-8-codierte Folge von Bytes abgerufen wird.

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

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();
    }
}

using namespace System;
using namespace System::Text;
using namespace System::Collections;
int main()
{
   array<Char>^chars = {'a','b','c',L'\u0300',L'\ua0a0'};
   array<Byte>^bytes;
   Encoder^ utf8Encoder = Encoding::UTF8->GetEncoder();
   int byteCount = utf8Encoder->GetByteCount( chars, 2, 3, true );
   bytes = gcnew array<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: " );
   IEnumerator^ myEnum = bytes->GetEnumerator();
   while ( myEnum->MoveNext() )
   {
      Byte b = safe_cast<Byte>(myEnum->Current);
      Console::Write( "[{0}]", b );
   }

   Console::WriteLine();
}

import System.*;
import System.Text.*;

class UTF8EncodingExample
{
    public static void main(String[] args)
    {
        char chars[] = new char[] { 'a', 'b', 'c', '\u0300', '\ua0a0' };
        ubyte bytes[];
        Encoder utf8Encoder = Encoding.get_UTF8().GetEncoder();
        int byteCount = utf8Encoder.GetByteCount(chars, 2, 3, true);
        bytes = new ubyte[byteCount];
        int bytesEncodedCount = utf8Encoder.GetBytes(chars, 2, 3,
            bytes, 0, true);

        Console.WriteLine("{0} bytes used to encode characters.", 
            String.valueOf(bytesEncodedCount));
        Console.Write("Encoded bytes: ");
        for (int iCtr = 0; iCtr < bytes.length; iCtr++) {
            ubyte b = bytes[iCtr];
            Console.Write("[{0}]", String.valueOf(b));
        }
        Console.WriteLine();
    } //main
} //UTF8EncodingExample

Plattformen

Windows 98, Windows 2000 SP4, Windows CE, Windows Millennium Edition, Windows Mobile für Pocket PC, Windows Mobile für Smartphone, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

.NET Framework unterstützt nicht alle Versionen sämtlicher Plattformen. Eine Liste der unterstützten Versionen finden Sie unter Systemanforderungen.

Versionsinformationen

.NET Framework

Unterstützt in: 2.0, 1.1, 1.0

.NET Compact Framework

Unterstützt in: 2.0, 1.0

Siehe auch

Referenz

UTF8Encoding-Klasse
UTF8Encoding-Member
System.Text-Namespace
Encoder-Klasse
GetBytes
GetByteCount
GetDecoder