System.Text.UTF8Encoding Class

Assembly: Mscorlib.dll
Namespace: System.Text
Summary
Represents a UTF-8 encoding of Unicode characters.
C# Syntax:
[Serializable]
public class UTF8Encoding : Encoding
Remarks
This class encodes Unicode characters using UCS Transformation Format, 8-bit form (UTF-8). This encoding supports all Unicode character values and surrogates. For more information regarding surrogate pairs, see UnicodeCategory.

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

The UTF8Encoding.GetDecoder method obtains an object to convert (decode) UTF-8 encoded bytes into Unicode characters, while the UTF8Encoding.GetEncoder method obtains an object to convert (encode) Unicode characters into UTF-8 encoded bytes. The UTF8Encoding.GetPreamble method can obtain a Unicode byte order mark, which when prefixed to a series of bytes, indicates how those bytes are encoded.

UTF-8 encodes Unicode characters with a variable number of bytes per character. This encoding is optimized for the lower 127 ASCII characters, yielding an efficient mechanism to encode English in an international way. The UTF-8 identifier is the Unicode byte order mark, hexadecimal 0xFEFF, which is represented in UTF-8 as hexadecimal 0xEF 0xBB 0xBF. The byte order mark is used to distinguish UTF-8 text from other encodings.

This class offers an error detection feature that can be turned on when an instance of the class is constructed. Certain methods in this class check for invalid sequences of surrogate pairs. If error detection is turned on and an invalid sequence is found, ArgumentException is thrown. If error detection is not turned on and an invalid sequence is found, no exception is thrown and execution continues in a manner defined by that method.

The error detection feature also works during decoding operations. If error detection is on and an invalid byte sequence is found, ArgumentException is thrown. Examples of invalid byte sequence are invalid leading or trailing UTF-8 bytes, UTF-8 byte sequence consisting of more than four bytes, and the non-shortest form as defined in Unicode 3.0.1. When error detection is off, invalid bytes are discarded.

This class inherits from the Encoding class.

See also:
System.Text Namespace | Decoder | Encoder

System.Text.UTF8Encoding 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 UTF8Encoding class.
ctor #2 Overloaded:
.ctor(bool encoderShouldEmitUTF8Identifier)

 Initializes a new instance of the UTF8Encoding class. A parameter specifies whether to prefix an encoding with a Unicode byte order mark.
ctor #3 Overloaded:
.ctor(bool encoderShouldEmitUTF8Identifier, bool throwOnInvalidBytes)

 Initializes a new instance of the UTF8Encoding class. Parameters specify whether to prefix an encoding with a Unicode byte order mark, and whether to throw an exception when an invalid encoding is detected.
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 chars)

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 in 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 in 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 the result into a specified range of elements in a Unicode character array.
GetDecoder Overridden:
Obtains a decoder that can convert a UTF-8 encoded sequence of bytes into a sequence of Unicode characters.
GetEncoder Overridden:
Obtains an encoder that can convert a sequence of Unicode characters into a UTF-8 encoded sequence of bytes.
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 UTF-8 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.Text.UTF8Encoding Member Details

Overloaded ctor #1
Summary
Initializes a new instance of the UTF8Encoding class.

Default constructor. This constructor is called by derived class constructors to initialize state in this type.
C# Syntax:
public UTF8Encoding();
Remarks
By default, this constructor does not request that a Unicode byte order mark prefix encoded characters, and this constructor does not request an exception be thrown when an invalid encoding is detected.
See also:
UTF8Encoding.GetPreamble

Return to top

Overloaded ctor #2
Summary
Initializes a new instance of the UTF8Encoding class. A parameter specifies whether to prefix an encoding with a Unicode byte order mark.
C# Syntax:
public UTF8Encoding(
   bool encoderShouldEmitUTF8Identifier
);
Parameters:

encoderShouldEmitUTF8Identifier

true to specify that a Unicode byte order mark prefix be emitted when encoding; otherwise, false.

Remarks
By default, this constructor does not request an exception be thrown when an invalid encoding is detected.
See also:
UTF8Encoding.GetPreamble

Return to top

Overloaded ctor #3
Summary
Initializes a new instance of the UTF8Encoding class. Parameters specify whether to prefix an encoding with a Unicode byte order mark, and whether to throw an exception when an invalid encoding is detected.
C# Syntax:
public UTF8Encoding(
   bool encoderShouldEmitUTF8Identifier,
   bool throwOnInvalidBytes
);
Parameters:

encoderShouldEmitUTF8Identifier

true to specify that a Unicode byte order mark prefix be emitted when encoding; otherwise, false.

