System.Text.UnicodeEncoding Class

Summary

Represents a UTF-16 encoding of Unicode characters.

C# Syntax:

[Serializable] public class UnicodeEncoding : Encoding

This class encodes Unicode characters in Unicode Transformation Format, 16-bit encoding form (UTF-16); that is, the character is encoded in a 16-bit field consisting of two consecutive bytes. An extension mechanism, using pairs of fields called surrogates, enables another 2 ²⁰ characters to be encoded.

The two bytes of an encoded character are stored in either little-endian or big-endian byte order depending on the computer architecture. In big-endian architectures the most significant byte is written and read first, while in little-endian architectures the least significant byte is written and read first.

A UTF-16 encoding can be prefixed by a byte order mark (U+FEFF) to indicate the byte order used. It is assumed that the encoding is big-endian if the byte order mark is hexadecimal 0xFEFF, and little-endian if the byte order mark is hexadecimal 0xFFFE. (A byte order mark can also precede files encoded in UTF-8 format, but in that case the byte order mark just indicates UTF-8 encoding; it does not indicate byte order. For more information, see the UTF8Encoding class.)

This class contains a constructor, UnicodeEncoding.#ctor, that can specify whether an encoding is little-endian or big-endian, and whether a byte order mark is used.

This class contains the UnicodeEncoding.GetCharCount method that reports the number of Unicode characters that result from decoding an array of bytes, and the UnicodeEncoding.GetChars method that actually decodes an array of bytes. The UnicodeEncoding.GetByteCount method reports the number of bytes that result from encoding strings or arrays of Unicode characters, and the UnicodeEncoding.GetBytes method actually encodes characters into an array of bytes.

The UnicodeEncoding.GetDecoder method obtains an object to decode bytes. The UnicodeEncoding.GetPreamble method can obtain an encoded Unicode byte order mark.

For more information about Unicode, see the Unicode Standard at www.unicode.org.

This class implements the Encoding abstract base class.

System.Text Namespace

System.Text.UnicodeEncoding Member List:

Public 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 UnicodeEncoding class.
ctor #2	Overloaded: .ctor(bool bigEndian, bool byteOrderMark) Initializes a new instance of the UnicodeEncoding class, specifying whether to support little-endian or big-endian byte ordering and the Unicode byte order mark.

Public Fields

CharSize

Represents the Unicode version 2.0 character size in bytes.

Public Properties

BodyName (inherited from System.Text.Encoding)	Read-only See base class member description: System.Text.Encoding.BodyName Gets the name for this encoding that can be used with mail agent body tags.
CodePage (inherited from System.Text.Encoding)	Read-only See base class member description: System.Text.Encoding.CodePage When overridden in a derived class, gets the code page identifier of this encoding.
EncodingName (inherited from System.Text.Encoding)	Read-only See base class member description: System.Text.Encoding.EncodingName Gets the human-readable description of the encoding.
HeaderName (inherited from System.Text.Encoding)	Read-only See base class member description: System.Text.Encoding.HeaderName Gets the name for this encoding that can be used with mail agent header tags.
IsBrowserDisplay (inherited from System.Text.Encoding)	Read-only See base class member description: System.Text.Encoding.IsBrowserDisplay Gets an indication whether this encoding can be used for display by browser clients.
IsBrowserSave (inherited from System.Text.Encoding)	Read-only See base class member description: System.Text.Encoding.IsBrowserSave Gets an indication whether this encoding can be used for saving by browser clients.
IsMailNewsDisplay (inherited from System.Text.Encoding)	Read-only See base class member description: System.Text.Encoding.IsMailNewsDisplay Gets and indication whether this encoding can be used for display by mail and news clients.
IsMailNewsSave (inherited from System.Text.Encoding)	Read-only See base class member description: System.Text.Encoding.IsMailNewsSave Gets an indication whether this encoding can be used for saving by mail and news clients.
WebName (inherited from System.Text.Encoding)	Read-only See base class member description: System.Text.Encoding.WebName Gets the name registered with the Internet Assigned Numbers Authority (IANA) for this encoding.
WindowsCodePage (inherited from System.Text.Encoding)	Read-only See base class member description: System.Text.Encoding.WindowsCodePage Gets the Windows operating system code page that most closely corresponds to this encoding.

Public Methods

