System.Text.Encoder Class

Assembly: Mscorlib.dll
Namespace: System.Text
Summary
Converts blocks of Unicode characters into encoded blocks of bytes.
C# Syntax:
[Serializable]
public abstract class Encoder
Remarks
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.

See also:
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.Text.Encoder Member Details

ctor #1
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


Method: Equals(
   object obj
)
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


Method: Finalize()
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


Method: GetByteCount(
   char[] chars,
   int index,
   int count,
   bool flush
)
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
);
Parameters:

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.

Remarks
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


Method: GetBytes(
   char[] chars,
   int charIndex,
   int charCount,
   byte[] bytes,
   int byteIndex,
   bool flush
)
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
);
Parameters:

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.

Remarks
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


Method: GetHashCode()
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


Method: GetType()
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


Method: MemberwiseClone()
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


Method: ToString()
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

Copyright (c) 2002 Microsoft Corporation. All rights reserved.