throwOnInvalidBytes

true to specify that an exception be thrown when an invalid encoding is detected; otherwise, false.

Remarks
If throwOnInvalidBytes is true, a method that detects an invalid byte sequence throws ArgumentException; otherwise, the method does not throw an exception and the invalid sequence is ignored.

Return to top

Property: BodyName (read-only)
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;}
Remarks
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

Property: CodePage (read-only)
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;}
Remarks
This property must be implemented or overridden.
See also:
Encoding.#ctor

Return to top

Property: EncodingName (read-only)
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;}
Remarks
An example of an Encoding.EncodingName is Hebrew (DOS) for code page 862.

Return to top

Property: HeaderName (read-only)
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;}
Remarks
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

Property: IsBrowserDisplay (read-only)
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;}
Remarks
For example, this property returns true for code page 1252 (windows-1252), but false for code page 437 (IBM-437).

Return to top

Property: IsBrowserSave (read-only)
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;}
Remarks
For example, this property returns true for code page 1252 (windows-1252), but false for code page 437 (IBM-437).

Return to top

Property: IsMailNewsDisplay (read-only)
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;}
Remarks
For example, this property returns true for code page 1252 (windows-1252), but false for code page 437 (IBM-437).

Return to top

Property: IsMailNewsSave (read-only)
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;}
Remarks
For example, this property returns true for code page 1252 (windows-1252), but false for code page 437 (IBM-437).

Return to top

Property: WebName (read-only)
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

Property: WindowsCodePage (read-only)
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

Overridden Method: Equals(
   object value
)
Summary
Returns a value indicating whether this instance is equal to a specified object.
C# Syntax:
public override bool Equals(
   object value
);
Parameters:

value

An object to compare with this instance or null.

Return Value:
true if value is an instance of UTF8Encoding and equals the value of this instance; otherwise, false.

Return to top

Method: Finalize()
Inherited
See base class member description: System.Object.Finalize
C# Syntax:
~UTF8Encoding();

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

Return to top

Overloaded Method: GetByteCount(
   char[] chars
)
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
);
Parameters:

chars

The character array to encode.

Return Value:
The number of bytes needed to encode chars.
Exceptions
Exception Type Condition
ArgumentNullException chars is null.
Remarks
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

Overloaded Method: GetByteCount(
   string chars
)
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 chars
);
Parameters:

chars

The String to encode.

Return Value:
The number of bytes required to encode the characters in chars.
Exceptions
Exception Type Condition
ArgumentNullException chars is null.
ArgumentException Return value is greater than Int32.MaxValue.

-or-

chars contains an invalid Unicode surrogate character.
Remarks
Use UTF8Encoding.GetByteCount to calculate exactly, or UTF8Encoding.GetMaxByteCount to calculate at most, the array size required by the UTF8Encoding.GetBytes method to store encoded characters.

If error detection is turned off and an invalid surrogate sequence is detected, the invalid characters are ignored and do not affect the return value, and no exception is thrown.

Return to top

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

chars

The Unicode character array to encode.

index

The index of the first character in chars to encode.

count

The number of characters to encode.

Return Value:
The number of bytes required to encode the range in chars from index to index + count.
Exceptions
Exception Type Condition
ArgumentNullException chars is null.
ArgumentOutOfRangeException index or count is less than zero.

-or-

index plus count is greater than the length of chars.

-or-

Return value overflowed.
ArgumentException chars contains an invalid sequence of characters and the UTF8Encoding.#ctor constructor for this instance specified throwing an exception when an invalid encoding is detected.
Remarks
Use UTF8Encoding.GetByteCount to calculate exactly, or UTF8Encoding.GetMaxByteCount to calculate at most, the array size required by the UTF8Encoding.GetBytes method to store encoded characters.

If error detection is turned off and an invalid surrogate sequence is detected, the invalid characters are ignored and do not affect the return value, and no exception is thrown.

Return to top

Overloaded Method: GetBytes(
   char[] chars
)
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
);
Parameters:

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.
See also:
Encoding.GetByteCount | Encoding.GetMaxByteCount | Encoding.GetDecoder | Encoding.GetEncoder

Return to top

Overloaded Method: GetBytes(
   string s
)
Summary
Encodes the characters from a specified String and returns the results in a byte array.
C# Syntax:
public override byte[] GetBytes(
   string s
);
Parameters:

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 was encountered during encoding.
Remarks
If error detection is turned off and an invalid surrogate sequence is detected, the invalid characters are ignored and are not encoded into the returned byte array, and no exception is thrown.
See also:
UTF8Encoding.GetByteCount | UTF8Encoding.GetMaxByteCount