Equals	Overridden: Returns a value indicating whether this instance is equal to a specified object.
GetByteCount (inherited from System.Text.Encoding)	Overloaded: GetByteCount(char[] chars) See base class member description: System.Text.Encoding.GetByteCount Calculates the number of bytes required to encode a specified character array.
GetByteCount	Overloaded: GetByteCount(string s) Overridden: Calculates the number of bytes required to store the results of encoding the characters from a specified String.
GetByteCount	Overloaded: GetByteCount(char[] chars, int index, int count) Overridden: Calculates the number of bytes required to store the results of encoding a set of characters from a specified Unicode character array.
GetBytes (inherited from System.Text.Encoding)	Overloaded: GetBytes(char[] chars) See base class member description: System.Text.Encoding.GetBytes Encodes a specified character array into a byte array.
GetBytes	Overloaded: GetBytes(string s) Overridden: Encodes the characters from a specified String and returns the results in a byte array.
GetBytes (inherited from System.Text.Encoding)	Overloaded: GetBytes(char[] chars, int index, int count) See base class member description: System.Text.Encoding.GetBytes 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) Overridden: Encodes a specified range of elements from a Unicode character array and stores the results into a specified range of elements in a byte array.
GetBytes	Overloaded: GetBytes(string s, int charIndex, int charCount, byte[] bytes, int byteIndex) Overridden: Encodes a specified range of characters from a String and stores the results into a specified range of elements in a byte array.
GetCharCount (inherited from System.Text.Encoding)	Overloaded: GetCharCount(byte[] bytes) See base class member description: System.Text.Encoding.GetCharCount Calculates the number of characters produced by decoding an array of bytes.
GetCharCount	Overloaded: GetCharCount(byte[] bytes, int index, int count) Overridden: Calculates the number of characters that would result from decoding a specified range of elements in a byte array.
GetChars (inherited from System.Text.Encoding)	Overloaded: GetChars(byte[] bytes) See base class member description: System.Text.Encoding.GetChars Decodes a byte array into an array of characters.
GetChars (inherited from System.Text.Encoding)	Overloaded: GetChars(byte[] bytes, int index, int count) See base class member description: System.Text.Encoding.GetChars 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) Overridden: Decodes a range of elements from a specified byte array and stores them as elements in a specified Unicode character array.
GetDecoder	Overridden: Obtains a decoder that can convert a UTF-16 encoded sequence of bytes into a sequence of characters.
GetEncoder (inherited from System.Text.Encoding)	See base class member description: System.Text.Encoding.GetEncoder An Encoder for this encoding.
GetHashCode	Overridden: Returns the hash code for this instance.
GetMaxByteCount	Overridden: Calculates the maximum number of bytes required to encode a specified number of characters.
GetMaxCharCount	Overridden: Calculates the maximum number of characters that can result from decoding a specified number of bytes.
GetPreamble	Overridden: Returns a Unicode byte order mark encoded in big-endian or little-endian format, if the constructor for this instance requested byte order mark support.
GetString (inherited from System.Text.Encoding)	Overloaded: GetString(byte[] bytes) See base class member description: System.Text.Encoding.GetString Returns a string containing the decoded representation of the specified byte array.
GetString (inherited from System.Text.Encoding)	Overloaded: GetString(byte[] bytes, int index, int count) See base class member description: System.Text.Encoding.GetString 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 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.UnicodeEncoding

System.Text.UnicodeEncoding Member Details

Summary

Initializes a new instance of the UnicodeEncoding class.

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

C# Syntax:

public UnicodeEncoding();

By default, this constructor requests little-endian byte ordering and byte order mark support.

Return to top

Summary

Initializes a new instance of the UnicodeEncoding class, specifying whether to support little-endian or big-endian byte ordering and the Unicode byte order mark.

C# Syntax:

public UnicodeEncoding(    bool bigEndian,    bool byteOrderMark );

bigEndian

true to support big-endian byte ordering when encoding, or false to support little-endian byte ordering.

byteOrderMark

true to include the Unicode byte order mark when encoding, or false to not include the Unicode byte order mark.

The byteOrderMark parameter is used to determine the return value of the UnicodeEncoding.GetPreamble method.

Return to top

Summary

Represents the Unicode version 2.0 character size in bytes.

C# Syntax:

public const int CharSize;

The value of this field is a 32-bit signed constant, with a value of two.

Return to top

Inherited
See base class member description: System.Text.Encoding.BodyName

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

Inherited
See base class member description: System.Text.Encoding.CodePage

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

Inherited
See base class member description: System.Text.Encoding.EncodingName

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

