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 231 code positions, divided into 128 groups of 256 planes. Each plane contains 216 code positions. UCS-2 is a two-byte (16-bit) encoding containing the 216 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 221 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


UnicodeEncoding() Constructor

public UnicodeEncoding();

Summary

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

UnicodeEncoding(bool, bool) Constructor

public UnicodeEncoding(bool bigEndian, bool byteOrderMark);

Summary

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

UnicodeEncoding.Equals Method

public override bool Equals(object value);

Summary

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

UnicodeEncoding.GetByteCount(char[], int, int) Method

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

Summary

Determines the exact number of bytes required to encode the specified range of the specified array of characters as Unicode-encoded characters.

Parameters

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 - 1 as Unicode-encoded characters.

Exceptions

Exception TypeCondition
ArgumentNullExceptionchars is null .
ArgumentOutOfRangeExceptionindex < 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

UnicodeEncoding.GetByteCount(System.String) Method

public override int GetByteCount(string s);

Summary

Returns the number of bytes required to encode the specified string as Unicode-encoded characters.

Parameters

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 TypeCondition
ArgumentNullExceptions is null .

Description

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

See Also

System.Text.UnicodeEncoding Class, System.Text Namespace

UnicodeEncoding.GetBytes(System.String, int, int, byte[], int) Method

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

Summary

Encodes the specified range of the specified string into the specified range of the specified array of bytes as Unicode-encoded characters.

Parameters

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 TypeCondition
ArgumentExceptionbytes does not contain sufficient space to store the encoded characters.

ArgumentNullExceptions is null .

-or-

bytes is null .

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

UnicodeEncoding.GetBytes(System.String) Method

public override byte[] GetBytes(string s);

Summary

Encodes the specified string as Unicode-encoded characters.

Parameters

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 TypeCondition
ArgumentNullExceptions is null .

Description

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

See Also

System.Text.UnicodeEncoding Class, System.Text Namespace

UnicodeEncoding.GetBytes(char[], int, int, byte[], int) Method

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

Summary

Encodes the specified range of the specified character array into the specified range of the specified byte array as Unicode-encoded characters.

Parameters

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 TypeCondition
ArgumentExceptionbytes does not contain sufficient space to store the encoded characters.

ArgumentNullExceptionchars is null .

-or-

bytes is null .

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

UnicodeEncoding.GetCharCount Method

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

Summary

Determines the exact number of characters that will be produced by decoding the specified range of the specified array of bytes as Unicode-encoded characters.

Parameters

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 TypeCondition
ArgumentNullExceptionbytes is null .
ArgumentOutOfRangeExceptionindex < 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

UnicodeEncoding.GetChars Method

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

Summary

Decodes the specified range of the specified array of bytes into the specified range of the specified array of characters as Unicode-encoded characters.

Parameters

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 TypeCondition
ArgumentExceptionchars does not contain sufficient space to store the decoded characters.

ArgumentNullExceptionchars is null .

-or-

bytes is null .

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

UnicodeEncoding.GetDecoder Method

public override Decoder GetDecoder();

Summary

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

UnicodeEncoding.GetHashCode Method

public override int GetHashCode();

Summary

Generates a hash code for the current instance.

Return Value

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

UnicodeEncoding.GetMaxByteCount Method

public override int GetMaxByteCount(int charCount);

Summary

Returns the maximum number of bytes required to encode the specified number of characters as Unicode-encoded characters, regardless of the actual character values.

Parameters

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

UnicodeEncoding.GetMaxCharCount Method

public override int GetMaxCharCount(int byteCount);

Summary

Returns the maximum number of characters produced by decoding the specified number of bytes as Unicode-encoded characters, regardless of the actual byte values.

Parameters

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

UnicodeEncoding.GetPreamble Method

public override byte[] GetPreamble();

Summary

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