System.Text.UnicodeEncoding Class

public class UnicodeEncoding : Encoding

Base Types

Object
  Encoding
    UnicodeEncoding

Assembly

mscorlib

Library

BCL

Summary

Represents a Unicode implementation of Encoding.

Description

UnicodeEncoding encodes each Unicode character in UTF-16, i.e. as two consecutive bytes. Both little-endian and big-endian encodings are supported.

[Note: On little-endian platforms such as Intel machines, it is generally more efficient to store Unicode characters in little-endian. However, many other platforms can store Unicode characters in big-endian. Unicode files can be distinguished by the presence of the byte order mark (U+FEFF), which is written as either 0xfe 0xff or 0xff 0xfe.

This Encoding implementation can detect a byte order mark automatically and switch byte orders, based on a parameter specified in the constructor.

ISO/IEC 10646 defines UCS-2 and UCS-4. UCS-4 is a four-byte (32-bit) encoding containing 2³¹ code positions, divided into 128 groups of 256 planes. Each plane contains 2¹⁶ code positions. UCS-2 is a two-byte (16-bit) encoding containing the 2¹⁶ code positions of UCS-4 for which the upper two bytes are zero, known as Plane Zero or the Basic Multilingual Plane (BMP). For example, the code position for LATIN CAPITAL LETTER A in UCS-4 is 0x00000041 whereas in UCS-2 it is 0x0041.

ISO/IEC 10646 also defines UTF-16, which stands for "UCS Transformation Format for 16 Planes of Group 00". UTF-16 is a two byte encoding that uses an extension mechanism to represent 2²¹ code positions. UTF-16 represents code positions in Plane Zero by its UCS-2 code value and code positions in Planes 1 through 16 by a pair of special code values, called surrogates. UTF-16 is equivalent to the Unicode Standard. For a detailed description of UTF-16 and surrogates, see "The Unicode Standard Version 3.0" Appendix C.

]

See Also

System.Text Namespace

Members

UnicodeEncoding Constructors

UnicodeEncoding() Constructor
UnicodeEncoding(bool, bool) Constructor

UnicodeEncoding Methods

UnicodeEncoding.Equals Method
UnicodeEncoding.GetByteCount(char[], int, int) Method
UnicodeEncoding.GetByteCount(System.String) Method
UnicodeEncoding.GetBytes(System.String, int, int, byte[], int) Method
UnicodeEncoding.GetBytes(System.String) Method
UnicodeEncoding.GetBytes(char[], int, int, byte[], int) Method
UnicodeEncoding.GetCharCount Method
UnicodeEncoding.GetChars Method
UnicodeEncoding.GetDecoder Method
UnicodeEncoding.GetHashCode Method
UnicodeEncoding.GetMaxByteCount Method
UnicodeEncoding.GetMaxCharCount Method
UnicodeEncoding.GetPreamble Method

Constructs and initializes a new instance of the UnicodeEncoding class.

Description

The new instance uses little-endian encoding and includes the Unicode byte-order mark in conversions.

See Also

System.Text.UnicodeEncoding Class, System.Text Namespace

Constructs and initializes a new instance of the UnicodeEncoding class using the specified Boolean flags.

Parameters

bigEndian

A Boolean value that specifies the byte-ordering to use for the new instance. Specify true to use big-endian ordering; specify false to use little-endian ordering.

byteOrderMark

A Boolean value that specifies whether to include the Unicode byte order mark in translated strings. Specify true to include the Unicode byte-order mark; otherwise, specify false .

See Also

System.Text.UnicodeEncoding Class, System.Text Namespace

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

Parameters

value

The Object to compare to the current instance.

Return Value

true if value represents the same type and value as the current instance. If value is a null reference or is not an instance of UnicodeEncoding, returns false .

Description

[Note: This method overrides System.Object.Equals(System.Object).]

See Also

System.Text.UnicodeEncoding Class, System.Text Namespace

chars

A Char array to encode as Unicode-encoded characters.

index

A Int32 that specifies the first index of chars to encode.

count

A Int32 that specifies the number of elements in chars to encode.

Return Value

A Int32 whose value equals the number of bytes required to encode the range in chars from index to index + count as Unicode-encoded characters.

Exceptions

Exception Type	Condition
ArgumentNullException	chars is null .
ArgumentOutOfRangeException	index < 0. -or- count < 0. -or- index and count do not specify a valid range in chars (i.e. ( index + count) > chars.Length).