Inherited
See base class member description: System.Text.Encoding.HeaderName

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

Inherited
See base class member description: System.Text.Encoding.IsBrowserDisplay

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

Inherited
See base class member description: System.Text.Encoding.IsBrowserSave

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

Inherited
See base class member description: System.Text.Encoding.IsMailNewsDisplay

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

Inherited
See base class member description: System.Text.Encoding.IsMailNewsSave

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

Inherited
See base class member description: System.Text.Encoding.WebName

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

Inherited
See base class member description: System.Text.Encoding.WindowsCodePage

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

Returns a value indicating whether this instance is equal to a specified object.

C# Syntax:

public override bool Equals(    object value );

value

An object to compare with this instance or null.

Return Value:

true if value is an instance of UnicodeEncoding and equals the value of this instance; otherwise, false.

Return to top

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

C# Syntax:

~UnicodeEncoding();

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

Return to top

Inherited
See base class member description: System.Text.Encoding.GetByteCount

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 store the results of encoding the characters from a specified String.

C# Syntax:

public override int GetByteCount(    string s );

s

The String to encode.

Return Value:

The number of bytes required to encode the characters in s.

Exceptions

Exception Type	Condition
ArgumentNullException	s is null.
ArgumentException	Return value is greater than Int32.MaxValue. -or- s contains an invalid Unicode surrogate pair.

Use UnicodeEncoding.GetByteCount to calculate exactly, or UnicodeEncoding.GetMaxByteCount to calculate at most, the array size required by the UnicodeEncoding.GetBytes method to store encoded characters.

Return to top

Summary

Calculates the number of bytes required to store the results of encoding a set of characters from a specified Unicode character array.

C# Syntax:

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

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.

Return Value:

The number of bytes required to encode the range in chars from index to index + count.

Exceptions

Exception Type	Condition
ArgumentException	Return value is greater than Int32.MaxValue. -or- chars contains an invalid Unicode surrogate pair.
ArgumentNullException	chars is null.
ArgumentOutOfRangeException	index is less than zero. -or- count is less than zero. -or- index plus count is greater than the length of chars.

Use UnicodeEncoding.GetByteCount to calculate exactly, or UnicodeEncoding.GetMaxByteCount to calculate at most, the array size required by the UnicodeEncoding.GetBytes method to store encoded characters.

Return to top

Inherited
See base class member description: System.Text.Encoding.GetBytes

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 the characters from a specified String and returns the results in a byte array.

C# Syntax:

public override byte[] GetBytes(    string s );

s

The string of characters to encode.

Return Value:

A byte array that contains the encoded characters from s.

Exceptions

Exception Type	Condition
ArgumentNullException	s is null.
ArgumentException	An invalid high or low member of a surrogate pair encountered during encoding.

Return to top

Inherited
See base class member description: System.Text.Encoding.GetBytes

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

Encodes a specified range of elements from a Unicode character array and stores the results into a specified range of elements in a byte array.

C# Syntax:

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

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 encoded results are stored.

byteIndex

The index of the first element in bytes where the encoded results are stored.

Return Value:

The number of bytes stored in bytes.

Exceptions

Exception Type	Condition
ArgumentNullException	chars or bytes is null.
ArgumentOutOfRangeException	charIndex, charCount or byteIndex is less than zero. -or- The sum of charIndex and charCount is greater than the length of chars. -or- byteIndex is greater than the length of bytes.
ArgumentException	byteIndex is equal to the length of bytes. -or- No bytes have been stored into bytes.
ArgumentException	An invalid high or low member of a surrogate pair encountered during encoding.

Use UnicodeEncoding.GetByteCount to calculate exactly, or UnicodeEncoding.GetMaxByteCount to calculate at most, the array size required by the UnicodeEncoding.GetBytes method to store encoded characters.

Return to top

Summary

Encodes a specified range of characters from a String and stores the results into a specified range of elements in a byte array.

C# Syntax:

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

s

The string of characters to encode.

charIndex

The index of the first character in s to encode.

charCount

The number of characters to encode.

bytes

The byte array where the encoded results are stored.

byteIndex

The index of the first element in bytes where the encoded results are stored.

Return Value:

The number of bytes stored in bytes.

Exceptions

Exception Type	Condition
ArgumentNullException	s or bytes is null.
ArgumentOutOfRangeException	charIndex, charCount or byteIndex is less than zero. -or- The sum of charIndex and charCount is greater than the length of s. -or- byteIndex is greater than the length of bytes.
ArgumentException	byteIndex is equal to the length of bytes. -or- No bytes have been stored into bytes.
ArgumentException	An invalid high or low member of a surrogate pair encountered during encoding.

