System.Text.Encoding Class

Summary

Represents a character encoding.

C# Syntax:

[Serializable] public abstract class Encoding

This type is safe for multithreaded operations.

Methods are provided to convert arrays and strings of Unicode characters to and from arrays of bytes encoded for a target code page.

A number of Encoding implementations are provided in the System.Text namespace, including:

The ASCIIEncoding class encodes Unicode characters as single 7-bit ASCII characters. This encoding only supports character values between U+0000 and U+007F.

The UnicodeEncoding class encodes each Unicode character as two consecutive bytes. Both little-endian (code page 1200) and big-endian (code page 1201) byte orders are supported.

The UTF7Encoding class encodes Unicode characters using the UTF-7 encoding (UTF-7 stands for UCS Transformation Format, 7-bit form). This encoding supports all Unicode character values, and can also be accessed as code page 65000.

The UTF8Encoding class encodes Unicode characters using the UTF-8 encoding (UTF-8 stands for UCS Transformation Format, 8-bit form). This encoding supports all Unicode character values, and can also be accessed as code page 65001.

Use the Encoding.GetEncoding method with a code page or name parameter to obtain other encodings.

When the data to be converted is only available in sequential blocks (such as data read from a stream), an application can use a Decoder or an Encoder to perform the conversion. This is also useful when the amount of data is so large that it needs to be divided into smaller blocks. Decoders and encoders are obtained using the Encoding.GetDecoder and Encoding.GetEncoder methods. An application can use the properties of this class such as Encoding.ASCII, Encoding.Default, Encoding.Unicode, Encoding.UTF7, and Encoding.UTF8 to obtain encodings. Applications can initialize new instances of Encoding objects through the ASCIIEncoding, UnicodeEncoding, UTF7Encoding, and UTF8Encoding classes.

Through an encoding, the Encoding.GetBytes method is used to convert arrays of Unicode characters to arrays of bytes, and the Encoding.GetChars method is used to convert arrays of bytes to arrays of Unicode characters. The Encoding.GetBytes and Encoding.GetChars methods maintain no state between conversions.

When the data to be converted is only available in sequential blocks (such as data read from a stream) or when the amount of data is so large that it needs to be divided into smaller blocks, an application can use a Decoder or an Encoder to perform the conversion. Decoders and encoders allow sequential blocks of data to be converted and they maintain the state required to support conversions of data that spans adjacent blocks. Decoders and encoders are obtained using the Encoding.GetDecoder and Encoding.GetEncoder methods.

The core Encoding.GetBytes and Encoding.GetChars methods require the caller to provide the destination buffer and ensure that the buffer is large enough to hold the entire result of the conversion. An application can use one of the following methods to calculate the required size of the destination buffer.

1. The Encoding.GetByteCount and Encoding.GetCharCount methods can be used to compute the exact size of the result of a particular conversion, and an appropriately sized buffer for that conversion can then be allocated.
2. The Encoding.GetMaxByteCount and Encoding.GetMaxCharCount methods can be used to compute the maximum possible size of a conversion of a given number of bytes or characters, and a buffer of that size can then be reused for multiple conversions.

The first method generally uses less memory, whereas the second method generally executes faster.

System.Text Namespace

System.Text.Encoding Member List:

Public Properties

ASCII	Read-only Gets an encoding for the ASCII (7 bit) character set.
BigEndianUnicode	Read-only Gets an encoding for the Unicode format in the big-endian byte order.
BodyName	Read-only Gets the name for this encoding that can be used with mail agent body tags.
CodePage	Read-only When overridden in a derived class, gets the code page identifier of this encoding.
Default	Read-only Gets an encoding for the system's current ANSI code page.
EncodingName	Read-only Gets the human-readable description of the encoding.
HeaderName	Read-only Gets the name for this encoding that can be used with mail agent header tags.
IsBrowserDisplay	Read-only Gets an indication whether this encoding can be used for display by browser clients.
IsBrowserSave	Read-only Gets an indication whether this encoding can be used for saving by browser clients.
IsMailNewsDisplay	Read-only Gets and indication whether this encoding can be used for display by mail and news clients.
IsMailNewsSave	Read-only Gets an indication whether this encoding can be used for saving by mail and news clients.
Unicode	Read-only Gets an encoding for the Unicode format in little-endian byte order.
UTF7	Read-only Gets an encoding for the UTF-7 format.
UTF8	Read-only Gets an encoding for the UTF-8 format.
WebName	Read-only Gets the name registered with the Internet Assigned Numbers Authority (IANA) for this encoding.
WindowsCodePage	Read-only Gets the Windows operating system code page that most closely corresponds to this encoding.

