Encoder Class

Definition

Namespace:

System.Text

Assemblies:

netstandard.dll, System.Runtime.dll

Source:

Encoder.cs

Converts a set of characters into a sequence of bytes.

C#

public abstract class Encoder

Inheritance

Object

Encoder

Examples

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 UTF7Encoding. Next, the array of characters is encoded using an Encoder.

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

/* This code example produces the following output.

Using Encoding
--------------
All characters encoded:
[43][65][67][77][65][74][81][79][103][65][54][77][45]

First character:
[43][65][67][77][45]

Second character:
[43][65][67][85][45]

Third character:
[43][65][54][65][45]

Fourth character:
[43][65][54][77][45]

Using Encoder
-------------
All characters encoded:
[43][65][67][77][65][74][81][79][103][65][54][77][45]

First character:
[43][65][67]

Second character:
[77][65][74]

Third character:
[81][79][103]

Fourth character:
[65][54][77][45]


*/

Remarks

To obtain an instance of an implementation of the Encoder class, the application should use the GetEncoder method of an Encoding implementation.

The GetByteCount method determines how many bytes result in encoding a set of Unicode characters, and the GetBytes method performs the actual encoding. There are several versions of both of these methods available in the Encoder class. For more information, see Encoding.GetBytes.

A Encoder object maintains state information between successive calls to GetBytes or Convert methods so that it can correctly encode character sequences that span blocks. The Encoder also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. For example, a data block might end with an unmatched high surrogate, and the matching low surrogate might be in the next data block. 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.

Märkus

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 Encoder object.

Notes to Implementers

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

Constructors

Encoder()

Initializes a new instance of the Encoder class.

Properties

Fallback	Gets or sets a EncoderFallback object for the current Encoder object.
FallbackBuffer	Gets the EncoderFallbackBuffer object associated with the current Encoder object.

Methods

Convert(Char[], Int32, Int32, Byte[], Int32, Int32, Boolean, Int32, Int32, Boolean)	Converts an array of Unicode characters to an encoded byte sequence and stores the result in an array of bytes.
Convert(Char*, Int32, Byte*, Int32, Boolean, Int32, Int32, Boolean)	Converts a buffer of Unicode characters to an encoded byte sequence and stores the result in another buffer.
Convert(ReadOnlySpan<Char>, Span<Byte>, Boolean, Int32, Int32, Boolean)	Converts a span of Unicode characters to an encoded byte sequence and stores the result in another buffer.
Equals(Object)	Determines whether the specified object is equal to the current object. (Inherited from Object)
GetByteCount(Char[], Int32, Int32, Boolean)	When overridden in a derived class, calculates the number of bytes produced by encoding a set of characters from the specified character array. A parameter indicates whether to clear the internal state of the encoder after the calculation.
GetByteCount(Char*, Int32, Boolean)	When overridden in a derived class, calculates the number of bytes produced by encoding a set of characters starting at the specified character pointer. A parameter indicates whether to clear the internal state of the encoder after the calculation.
GetByteCount(ReadOnlySpan<Char>, Boolean)	When overridden in a derived class, calculates the number of bytes produced by encoding a set of characters in the 'chars' span. A parameter indicates whether to clear the internal state of the encoder after the calculation.
GetBytes(Char[], Int32, Int32, Byte[], Int32, Boolean)	When overridden in a derived class, encodes a set of characters from the specified character array and any characters in the internal buffer into the specified byte array. A parameter indicates whether to clear the internal state of the encoder after the conversion.
GetBytes(Char*, Int32, Byte*, Int32, Boolean)	When overridden in a derived class, encodes a set of characters starting at the specified character pointer and any characters in the internal buffer into a sequence of bytes that are stored starting at the specified byte pointer. A parameter indicates whether to clear the internal state of the encoder after the conversion.
GetBytes(ReadOnlySpan<Char>, Span<Byte>, Boolean)	When overridden in a derived class, encodes a set of characters in the input characters span and any characters in the internal buffer into a sequence of bytes that are stored in the input byte span. A parameter indicates whether to clear the internal state of the encoder 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 encoder back to its initial state.
ToString()	Returns a string that represents the current object. (Inherited from Object)

Extension Methods

Convert(Encoder, ReadOnlySequence<Char>, IBufferWriter<Byte>, Boolean, Int64, Boolean)	Converts a ReadOnlySequence<T> to encoded bytes and writes the result to writer.
Convert(Encoder, ReadOnlySpan<Char>, IBufferWriter<Byte>, Boolean, Int64, Boolean)	Converts a ReadOnlySpan<T> to bytes using encoder and writes the result to writer.

Applies to

See also

• Decoder
• Encoding
• Understanding Encodings