System.Text.Encoder Class

Summary

Converts blocks of Unicode characters into encoded blocks of bytes.

C# Syntax:

[Serializable] public abstract class Encoder

This is an abstract class. You must implement and override all its methods in a derived class.

An implementation of this class converts blocks of Unicode characters into blocks of encoded bytes through successive calls of the Encoder.GetBytes method. This class maintains state information between successive calls of Encoder.GetBytes, enabling it to encode a character into a sequence of bytes, such as surrogate pairs, that span adjacent blocks. For example, this is useful for encoding a character into a surrogate pair.

The Encoder.GetByteCount method calculates the number of bytes required to encode a specified block of characters.

An instance of Encoder is typically obtained by calling the Encoding.GetEncoder method of a class derived from the Encoding class.

System.Text Namespace | Encoding

System.Text.Encoder Member List:

Public Methods

Equals (inherited from System.Object)	See base class member description: System.Object.Equals Derived from System.Object, the primary base class for all objects.
GetByteCount	When overridden in a derived class, calculates the number of bytes Encoder.GetBytes would produce from encoding the specified range of characters.
GetBytes	When overridden in a derived class, encodes a specified range of characters in a character array and stores them in a specified range of a byte array.
GetHashCode (inherited from System.Object)	See base class member description: System.Object.GetHashCode Derived from System.Object, the primary base class for all objects.
GetType (inherited from System.Object)	See base class member description: System.Object.GetType Derived from System.Object, the primary base class for all objects.
ToString (inherited from System.Object)	See base class member description: System.Object.ToString Derived from System.Object, the primary base class for all objects.

Protected Constructors

ctor #1

Default constructor. This constructor is called by derived class constructors to initialize state in this type. Initializes a new instance of the Encoder class.

Protected Methods

Finalize (inherited from System.Object)	See base class member description: System.Object.Finalize Derived from System.Object, the primary base class for all objects.
MemberwiseClone (inherited from System.Object)	See base class member description: System.Object.MemberwiseClone Derived from System.Object, the primary base class for all objects.

Hierarchy:

• System.Object
• System.Text.Encoder

System.Text.Encoder Member Details

Summary

Initializes a new instance of the Encoder class.

Default constructor. This constructor is called by derived class constructors to initialize state in this type.

C# Syntax:

protected Encoder();

Return to top

Inherited
See base class member description: System.Object.Equals

C# Syntax:

public virtual bool Equals(    object obj );

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.Finalize

C# Syntax:

~Encoder();

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

When overridden in a derived class, calculates the number of bytes Encoder.GetBytes would produce from encoding the specified range of characters.

C# Syntax:

public abstract int GetByteCount(    char[] chars,    int index,    int count,    bool flush );

chars

The Unicode character array to encode.

index

The index of the first character in chars to encode.

count

The number of characters to encode.

flush

true if this instance can flush its internal state after the calculation; otherwise, false.

Return Value:

The number of bytes the next call to Encoder.GetBytes would produce from encoding the specified range of characters and honoring flush.

Exceptions

Exception Type	Condition
ArgumentNullException	chars is null.
ArgumentOutOfRangeException	index or count is less than zero. -or- index plus count is greater than the length of chars.

Use Encoder.GetByteCount to calculate the array size required by the Encoder.GetBytes method to store encoded chararacters.

The state of the encoder is not affected by calling this method.

Return to top

Summary

When overridden in a derived class, encodes a specified range of characters in a character array and stores them in a specified range of a byte array.

C# Syntax:

public abstract int GetBytes(    char[] chars,    int charIndex,    int charCount,    byte[] bytes,    int byteIndex,    bool flush );

chars

The character array to encode.

charIndex

The index of the first character in chars to encode.

charCount

The number of characters to encode.

bytes

The byte array where the encoding is stored.

byteIndex

The index of the first element in bytes where the encoding is stored.

flush

true if this encoder can flush its state at the end of the conversion; otherwise, false. To ensure correct termination of a sequence of blocks of encoded bytes, the last call to GetBytes can specify a value of true for flush.

Return Value:

The number of bytes encoded into bytes.

Exceptions

Exception Type	Condition
ArgumentNullException	chars or bytes is null.
ArgumentOutOfRangeException	charIndex, charCount, or byteIndex is less than zero. -or- charIndex plus charCount is greater than the length of chars. -or- byteIndex plus charCount is greater than the length of bytes.

Use Encoder.GetByteCount to calculate the array size required by the Encoder.GetBytes method to store encoded characters.

It is recommended that you always call Encoder.GetByteCount before calling Encoder.GetBytes because the Encoder.GetBytes method might change the internal state information between blocks of bytes.

The flush parameter is useful for flushing a high-surrogate at the end of a stream that does not have a low-surrogate. For example, the Encoder created by UTF8Encoding.GetEncoder uses this parameter to determine whether to write out a dangling high-surrogate at the end of a character block.

Return to top

Inherited
See base class member description: System.Object.GetHashCode

C# Syntax:

public virtual int GetHashCode();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.GetType

C# Syntax:

public Type GetType();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.MemberwiseClone

C# Syntax:

protected object MemberwiseClone();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.ToString

C# Syntax:

public virtual string ToString();

For more information on members inherited from System.Object click on the link above.

Return to top

Top of page