Public Methods

Convert	Overloaded: Convert(Encoding srcEncoding, Encoding dstEncoding, byte[] bytes) Converts a byte array from one encoding to another.
Convert	Overloaded: Convert(Encoding srcEncoding, Encoding dstEncoding, byte[] bytes, int index, int count) Converts a range of bytes in a byte array from one encoding to another.
Equals	Overridden: Determines whether the current instance and the specified Object represent the same type and value.
GetByteCount	Overloaded: GetByteCount(char[] chars) Calculates the number of bytes required to encode a specified character array.
GetByteCount	Overloaded: GetByteCount(string s) Calculates the number of bytes required to encode the specified String.
GetByteCount	Overloaded: GetByteCount(char[] chars, int index, int count) When overridden in a derived class, returns the number of bytes required to encode a range of characters in the specified character array.
GetBytes	Overloaded: GetBytes(char[] chars) Encodes a specified character array into a byte array.
GetBytes	Overloaded: GetBytes(string s) Encodes a specified String into an array of bytes.
GetBytes	Overloaded: GetBytes(char[] chars, int index, int count) Encodes a range of characters from a character array into a byte array.
GetBytes	Overloaded: GetBytes(char[] chars, int charIndex, int charCount, byte[] bytes, int byteIndex) When overridden in a derived class, encodes a range of characters from a character array into a byte array.
GetBytes	Overloaded: GetBytes(string s, int charIndex, int charCount, byte[] bytes, int byteIndex) Encodes the specified range of a String into the specified range of a byte array.
GetCharCount	Overloaded: GetCharCount(byte[] bytes) Calculates the number of characters produced by decoding an array of bytes.
GetCharCount	Overloaded: GetCharCount(byte[] bytes, int index, int count) When overridden in a derived class, calculates the number of characters produced by decoding a specified range of elements in an array of bytes.
GetChars	Overloaded: GetChars(byte[] bytes) Decodes a byte array into an array of characters.
GetChars	Overloaded: GetChars(byte[] bytes, int index, int count) Decodes a range of bytes from a byte array into a character array.
GetChars	Overloaded: GetChars(byte[] bytes, int byteIndex, int byteCount, char[] chars, int charIndex) When overridden in a derived class, decodes a range of bytes in a byte array into a range of characters in a character array.
GetDecoder	Returns a Decoder for this encoding.
GetEncoder	An Encoder for this encoding.
GetEncoding	Overloaded: GetEncoding(int codepage) Returns an Encoding that corresponds to the specified code page value.
GetEncoding	Overloaded: GetEncoding(string name) Returns an Encoding for the specified name.
GetHashCode	Overridden: Returns the hash code for this instance.
GetMaxByteCount	When overridden in a derived class, returns the maximum number of bytes required to encode a given number of characters.
GetMaxCharCount	When overridden in a derived class, returns the maximum number of characters produced by decoding a given number of bytes.
GetPreamble	Returns a set of bytes used at the beginning of a stream to determine which encoding a file was created with. This can include the Unicode byte order mark.
GetString	Overloaded: GetString(byte[] bytes) Returns a string containing the decoded representation of the specified byte array.
GetString	Overloaded: GetString(byte[] bytes, int index, int count) Returns a string containing the decoded representation of a range of bytes in a byte array.
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	Overloaded: .ctor() Default constructor. This constructor is called by derived class constructors to initialize state in this type. Initializes a new instance of the Encoding class.
ctor #2	Overloaded: .ctor(int codePage) Initializes a new instance of the Encoding 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.Encoding
  • System.Text.ASCIIEncoding
  • System.Text.UnicodeEncoding
  • System.Text.UTF7Encoding
  • System.Text.UTF8Encoding