Return to top

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

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.
See also:
Encoding.GetByteCount | Encoding.GetMaxByteCount | Encoding.GetDecoder | Encoding.GetEncoder

Return to top

Overloaded Method: GetBytes(
   char[] chars,
   int charIndex,
   int charCount,
   byte[] bytes,
   int byteIndex
)
Summary
Encodes a specified range of elements from a Unicode character array and stores the results in 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
);
Parameters:

chars

The character array to encode.

charIndex

The index of the first character in chars to encode.

charCount

The number of characters to encode.

bytes

The byte array where the 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 in bytes.

-or-

An invalid high or low member of a surrogate pair was encountered during encoding.
Remarks
Use UTF8Encoding.GetByteCount to calculate exactly, or UTF8Encoding.GetMaxByteCount to calculate at most, the array size required by the UTF8Encoding.GetBytes method to store encoded characters.

If error detection is turned off and an invalid surrogate sequence is detected, the invalid characters are ignored and do not affect the return value, and no exception is thrown.

See also:
UTF8Encoding.GetByteCount | UTF8Encoding.GetMaxByteCount

Return to top

Overloaded Method: GetBytes(
   string s,
   int charIndex,
   int charCount,
   byte[] bytes,
   int byteIndex
)
Summary
Encodes a specified range of characters from a String and stores the results in 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
);
Parameters:

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-

charIndex plus 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 in bytes.

-or-

An invalid high or low member of a surrogate pair was encountered during encoding.
Remarks
Use UTF8Encoding.GetByteCount to calculate exactly, or UTF8Encoding.GetMaxByteCount to calculate at most, the array size required by the UTF8Encoding.GetBytes method to store encoded characters.

If error detection is turned off and an invalid surrogate sequence is detected, the invalid characters are ignored and do not affect the return value, and no exception is thrown.

See also:
UTF8Encoding.GetByteCount | UTF8Encoding.GetMaxByteCount

Return to top

Overloaded Method: GetCharCount(
   byte[] bytes
)
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
);
Parameters:

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

Overloaded Method: GetCharCount(
   byte[] bytes,
   int index,
   int count
)
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
);
Parameters:

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 or count is less than zero.

-or-

index plus count is greater than the length of bytes.
ArgumentException An invalid surrogate pair sequence was detected.
Remarks
Use UTF8Encoding.GetCharCount to calculate exactly, or UTF8Encoding.GetMaxCharCount to calculate at most, the array size required by the UTF8Encoding.GetChars method to store decoded bytes.

Return to top

Overloaded Method: GetChars(
   byte[] bytes
)
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
);
Parameters:

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.
Remarks
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.
See also:
Encoding.GetCharCount | Encoding.GetMaxCharCount

Return to top

Overloaded Method: GetChars(
   byte[] bytes,
   int index,
   int count
)
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
);
Parameters:

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.
Remarks
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.
See also:
Encoding.GetCharCount | Encoding.GetMaxCharCount

Return to top

Overloaded Method: GetChars(
   byte[] bytes,
   int byteIndex,
   int byteCount,
   char[] chars,
   int charIndex
)
Summary
Decodes a range of elements from a specified byte array and stores the result into a specified range of elements in a Unicode character array.
C# Syntax:
public override int GetChars(
   byte[] bytes,
   int byteIndex,
   int byteCount,
   char[] chars,
   int charIndex
);
Parameters:

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 where 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 bytes contains an invalid sequence of bytes, and the UTF8Encoding.#ctor constructor for this instance specified throwing an exception when an invalid encoding is detected.
Remarks
Use UTF8Encoding.GetCharCount to calculate exactly, or UTF8Encoding.GetMaxCharCount to calculate at most, the array size required by the UTF8Encoding.GetChars method to store decoded bytes.

If error detection is turned off and an invalid UTF-8 byte sequence is detected, the invalid bytes are ignored and are not encoded into chars, and no exception is thrown.

See also:
UTF8Encoding.GetCharCount | UTF8Encoding.GetMaxCharCount | Encoding.GetChars

Return to top

Overridden Method: GetDecoder()
Summary
Obtains a decoder that can convert a UTF-8 encoded sequence of bytes into a sequence of Unicode characters.
C# Syntax:
public override Decoder GetDecoder();
Return Value:
A Decoder.
Remarks
The Decoder.GetChars method converts adjacent blocks of bytes into adjacent blocks of characters, in a manner similar to the UTF8Encoding.GetChars method. However, a Decoder maintains state information between calls so it can correctly decode byte sequences that span blocks.

