Decoder Class

Definition

Namespace:

System.Text

Assembly:

System.Runtime.dll

Source:

Decoder.cs

Converts a sequence of encoded bytes into a set of characters.

public ref class Decoder abstract

public abstract class Decoder

type Decoder = class

Public MustInherit Class Decoder

Inheritance

Object

Decoder

Examples

The following example demonstrates the use of a Decoder to convert two different byte arrays into a character array. One of the character's bytes spans the arrays. This is similar to what a StreamReader object does internally when reading a stream.

using namespace System;
using namespace System::Text;
int main()
{
   
   // These bytes in UTF-8 correspond to 3 different Unicode
   // characters: space (U+0020), # (U+0023), and the biohazard
   // symbol (U+2623).  Note the biohazard symbol requires 3 bytes
   // in UTF-8 (hexadecimal e2, 98, a3).  Decoders store state across
   // multiple calls to GetChars, handling the case when one char
   // is in multiple byte arrays.
   array<Byte>^bytes1 = {0x20,0x23,0xe2};
   array<Byte>^bytes2 = {0x98,0xa3};
   array<Char>^chars = gcnew array<Char>(3);
   Decoder^ d = Encoding::UTF8->GetDecoder();
   int charLen = d->GetChars( bytes1, 0, bytes1->Length, chars, 0 );
   
   // The value of charLen should be 2 now.
   charLen += d->GetChars( bytes2, 0, bytes2->Length, chars, charLen );
   for ( UInt16 index(0); index < chars->Length; ++index )
   {
      Console::Write( "U+{0:X4}  ", static_cast<UInt16>(chars[ index ]) );

   }
}

using System;
using System.Text;
public class dec
{
    public static void Main()
    {
        // These bytes in UTF-8 correspond to 3 different Unicode
        // characters: space (U+0020), # (U+0023), and the biohazard
        // symbol (U+2623).  Note the biohazard symbol requires 3 bytes
        // in UTF-8 (hexadecimal e2, 98, a3).  Decoders store state across
        // multiple calls to GetChars, handling the case when one char
        // is in multiple byte arrays.
        byte[] bytes1 = { 0x20, 0x23, 0xe2 };
        byte[] bytes2 = { 0x98, 0xa3 };
        char[] chars = new char[3];

        Decoder d = Encoding.UTF8.GetDecoder();
        int charLen = d.GetChars(bytes1, 0, bytes1.Length, chars, 0);
        // The value of charLen should be 2 now.
        charLen += d.GetChars(bytes2, 0, bytes2.Length, chars, charLen);
        foreach(char c in chars)
            Console.Write("U+{0:X4}  ", (ushort)c);
    }
}

Imports System.Text

Public Class dec
    
    Public Shared Sub Main()
        ' These bytes in UTF-8 correspond to 3 different Unicode
        ' characters: space (U+0020), # (U+0023), and the biohazard
        ' symbol (U+2623).  Note the biohazard symbol requires 3 bytes
        ' in UTF-8 (hexadecimal e2, 98, a3).  Decoders store state across
        ' multiple calls to GetChars, handling the case when one char
        ' is in multiple byte arrays.
        Dim bytes1 As Byte() =  {&H20, &H23, &HE2}
        Dim bytes2 As Byte() =  {&H98, &HA3}
        Dim chars(3) As Char
        
        Dim d As Decoder = Encoding.UTF8.GetDecoder()
        Dim charLen As Integer = d.GetChars(bytes1, 0, bytes1.Length, chars, 0)
        ' The value of charLen should be 2 now.
        charLen += d.GetChars(bytes2, 0, bytes2.Length, chars, charLen)
        Dim c As Char
        For Each c In  chars
            Console.Write("U+{0:X4}  ", Convert.ToUInt16(c) )
        Next c
    End Sub
End Class

Remarks

To obtain an instance of an implementation of the Decoder class, call the GetDecoder method of an Encoding implementation.