System.Text.Encoding Member Details

Summary

Initializes a new instance of the Encoding class.

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

C# Syntax:

protected Encoding();

Return to top

Summary

Initializes a new instance of the Encoding class.

C# Syntax:

protected Encoding(    int codePage );

codePage

A code page value that corresponds to the preferred encoding.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	codePage is less than zero.

Return to top

Summary

Gets an encoding for the ASCII (7 bit) character set.

C# Syntax:

public static Encoding ASCII {get;}

ASCII characters are limited to the lowest 128 Unicode characters, from U+0000 to U+007f.

Return to top

Summary

Gets an encoding for the Unicode format in the big-endian byte order.

C# Syntax:

public static Encoding BigEndianUnicode {get;}

Unicode characters can be stored in two different byte orders: big-endian and little-endian. On little-endian platforms such as Intel machines, it is generally more efficient to store Unicode characters in little-endian order. However, many other platforms can store Unicode characters in big-endian order.

Unicode files can be distinguished by the presence of the byte order mark (U+FEFF), which is represented as hexadecimal 0xFE 0xFF on big-endian platforms and hexadecimal 0xFF 0xFE on little-endian platforms.

Return to top

Summary

Gets the name for this encoding that can be used with mail agent body tags.

C# Syntax:

public virtual string BodyName {get;}

For example, if this encoding is equivalent to UTF8Encoding, this property returns "utf-8".

If the encoding cannot be used, the property value is the empty string ("").

Return to top

Summary

When overridden in a derived class, gets the code page identifier of this encoding.

C# Syntax:

public virtual int CodePage {get;}

This property must be implemented or overridden.

Return to top

Summary

Gets an encoding for the system's current ANSI code page.

C# Syntax:

public static Encoding Default {get;}

You can also retrieve your system's current ANSI code page with the Win32 API GetACP() method.

Return to top

Summary

Gets the human-readable description of the encoding.

C# Syntax:

public virtual string EncodingName {get;}

An example of an Encoding.EncodingName is Hebrew (DOS) for code page 862.

Return to top

Summary

Gets the name for this encoding that can be used with mail agent header tags.

C# Syntax:

public virtual string HeaderName {get;}

For example, if this encoding is equivalent to UTF8Encoding, this property returns "utf-8".

If the encoding cannot be used, the string is empty.

Return to top

Summary

Gets an indication whether this encoding can be used for display by browser clients.

C# Syntax:

public virtual bool IsBrowserDisplay {get;}

For example, this property returns true for code page 1252 (windows-1252), but false for code page 437 (IBM-437).

Return to top

Summary

Gets an indication whether this encoding can be used for saving by browser clients.

C# Syntax:

public virtual bool IsBrowserSave {get;}

For example, this property returns true for code page 1252 (windows-1252), but false for code page 437 (IBM-437).

Return to top

Summary

Gets and indication whether this encoding can be used for display by mail and news clients.

C# Syntax:

public virtual bool IsMailNewsDisplay {get;}

For example, this property returns true for code page 1252 (windows-1252), but false for code page 437 (IBM-437).

Return to top

Summary

Gets an indication whether this encoding can be used for saving by mail and news clients.

C# Syntax:

public virtual bool IsMailNewsSave {get;}

For example, this property returns true for code page 1252 (windows-1252), but false for code page 437 (IBM-437).

Return to top

Summary

Gets an encoding for the Unicode format in little-endian byte order.

C# Syntax:

public static Encoding Unicode {get;}

Unicode characters can be stored in two different byte orders: big-endian and little-endian. On little-endian platforms such as Intel machines, it is generally more efficient to store Unicode characters in little-endian byte order. However, many other platforms can store Unicode characters in big-endian byte order.

Unicode files can be distinguished by the presence of the byte order mark (U+FEFF), which is represented as hexadecimal 0xFE 0xFF on big-endian platforms and hexadecimal 0xFF 0xFE on little-endian platforms.