Description

[Note: This method overrides System.Text.Encoding.GetByteCount(System.Char[]).]

See Also

System.Text.UnicodeEncoding Class, System.Text Namespace

s

A String to encode as Unicode-encoded characters.

Return Value

A Int32 containing the number of bytes needed to encode s as Unicode-encoded characters.

Exceptions

Exception Type	Condition
ArgumentNullException	s is null .

Description

[Note: This method overrides System.Text.Encoding.GetByteCount(System.Char[]).]

See Also

System.Text.UnicodeEncoding Class, System.Text Namespace

s

A String to encode as Unicode-encoded characters.

charIndex

A Int32 that specifies the first index of s from which to encode.

charCount

A Int32 that specifies the number of elements in s to encode.

bytes

A Byte array to encode into.

byteIndex

A Int32 that specifies the first index of bytes to encode into.

Return Value

A Int32 whose value equals the number of bytes encoded into bytes as Unicode-encoded characters.

Exceptions

Exception Type	Condition
ArgumentException	bytes does not contain sufficient space to store the encoded characters.
ArgumentNullException	s is null . -or- bytes is null .
ArgumentOutOfRangeException	charIndex < 0. -or- charCount < 0. -or- byteIndex < 0. -or- charIndex and charCount do not specify a valid range in s (i.e. (charIndex + charCount) > s.Length). -or- byteIndex > bytes.Length.

Description

[Note: This method overrides System.Text.Encoding.GetBytes(System.Char[]).]

See Also

System.Text.UnicodeEncoding Class, System.Text Namespace

s

A String to encode as Unicode-encoded characters.

Return Value

A Byte array containing the encoded representation of s as Unicode-encoded characters.

Exceptions

Exception Type	Condition
ArgumentNullException	s is null .

Description

[Note: This method overrides System.Text.Encoding.GetBytes(System.Char[]).]

See Also

System.Text.UnicodeEncoding Class, System.Text Namespace

chars

A Char array of characters to encode as Unicode-encoded characters.

charIndex

A Int32 that specifies the first index of chars to encode.

charCount

A Int32 that specifies the number of elements in chars to encode.

bytes

A Byte array to encode into.

byteIndex

A Int32 that specifies the first index of bytes to encode into.

Return Value

A Int32 containing the number of bytes encoded into bytes as Unicode-encoded characters.

Exceptions

Exception Type	Condition
ArgumentException	bytes does not contain sufficient space to store the encoded characters.
ArgumentNullException	chars is null . -or- bytes is null .
ArgumentOutOfRangeException	charIndex < 0. -or- charCount < 0. -or- byteIndex < 0. -or- charIndex and charCount do not specify a valid range in chars (i.e. ( charIndex + charCount ) > chars.Length). -or- byteIndex > bytes.Length.

Description

[Note: This method overrides System.Text.Encoding.GetBytes(System.Char[]).

System.Text.UnicodeEncoding.GetByteCount(System.Char[],System.Int32,System.Int32) can be used to determine the exact number of bytes that will be produced for a given range of characters. Alternatively, System.Text.UnicodeEncoding.GetMaxByteCount(System.Int32) 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.

]

See Also

System.Text.UnicodeEncoding Class, System.Text Namespace

bytes

A Byte array to decode as Unicode-encoded characters.

index

A Int32 that specifies the first index in bytes to decode.

count

A Int32 that specifies the number of elements in bytes to decode.

Return Value

A Int32 whose value equals the number of characters a call to System.Text.UnicodeEncoding.GetChars(System.Byte[],System.Int32,System.Int32,System.Char[],System.Int32) will produce if presented with the specified range of bytes as Unicode-encoded characters.

Exceptions

Exception Type	Condition
ArgumentNullException	bytes is null .
ArgumentOutOfRangeException	index < 0. -or- count < 0. -or- index and count do not specify a valid range in bytes (i.e. (index + count) > bytes.Length).

Description

[Note: This method overrides System.Text.Encoding.GetCharCount(System.Byte[]).]

See Also

System.Text.UnicodeEncoding Class, System.Text Namespace

bytes

A Byte array to decode as Unicode-encoded characters.

byteIndex

A Int32 that specifies the first index of bytes from which to decode.

byteCount

A Int32 that specifies the number of elements in bytes to decode.

chars

A Char array to decode into.

charIndex

A Int32 that specifies the first index of chars to store the decoded bytes.