The GetCharCount method determines how many characters result in decoding a sequence of bytes, and the GetChars method performs the actual decoding. There are several versions of both of these methods available in the Decoder class. For more information, see Encoding.GetChars. A Decoder object maintains state information between successive calls to GetChars or Convert methods so it can correctly decode byte sequences that span blocks. The Decoder also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, GetDecoder and GetEncoder are useful for network transmission and file operations because those operations often deal with blocks of data instead of a complete data stream.

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. If an exception occurs or if the application switches streams, it should call Reset to clear the internal state of the Decoder object.

Notes to Implementers

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

Constructors

Decoder()

Initializes a new instance of the Decoder class.

Properties

Fallback	Gets or sets a DecoderFallback object for the current Decoder object.
FallbackBuffer	Gets the DecoderFallbackBuffer object associated with the current Decoder object.

Methods

Convert(Byte[], Int32, Int32, Char[], Int32, Int32, Boolean, Int32, Int32, Boolean)	Converts an array of encoded bytes to UTF-16 encoded characters and stores the result in a character array.
Convert(Byte*, Int32, Char*, Int32, Boolean, Int32, Int32, Boolean)	Converts a buffer of encoded bytes to UTF-16 encoded characters and stores the result in another buffer.
Convert(ReadOnlySpan<Byte>, Span<Char>, Boolean, Int32, Int32, Boolean)	Converts a span of encoded bytes to UTF-16 encoded characters and stores the result in another span buffer.
Equals(Object)	Determines whether the specified object is equal to the current object. (Inherited from Object)
GetCharCount(Byte[], Int32, Int32, Boolean)	When overridden in a derived class, calculates the number of characters produced by decoding a sequence of bytes from the specified byte array. A parameter indicates whether to clear the internal state of the decoder after the calculation.
GetCharCount(Byte[], Int32, Int32)	When overridden in a derived class, calculates the number of characters produced by decoding a sequence of bytes from the specified byte array.
GetCharCount(Byte*, Int32, Boolean)	When overridden in a derived class, calculates the number of characters produced by decoding a sequence of bytes starting at the specified byte pointer. A parameter indicates whether to clear the internal state of the decoder after the calculation.
GetCharCount(ReadOnlySpan<Byte>, Boolean)	When overridden in a derived class, calculates the number of characters produced by decoding the sequence of bytes in the span. A parameter indicates whether to clear the internal state of the decoder after the calculation.
GetChars(Byte[], Int32, Int32, Char[], Int32, Boolean)	When overridden in a derived class, decodes a sequence of bytes from the specified byte array and any bytes in the internal buffer into the specified character array. A parameter indicates whether to clear the internal state of the decoder after the conversion.
GetChars(Byte[], Int32, Int32, Char[], Int32)	When overridden in a derived class, decodes a sequence of bytes from the specified byte array and any bytes in the internal buffer into the specified character array.
GetChars(Byte*, Int32, Char*, Int32, Boolean)	When overridden in a derived class, decodes a sequence of bytes starting at the specified byte pointer and any bytes in the internal buffer into a set of characters that are stored starting at the specified character pointer. A parameter indicates whether to clear the internal state of the decoder after the conversion.
GetChars(ReadOnlySpan<Byte>, Span<Char>, Boolean)	When overridden in a derived class, decodes a sequence of span bytes and any bytes in the internal buffer into a set of characters that are stored starting at the specified character pointer. A parameter indicates whether to clear the internal state of the decoder after the conversion.
GetHashCode()	Serves as the default hash function. (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)
Reset()	When overridden in a derived class, sets the decoder back to its initial state.
ToString()	Returns a string that represents the current object. (Inherited from Object)

Extension Methods

Convert(Decoder, ReadOnlySequence<Byte>, IBufferWriter<Char>, Boolean, Int64, Boolean)	Converts a ReadOnlySequence<T> to UTF-16 encoded characters and writes the result to writer.
Convert(Decoder, ReadOnlySpan<Byte>, IBufferWriter<Char>, Boolean, Int64, Boolean)	Converts a ReadOnlySpan<T> to chars using decoder and writes the result to writer.

See also

• Encoder
• Encoding
• GetChars(Byte[], Int32, Int32)
• Understanding Encodings