Return to top

Summary

Gets an encoding for the UTF-7 format.

C# Syntax:

public static Encoding UTF7 {get;}

Return to top

Summary

Gets an encoding for the UTF-8 format.

C# Syntax:

public static Encoding UTF8 {get;}

Return to top

Summary

Gets the name registered with the Internet Assigned Numbers Authority (IANA) for this encoding.

C# Syntax:

public virtual string WebName {get;}

Return to top

Summary

Gets the Windows operating system code page that most closely corresponds to this encoding.

C# Syntax:

public virtual int WindowsCodePage {get;}

Return to top

Summary

Converts a byte array from one encoding to another.

C# Syntax:

public static byte[] Convert(    Encoding srcEncoding,    Encoding dstEncoding,    byte[] bytes );

srcEncoding

The encoding that bytes is in.

dstEncoding

The encoding desired for the returned byte array.

bytes

The bytes to convert.

Return Value:

An array of type Byte containing the result of the conversion.

Exceptions

Exception Type	Condition
ArgumentNullException	srcEncoding, dstEncoding, or bytes is null.

The bytes in the byte array are converted from srcEncoding to dstEncoding.

Return to top

Summary

Converts a range of bytes in a byte array from one encoding to another.

C# Syntax:

public static byte[] Convert(    Encoding srcEncoding,    Encoding dstEncoding,    byte[] bytes,    int index,    int count );

srcEncoding

The source of encoding.

dstEncoding

The destination of encoding.

bytes

The byte array to convert.

index

The starting index of the byte array to convert.

count

The number of bytes to convert.

Return Value:

An array of type Byte containing the result of the conversion.

Exceptions

Exception Type	Condition
ArgumentNullException	srcEncoding, dstEncoding, or bytes arguments are null.
ArgumentOutOfRangeException	index and count do not denote a valid range in the byte array.

This method converts count bytes at the starting index from srcEncoding to dstEncoding.

Return to top

Summary

Determines whether the current instance and the specified Object represent the same type and value.

C# Syntax:

public override bool Equals(    object value );

value

The Object to compare to the current instance.

Return Value:

true if value represents the same type and value as the current instance; otherwise, false.false if value is null or is not an instance of Encoding.

Return to top

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

C# Syntax:

~Encoding();

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

Return to top

Summary

Calculates the number of bytes required to encode a specified character array.

C# Syntax:

public virtual int GetByteCount(    char[] chars );

chars

The character array to encode.

Return Value:

The number of bytes needed to encode chars.

Exceptions

Exception Type	Condition
ArgumentNullException	chars is null.

Encoding.GetByteCount can be used to determine the exact the number of bytes that will be produced from encoding the given array of characters. An appropriately sized buffer for that conversion can then be allocated.

Alternatively, Encoding.GetMaxByteCount can be used to determine the maximum number of bytes that will be produced from converting a given number of characters. A buffer of that size can then be reused for multiple conversions.

The Encoding.GetByteCount method generally uses less memory, whereas the Encoding.GetMaxByteCount method generally executes faster.

Return to top

Summary

Calculates the number of bytes required to encode the specified String.

C# Syntax:

public virtual int GetByteCount(    string s );

s

The String to encode.

Return Value:

The number of bytes required to encode s.

Encoding.GetByteCount can be used to determine the exact the number of bytes that will be produced from encoding the given String. An appropriately sized buffer for that conversion can then be allocated.

Alternatively, Encoding.GetMaxByteCount can be used to determine the maximum number of bytes that will be produced from converting a given String. A buffer of that size can then be reused for multiple conversions.

The Encoding.GetByteCount method generally uses less memory, whereas the Encoding.GetMaxByteCount method generally executes faster.

Return to top

Summary

When overridden in a derived class, returns the number of bytes required to encode a range of characters in the specified character array.

C# Syntax:

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

chars

The character array to encode.

index

The starting index of the character array to encode.

count

The number of characters to encode.

Return Value:

The number of bytes required to encode the specified range of characters.

Exceptions