Use UnicodeEncoding.GetByteCount to calculate exactly, or UnicodeEncoding.GetMaxByteCount to calculate at most, the array size required by the UnicodeEncoding.GetBytes method to store encoded characters.

Return to top

Inherited
See base class member description: System.Text.Encoding.GetCharCount

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

Calculates the number of characters that would result from decoding a specified range of elements in a byte array.

C# Syntax:

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

bytes

The byte array to decode.

index

The index of the first byte in bytes to decode.

count

The number of bytes to decode.

Return Value:

The number of characters that would result from decoding the specified range of elements in bytes.

Exceptions

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

Use UnicodeEncoding.GetCharCount to calculate exactly, or UnicodeEncoding.GetMaxCharCount to calculate at most, the array size required by the UnicodeEncoding.GetChars method to store decoded characters.

Return to top

Inherited
See base class member description: System.Text.Encoding.GetChars

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

Inherited
See base class member description: System.Text.Encoding.GetChars

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

Decodes a range of elements from a specified byte array and stores them as elements in a specified Unicode character array.

C# Syntax:

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

bytes

The byte array to decode.

byteIndex

The index of the first element in bytes to decode.

byteCount

The number of elements to decode.

chars

The character array in which the decoded results are stored.

charIndex

The index of the first element in chars to store decoded results.

Return Value:

The number of characters stored in chars.

Exceptions

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

Use UnicodeEncoding.GetCharCount to calculate exactly, or UnicodeEncoding.GetMaxCharCount to calculate at most, the array size required by the UnicodeEncoding.GetChars method to store decoded characters.

Return to top

Summary

Obtains a decoder that can convert a UTF-16 encoded sequence of bytes into a sequence of characters.

C# Syntax:

public override Decoder GetDecoder();

Return Value:

A Decoder.

The Decoder.GetChars method converts adjacent blocks of bytes into adjacent blocks of characters, in a manner similar to the UnicodeEncoding.GetChars method. However, a Decoder maintains state information between calls so it can correctly decode byte sequences that span blocks.

Return to top

Inherited
See base class member description: System.Text.Encoding.GetEncoder

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 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

Calculates the maximum number of bytes required to encode a specified number of characters.

C# Syntax:

public override int GetMaxByteCount(    int charCount );

charCount

The number of characters to encode.

Return Value:

The maximum number of bytes required to encode charCount number of characters.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	charCount is less than zero. -or- Return value is greater than Int32.MaxValue.

Use UnicodeEncoding.GetByteCount to calculate exactly, or UnicodeEncoding.GetMaxByteCount to calculate at most, the array size required by the UnicodeEncoding.GetBytes method to store encoded characters.

Return to top

Summary

Calculates the maximum number of characters that can result from decoding a specified number of bytes.

C# Syntax:

public override int GetMaxCharCount(    int byteCount );

byteCount

The number of bytes to decode.

Return Value:

The maximum number of characters that can result from decoding byteCount number of bytes.

Use UnicodeEncoding.GetCharCount to calculate exactly, or UnicodeEncoding.GetMaxCharCount to calculate at most, the array size required by the UnicodeEncoding.GetChars method to store decoded characters.

Return to top

Summary

Returns a Unicode byte order mark encoded in big-endian or little-endian format, if the constructor for this instance requested byte order mark support.

C# Syntax:

public override byte[] GetPreamble();

Return Value:

If the constructor for this instance did not request byte order mark support, that is the byteOrderMark parameter of the UnicodeEncoding.#ctor constructor is false, then a byte array of length zero.

Otherwise, if the constructor requested big-endian byte order mark support then a byte array whose elements contain hexadecimal 0xFE, 0xFF; or if the constructor requested little-endian byte order mark support then a byte array whose elements contain hexadecimal 0xFF, 0xFE.

The byte order mark (U+FEFF), when concatenated to the beginning of a UTF-16 encoding, enables a class like StreamReader to deduce whether the remainder of the encoding is in big-endian or little-endian format.

Concatenate this return value to the beginning of a UTF-16 encoding if the constructor for this instance requested support for a byte order mark.

Return to top

Inherited
See base class member description: System.Text.Encoding.GetString

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

Inherited
See base class member description: System.Text.Encoding.GetString

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