Return Value

A Int32 containing the number of characters decoded into chars as Unicode-encoded characters.

Exceptions

Exception Type	Condition
ArgumentException	chars does not contain sufficient space to store the decoded characters.
ArgumentNullException	chars is null . -or- bytes is null .
ArgumentOutOfRangeException	byteIndex < 0. -or- byteCount < 0. -or- charIndex < 0. -or- byteIndex and byteCount do not specify a valid range in bytes (i.e. (byteIndex + byteCount ) > bytes.Length). -or- charIndex > chars.Length.

Description

[Note: This method overrides System.Text.Encoding.GetChars(System.Byte[]).

System.Text.UnicodeEncoding.GetCharCount(System.Byte[],System.Int32,System.Int32) can be used to determine the exact number of characters that will be produced for a given range of bytes. Alternatively, System.Text.UnicodeEncoding.GetMaxCharCount(System.Int32) 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.

]

See Also

System.Text.UnicodeEncoding Class, System.Text Namespace

Returns a Decoder object for the current instance.

Return Value

A Decoder object for the current instance.

Description

[Note: This method overrides System.Text.Encoding.GetDecoder.

Unlike the System.Text.UnicodeEncoding.GetChars(System.Byte[],System.Int32,System.Int32,System.Char[],System.Int32) method, the System.Text.Decoder.GetChars(System.Byte[],System.Int32,System.Int32,System.Char[],System.Int32) method provided by a Decoder object can convert partial sequences of bytes into partial sequences of characters by maintaining the appropriate state between the conversions.

This implementation returns a decoder that simply forwards calls to System.Text.UnicodeEncoding.GetCharCount(System.Byte[],System.Int32,System.Int32) and System.Text.UnicodeEncoding.GetChars(System.Byte[],System.Int32,System.Int32,System.Char[],System.Int32) to the corresponding methods of the current instance. It is recommended that encoding implementations that requires state to be maintained between successive conversions override this method and return an instance of an appropriate decoder implementation.

]

See Also

System.Text.UnicodeEncoding Class, System.Text Namespace

A Int32 containing the hash code for the current instance.

Description

The algorithm used to generate the hash code is unspecified.

[Note: This method overrides System.Object.GetHashCode.]

See Also

System.Text.UnicodeEncoding Class, System.Text Namespace

charCount

A Int32 whose value represents a number of characters to encode as Unicode-encoded characters.

Return Value

A Int32 containing the maximum number of bytes required to encode charCount characters as Unicode-encoded characters.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	charCount < 0.

Description

[Note: This method overrides System.Text.Encoding.GetMaxByteCount(System.Int32).

Use this method to determine an appropriate minimum buffer size for byte arrays passed to System.Text.UnicodeEncoding.GetBytes(System.Char[],System.Int32,System.Int32,System.Byte[],System.Int32) or System.Text.Encoder.GetBytes(System.Char[],System.Int32,System.Int32,System.Byte[],System.Int32,System.Boolean) for the current instance. Using this minimum buffer size can help ensure that buffer overflow exceptions do not occur.

]

See Also

System.Text.UnicodeEncoding Class, System.Text Namespace

byteCount

A Int32 specifies the number of bytes to decode as Unicode-encoded characters.

Return Value

A Int32 containing the maximum number of characters that would be produced by decoding byteCount bytes as Unicode-encoded characters.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	byteCount < 0.

Description

[Note: This method overrides System.Text.Encoding.GetMaxCharCount(System.Int32).

Use this method to determine an appropriate minimum buffer size for byte arrays passed to System.Text.UnicodeEncoding.GetChars(System.Byte[],System.Int32,System.Int32,System.Char[],System.Int32) or System.Text.Encoding.GetChars(System.Byte[]) for the current instance. Using this minimum buffer size can help ensure that no buffer overflow exceptions will occur.

]

See Also

System.Text.UnicodeEncoding Class, System.Text Namespace

Returns the bytes used at the beginning of a Stream instance to determine which Encoding implementation the stream was created with.

Return Value

A Byte array that identifies the Encoding implementation used to create a Stream .

Description

System.Text.UnicodeEncoding.GetPreamble returns the Unicode byte order mark (U+FEFF) in either big-endian or little-endian order, according the ordering that the current instance was initialized with.

[Note: This method overrides System.Text.Encoding.GetPreamble.]

See Also

System.Text.UnicodeEncoding Class, System.Text Namespace