Exception Type	Condition
ArgumentNullException	chars is null.
ArgumentOutOfRangeException	index and count do not denote a valid range in the character array.

Encoding.GetByteCount can be used to determine the exact the number of bytes that will be produced from encoding the given array of characters. An appropriately sized buffer for that conversion can then be allocated.

Alternatively, Encoding.GetMaxByteCount can be used to determine the maximum number of bytes that will be produced from converting a given number of characters. A buffer of that size can then be reused for multiple conversions.

The Encoding.GetByteCount method generally uses less memory, whereas the Encoding.GetMaxByteCount method generally executes faster.

Return to top

Summary

Encodes a specified character array into a byte array.

C# Syntax:

public virtual byte[] GetBytes(    char[] chars );

chars

The character array to encode.

Return Value:

A byte array containing the encoded representation of chars.

Exceptions

Exception Type	Condition
ArgumentNullException	chars is null.

Return to top

Summary

Encodes a specified String into an array of bytes.

C# Syntax:

public virtual byte[] GetBytes(    string s );

s

The String to encode.

Return Value:

A byte array containing the encoded representation of the specified string.

Exceptions

Exception Type	Condition
ArgumentNullException	s is null.

The Encoding.GetBytes method maintains no state between conversions. The method is intended for conversion of a complete block of characters in one operation.

Return to top

Summary

Encodes a range of characters from a character array into a byte array.

C# Syntax:

public virtual byte[] GetBytes(    char[] chars,    int index,    int count );

chars

The character array to encode.

index

The starting index of the character array to encode.

count

The number of characters to encode.

Return Value:

A byte array containing the encoded representation of the specified range of characters in chars.

Exceptions

Exception Type	Condition
ArgumentNullException	chars is null.
ArgumentOutOfRangeException	The index and count parameters do not denote a valid range in chars.

Return to top

Summary

When overridden in a derived class, encodes a range of characters from a character array into a byte array.

C# Syntax:

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

chars

The character array to encode.

charIndex

The starting index of the character array to encode.

charCount

The number of characters to encode.

bytes

The byte array where the resulting encoding is stored.

byteIndex

The starting index of the resulting encoding in the byte array.

Return Value:

The number of bytes stored in array bytes.

Exceptions

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

Encodes a range of characters in a character array into a range of bytes in a byte array. An exception occurs if the byte array is not large enough to hold the complete encoding of the characters.

Encoding.GetByteCount can be used to determine the exact number of bytes that will be produced for a given range of characters. Alternatively, Encoding.GetMaxByteCount can be used to determine the maximum number of bytes that will be produced for a given number of characters, regardless of the actual character values.

Return to top

Summary

Encodes the specified range of a String into the specified range of a byte array.

C# Syntax:

public virtual int GetBytes(    string s,    int charIndex,    int charCount,    byte[] bytes,    int byteIndex );

s

A String to encode.

charIndex

The first index of s from which to encode.

charCount

The number of characters of s to encode.

bytes

The byte array to encode into.

byteIndex

The first index of bytes to encode into.

Return Value:

The number of encoded bytes in array bytes.

Exceptions

Exception Type	Condition
ArgumentNullException	s or bytes is null.
ArgumentOutOfRangeException	charIndex, charCount, or byteIndex is less than zero. -or- charIndex and charCount do not specify a valid range in s (that is, (charIndex + charCount) is greater than the length of s). -or- byteIndex and charCount do not specify a valid range in bytes (that is, (byteIndex + charCount) is greater than the length of bytes).

Return to top

Summary

Calculates the number of characters produced by decoding an array of bytes.

C# Syntax:

public virtual int GetCharCount(    byte[] bytes );

bytes

The byte array to decode.

Return Value:

The number of characters produced by decoding the specified byte array.

Exceptions

Exception Type	Condition
ArgumentNullException	bytes is null.

The Encoding.GetCharCount method can be used to determine the exact the number of characters that will be produced from converting a given range of bytes. An appropriately sized buffer for that conversion can then be allocated.

Alternatively, the Encoding.GetMaxCharCount method can be used to determine the maximum number of characters that will produced for a given number of bytes. A buffer of that size can then be reused for multiple conversions.