If this UTF8Encoding.#ctor is constructed with error detection turned on (that is, the throwOnInvalidBytes parameter is true), the Decoder returned by this method also has error detection turned on. If an error is detected, the decoder is in an undefined state and should not be reused. Use error detection if you intend to stop processing after an error is encountered. Otherwise, if you intend to continue processing after an error is found, do not use error detection.

The UTF8Encoding.GetDecoder method obtains a Decoder that preserves trailing bytes at the end of decoded blocks and uses the trailing bytes in the next decoding operation. UTF8Encoding.GetDecoder and UTF8Encoding.GetEncoder are useful for network transmission and file operations since those operations often deal with blocks of data instead of a complete stream.

See also:
UTF8Encoding.GetCharCount | UTF8Encoding.GetChars

Return to top

Overridden Method: GetEncoder()
Summary
Obtains an encoder that can convert a sequence of Unicode characters into a UTF-8 encoded sequence of bytes.
C# Syntax:
public override Encoder GetEncoder();
Return Value:
An Encoder.
Remarks
The Encoder.GetBytes method converts adjacent blocks of characters into adjacent blocks of bytes, in a manner similar to the UTF8Encoding.GetBytes method. However, an Encoder maintains state information between calls so it can correctly encode characters that span blocks.

If this UTF8Encoding.#ctor is constructed with error detection turned on (that is, the throwOnInvalidBytes parameter is true), the Encoder returned by this method also has error detection turned on.

The UTF8Encoding.GetEncoder method obtains an Encoder that preserves trailing characters (such as a high-surrogate), at the end of a block and uses the trailing Unicode characters in the next encoding operation. UTF8Encoding.GetDecoder and UTF8Encoding.GetEncoder are useful for network transmission and file operations since those operations often deal with blocks of data instead of a complete stream.

See also:
UTF8Encoding.GetByteCount | UTF8Encoding.GetBytes

Return to top

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

Overridden Method: GetMaxByteCount(
   int charCount
)
Summary
Calculates the maximum number of bytes required to encode a specified number of characters.
C# Syntax:
public override int GetMaxByteCount(
   int charCount
);
Parameters:

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.
Remarks
Use UTF8Encoding.GetByteCount to calculate exactly, or UTF8Encoding.GetMaxByteCount to calculate at most, the array size required by the UTF8Encoding.GetBytes method to store encoded characters.
See also:
UTF8Encoding.GetBytes | Encoder.GetBytes

Return to top

Overridden Method: GetMaxCharCount(
   int byteCount
)
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
);
Parameters:

byteCount

The number of bytes to decode.

Return Value:
The maximum number of characters that can result from decoding byteCount number of bytes.
Exceptions
Exception Type Condition
ArgumentOutOfRangeException byteCount is less than zero.
Remarks
Use UTF8Encoding.GetCharCount to calculate exactly, or UTF8Encoding.GetMaxCharCount to calculate at most, the array size required by the UTF8Encoding.GetChars method to store decoded bytes.
See also:
UTF8Encoding.GetChars | Decoder.GetChars

Return to top

Overridden Method: GetPreamble()
Summary
Returns a Unicode byte order mark encoded in UTF-8 format, if the constructor for this instance requested byte order mark support.
C# Syntax:
public override byte[] GetPreamble();
Return Value:
A byte array containing the Unicode byte order mark (U+FEFF), encoded as hexadecimal 0xEF, 0xBB, 0xBF, if the constructor for this instance requested a UTF-8 identifier be emitted; otherwise, a byte array of length zero.
Remarks
The byte order mark, when concatenated before the beginning of an encoded sequence of bytes, enables classes like StreamReader determine whether subsequent bytes are encoded in UTF-8 format.

Concatenate this return value to the beginning of a UTF-8 encoded sequence of bytes if the constructor for this instance requested support for a byte order mark.

Return to top

Overloaded Method: GetString(
   byte[] bytes
)
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
);
Parameters:

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.
Remarks
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.
Example
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

Overloaded Method: GetString(
   byte[] bytes,
   int index,
   int count
)
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
);
Parameters:

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.
Remarks
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.
Example
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

Method: GetType()
Inherited
See base class member description: System.Object.GetType
C# Syntax:
public Type GetType();

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

Return to top

Method: MemberwiseClone()
Inherited
See base class member description: System.Object.MemberwiseClone
C# Syntax:
protected object MemberwiseClone();

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

Return to top

Method: ToString()
Inherited
See base class member description: System.Object.ToString
C# Syntax:
public virtual string ToString();

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

Return to top

Top of page

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