The Encoding.GetCharCount method generally uses less memory, whereas the Encoding.GetMaxCharCount method generally executes faster.

Return to top

Summary

When overridden in a derived class, calculates the number of characters produced by decoding a specified range of elements in an array of bytes.

C# Syntax:

public abstract int GetCharCount(    byte[] bytes,    int index,    int count );

bytes

The byte array to decode.

index

The starting index where decoding begins.

count

The number of bytes to decode.

Return Value:

The number of characters produced by decoding a range of bytes in the specified byte array.

Exceptions

Exception Type	Condition
ArgumentNullException	bytes is null.
ArgumentOutOfRangeException	index and count do not denote a valid range in the byte array.

The Encoding.GetCharCount method can be used to determine the exact the number of characters that will be produces from converting a given range of bytes. An appropriately sized buffer for that conversion can then be allocated.

Alternatively, the Encoding.GetMaxCharCount method can be used to determine the maximum number of characters that will produced for a given number of bytes. A buffer of that size can then be reused for multiple conversions.

The Encoding.GetCharCount method generally uses less memory, whereas the Encoding.GetMaxCharCount method generally executes faster.

Return to top

Summary

Decodes a byte array into an array of characters.

C# Syntax:

public virtual char[] GetChars(    byte[] bytes );

bytes

The byte array to decode.

Return Value:

A character array containing the decoded character representation from array bytes.

Exceptions

Exception Type	Condition
ArgumentNullException	bytes is null.

Encoding.GetChars assumes that the byte array contains all the bytes necessary to produce whole characters. If your bytes might be in multiple byte arrays (that is, the bytes corresponding to a single character might be at the end of one byte array and the beginning of another), use the Decoder class, which maintains state between multiple calls.

Return to top

Summary

Decodes a range of bytes from a byte array into a character array.

C# Syntax:

public virtual char[] GetChars(    byte[] bytes,    int index,    int count );

bytes

The byte array to decode.

index

The starting index of the byte array to decode.

count

The number of bytes to decode.

Return Value:

A character array containing the decoded character representation from a range of array bytes.

Exceptions

Exception Type	Condition
ArgumentNullException	bytes is null.
ArgumentOutOfRangeException	index and count do not denote a valid range in the byte array.

Encoding.GetChars assumes that the byte array contains all the bytes necessary to produce whole characters. If your bytes might be in multiple byte arrays (that is, the bytes corresponding to a single character might be at the end of one byte array and the beginning of another), use the Decoder class, which maintains state between multiple calls.

Return to top

Summary

When overridden in a derived class, decodes a range of bytes in a byte array into a range of characters in a character array.

C# Syntax:

public abstract int GetChars(    byte[] bytes,    int byteIndex,    int byteCount,    char[] chars,    int charIndex );

bytes

The byte array to decode.

byteIndex

The starting index of the byte array to decode.

byteCount

The number of bytes to decode.

chars

The character array where the resulting decoding is stored.

charIndex

The starting index of the resulting decoding in the character array.

Return Value:

The number of characters stored in the character array.

Exceptions

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

The Encoding.GetChars method maintains no state between conversions. The method is intended for conversions of complete blocks of bytes and characters in one operation. If your bytes might be in multiple byte arrays (that is, the bytes corresponding to a single character might be at the end of one byte array and the beginning of another), use the Decoder class, which will maintain state between multiple calls.

The Encoding.GetChars method requires the caller to provide the destination buffer and ensure that the buffer is large enough to hold the entire result of the conversion. An application can use Encoding.GetCharCount or Encoding.GetMaxCharCount to calculate the required size of the destination buffer.

You can use this method to determine the exact number of characters that will be produced for a given range of bytes. Alternatively, the Encoding.GetMaxCharCount method can be used to determine the maximum number of characters that will be produced for a given number of bytes, regardless of the actual byte values.

Return to top

Summary

Returns a Decoder for this encoding.

C# Syntax:

public virtual Decoder GetDecoder();

Return Value:

Returns a Decoder for this encoding. The Decoder can be used to decode a sequence of bytes into characters.

Contrary to the Encoding.GetChars methods, a Decoder can convert partial sequences of bytes into partial sequences of characters by maintaining the appropriate state between the conversions.

This default implementation returns a Decoder that forwards calls to the Encoding.GetCharCount and Encoding.GetChars methods to the corresponding methods of this encoding. Encodings that require state to be maintained between successive conversions can override this method and return an instance of an appropriate Decoder implementation.

Return to top

Summary

An Encoder for this encoding.

C# Syntax:

public virtual Encoder GetEncoder();

Return Value:

An Encoder for this encoding. The Encoder can be used to encode a sequence of characters into bytes.

Contrary to Encoding.GetBytes, an Encoder can convert partial sequences of characters into partial sequences of bytes by maintaining the appropriate state between the conversions.

This default implementation returns an Encoder that forwards calls to Encoding.GetByteCount and Encoding.GetBytes to the corresponding methods of this encoding. Encodings that require state to be maintained between successive conversions can override this method and return an instance of an appropriate Encoder implementation.

Return to top

Summary

Returns an Encoding that corresponds to the specified code page value.

C# Syntax:

public static Encoding GetEncoding(    int codepage );

codepage

A code page value that corresponds to the preferred encoding.

Return Value:

The requested encoding.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	codepage is less than zero or greater than 65535.
NotSupportedException	codepage is not supported by the current regional options of the computer executing this method.

The Encoding.GetEncoding method relies on the underlying platform to support most code pages. However, system support is supplied for the following cases: Specify code page 0 for the default encoding, that is, the encoding specified in the regional settings for the computer executing this method; 1200 for little-endian Unicode (UTF-16LE); 1201 for big-endian Unicode (UTF-16BE); 1252 for Windows operating system (windows-1252); 65000 for UTF-7; 65001 for UTF-8; 20127 for ASCII, and 54936 for GB18030 (Chinese Simplified).

For example, the encoding for the windows-1252 code page (code page value 1252) can be created by the following C# code:

Encoding enc = Encoding.GetEncoding(1252);

A specific code page might not be supported by certain platforms. For example, the Japanese shift-jis code page (code page 932) might not be supported in the United States version of Windows 98. In that case, the Encoding.GetEncoding method throws NotSupportedException when the following C# code is executed:

Encoding enc = Encoding.GetEncoding(932);

Return to top

Summary

Returns an Encoding for the specified name.

C# Syntax:

public static Encoding GetEncoding(    string name );

name

The name of an Encoding.

Return Value:

The requested encoding.

Exceptions

Exception Type	Condition
NotSupportedException	The name encoding is not supported by the current regional options of the computer executing this method.

The Encoding.GetEncoding method relies on the underlying platform to support most code pages. However, system support is supplied for the following cases: The default encoding, that is, the encoding specified in the regional settings for the computer executing this method; little-endian Unicode (UTF-16LE); big-endian Unicode (UTF-16BE); Windows operating system (windows-1252); UTF-7; UTF-8; ASCII, and GB18030 (Chinese Simplified).

Specify one of the names listed in the following table to obtain the system supported encoding with the corresponding code page.

code page	name
1200	"UTF-16LE", "utf-16", "ucs-2", "unicode", or "ISO-10646-UCS-2"
1201	"UTF-16BE" or "unicodeFFFE"
1252	"windows-1252"
65000	"utf-7", "csUnicode11UTF7", "unicode-1-1-utf-7", "unicode-2-0-utf-7", "x-unicode-1-1-utf-7", or "x-unicode-2-0-utf-7"
65001	"utf-8", "unicode-1-1-utf-8", "unicode-2-0-utf-8", "x-unicode-1-1-utf-8", or "x-unicode-2-0-utf-8"
20127	"us-ascii", "us", "ascii", "ANSI_X3.4-1968", "ANSI_X3.4-1986", "cp367", "csASCII", "IBM367", "iso-ir-6", "ISO646-US", or "ISO_646.irv:1991"
54936	"GB18030"

A specific code page might not be supported by certain platforms. For example, the Japanese shift-jis code page (code page 932) might not be supported in the United States version of Windows 98. In that case, the Encoding.GetEncoding method throws NotSupportedException when the following C# code is executed:

Encoding enc = Encoding.GetEncoding("shift-jis");

Return to top

Summary

Returns the hash code for this instance.

C# Syntax:

public override int GetHashCode();

Return Value:

A 32-bit signed integer hash code.

Return to top

Summary

When overridden in a derived class, returns the maximum number of bytes required to encode a given number of characters.

C# Syntax:

public abstract int GetMaxByteCount(    int charCount );

charCount

The number of characters to encode.

Return Value:

The maximum number of bytes required for encoding a given number of characters.

Encoding.GetMaxByteCount can be used to determine an appropriate buffer size for byte arrays passed to the Encoding.GetBytes of this encoding.

All encoding must guarantee that no buffer overflow exceptions will occur if buffers are sized according to the results of this method.

Return to top

Summary

When overridden in a derived class, returns the maximum number of characters produced by decoding a given number of bytes.

C# Syntax:

public abstract int GetMaxCharCount(    int byteCount );

byteCount

The number of bytes to encode.

Return Value:

The maximum number of characters produced by decoding a specified number of bytes.

This method can be used to determine an appropriate buffer size for character arrays passed to Encoding.GetChars or a Decoder for this encoding. All encoding must guarantee that no buffer overflow exceptions will occur if buffers are sized according to the results of this method.

Return to top

Summary

Returns a set of bytes used at the beginning of a stream to determine which encoding a file was created with. This can include the Unicode byte order mark.

C# Syntax:

public virtual byte[] GetPreamble();

Return Value:

The bytes at the beginning of a stream, which typically comprise the byte order mark.

The preamble can be the Unicode byte order mark (U+FEFF written in the appropriate encoding) or any other type of identifying marks. This method can return an empty byte array.

Return to top

Summary

Returns a string containing the decoded representation of the specified byte array.

C# Syntax:

public virtual string GetString(    byte[] bytes );

bytes

The byte array to decode.

Return Value:

A string containing the decoded representation of the specified byte array.

Exceptions

Exception Type	Condition
ArgumentNullException	The bytes parameter is null.

Encoding.GetString assumes that the byte array contains all the bytes necessary to produce whole characters. If your bytes might be in multiple byte arrays (that is, the bytes corresponding to a single character might be at the end of one byte array and the beginning of another), use the Decoder class, which will maintain state between multiple calls.

The following code example demonstrates how to read a UTF8 encoded string from binary file.

    private string ReadAuthor(Stream binary_file) {
      System.Text.Encoding encoding = System.Text.Encoding.UTF8;
      // Read string from binary file with UTF8 encoding
      byte[] buffer = new byte[30];
      binary_file.Read(buffer, 0, 30);
      return encoding.GetString(buffer);
    }

    

Return to top

Summary

Returns a string containing the decoded representation of a range of bytes in a byte array.

C# Syntax:

public virtual string GetString(    byte[] bytes,    int index,    int count );

bytes

The byte array to decode.

index

The starting index of the byte array to decode.

count

The number of bytes to decode.

Return Value:

A string containing the decoded representation of a range of bytes in the specified byte array.

Exceptions

Exception Type	Condition
ArgumentNullException	The bytes parameter is null.
ArgumentOutOfRangeException	The index and count parameters do not denote a valid range in the byte array.

Encoding.GetString assumes that the byte array contains all the bytes necessary to produce whole characters. If your bytes might be in multiple byte arrays (that is, the bytes corresponding to a single character might be at the end of one byte array and the beginning of another), use the Decoder class, which will maintain state between multiple calls.

The following code example demonstrates how to read a UTF8 encoded string from binary file.

    private string ReadAuthor(Stream binary_file) {
      System.Text.Encoding encoding = System.Text.Encoding.UTF8;
      // Read string from binary file with UTF8 encoding
      byte[] buffer = new byte[30];
      binary_file.Read(buffer, 0, 30);
      return encoding.GetString(buffer);
    }

    

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