Object
Encoding
mscorlib
BCL
Represents a character encoding.
Characters are abstract entities that can be represented using many different character schemes or codepages. For example, Unicode UTF-16 encoding represents, or encodes, characters as sequences of 16-bit integers while Unicode UTF-8 represents the same characters as sequences of 8-bit bytes.The BCL includes the following types derived from Encoding:
An application can use the properties of this class such as System.Text.Encoding.ASCII, System.Text.Encoding.Default, System.Text.Encoding.Unicode, and System.Text.Encoding.UTF8 to obtain encodings. Applications can initialize new instances of Encoding objects through the ASCIIEncoding, UnicodeEncoding, and UTF8Encoding classes.
- ASCIIEncoding - encodes Unicode characters as 7-bit ASCII characters. This encoding only supports code points between U+0000 and U+007F inclusive.
- UnicodeEncoding - encodes each Unicode character as two consecutive bytes. Both little-endian and big-endian byte orders are supported.
- UTF8Encoding - encodes Unicode characters using the UTF-8 (UCS Transformation Format, 8-bit form) encoding. This encoding supports all Unicode character values.
Through an encoding, the System.Text.Encoding.GetBytes(System.Char[]) method is used to convert arrays of Unicode characters to arrays of bytes, and the System.Text.Encoding.GetChars(System.Byte[]) method is used to convert arrays of bytes to arrays of Unicode characters. The System.Text.Encoding.GetBytes(System.Char[]) and System.Text.Encoding.GetChars(System.Byte[]) methods maintain no state between conversions. When the data to be converted is only available in sequential blocks (such as data read from a stream) or when the amount of data is so large that it needs to be divided into smaller blocks, an application can choose to use a Decoder or a Encoder to perform the conversion. Decoders and encoders allow sequential blocks of data to be converted and they maintain the state required to support conversions of data that spans adjacent blocks. Decoders and encoders are obtained using the System.Text.Encoding.GetDecoder and System.Text.Encoding.GetEncoder methods.
The core System.Text.Encoding.GetBytes(System.Char[]) and System.Text.Encoding.GetChars(System.Byte[]) methods require the caller to provide the destination buffer and ensure that the buffer is large enough to hold the entire result of the conversion. When using these methods, either directly on a Encoding object or on an associated Decoder or Encoder, an application can use one of two methods to allocate destination buffers.
The first method generally uses less memory, whereas the second method generally executes faster.
- The System.Text.Encoding.GetByteCount(System.Char[]) and System.Text.Encoding.GetCharCount(System.Byte[]) methods can be used to compute the exact size of the result of a particular conversion, and an appropriately sized buffer for that conversion can then be allocated.
- The System.Text.Encoding.GetMaxByteCount(System.Int32) and System.Text.Encoding.GetMaxCharCount(System.Int32) methods can be used to compute the maximum possible size of a conversion of a given number of characters or bytes, regardless of the actual character or byte values, and a buffer of that size can then be reused for multiple conversions.
System.Text Namespace
Encoding Constructors
Encoding Methods
Encoding.Convert(System.Text.Encoding, System.Text.Encoding, byte[], int, int) Method
Encoding.Convert(System.Text.Encoding, System.Text.Encoding, byte[]) Method
Encoding.Equals Method
Encoding.GetByteCount(char[]) Method
Encoding.GetByteCount(System.String) Method
Encoding.GetByteCount(char[], int, int) Method
Encoding.GetBytes(char[]) Method
Encoding.GetBytes(char[], int, int) Method
Encoding.GetBytes(char[], int, int, byte[], int) Method
Encoding.GetBytes(System.String) Method
Encoding.GetBytes(System.String, int, int, byte[], int) Method
Encoding.GetCharCount(byte[]) Method
Encoding.GetCharCount(byte[], int, int) Method
Encoding.GetChars(byte[]) Method
Encoding.GetChars(byte[], int, int) Method
Encoding.GetChars(byte[], int, int, char[], int) Method
Encoding.GetDecoder Method
Encoding.GetEncoder Method
Encoding.GetHashCode Method
Encoding.GetMaxByteCount Method
Encoding.GetMaxCharCount Method
Encoding.GetPreamble Method
Encoding.GetString(byte[]) Method
Encoding.GetString(byte[], int, int) Method
Encoding Properties
Encoding.ASCII Property
Encoding.BigEndianUnicode Property
Encoding.Default Property
Encoding.UTF8 Property
Encoding.Unicode Property
Constructs a new instance of the Encoding class.
System.Text.Encoding Class, System.Text Namespace
Converts the specified range of the specified Byte array from one specified encoding to another specified encoding.
- srcEncoding
- The Encoding that bytes is in.
- dstEncoding
- The Encoding desired for the returned Byte array.
- bytes
- The Byte array containing the values to convert.
- index
- A Int32 containing the first index of bytes from which to convert.
- count
- A Int32 containing the number of bytes to convert.
A Byte array containing the result of the conversion.
Exception Type Condition ArgumentNullException srcEncoding, dstEncoding , or bytes is null.
ArgumentOutOfRangeException index and count do not denote a valid range in bytes .
System.Text.Encoding Class, System.Text Namespace
Converts the specified Byte array from one specified encoding to another specified encoding.
- srcEncoding
- The Encoding that bytes is in.
- dstEncoding
- The Encoding desired for the returned Byte array.
- bytes
- The Byte array containing the values to convert.
A Byte array containing the result of the conversion.
Exception Type Condition ArgumentNullException srcEncoding, dstEncoding or bytes is null.
System.Text.Encoding Class, System.Text Namespace
Determines whether the current instance and the specified Object represent the same type and value.
- value
- The Object to compare to the current instance.
trueif obj represents the same type and value as the current instance. If obj is a null reference or is not an instance of Encoding, returnsfalse.
[Note: This method overrides System.Object.Equals(System.Object).]
System.Text.Encoding Class, System.Text Namespace
Returns the number of bytes required to encode the specified Char array.
- chars
- The Char array to encode.
A Int32 containing the number of bytes needed to encode chars.
Exception Type Condition ArgumentNullException chars is null.
[Behaviors: As described above.]
[Overrides: This method is overridden by types derived from Encoding to return the appropriate number of bytes for the particular encoding. ]
[Usage: System.Text.Encoding.GetByteCount(System.Char[]) can be used to determine the exact 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, System.Text.Encoding.GetMaxByteCount(System.Int32) can be used to determine the maximum number of bytes that will be produced from converting a given number of characters, regardless of the actual character values. A buffer of that size can then be reused for multiple conversions.
System.Text.Encoding.GetByteCount(System.Char[]) generally uses less memory and System.Text.Encoding.GetMaxByteCount(System.Int32) generally executes faster.
]
System.Text.Encoding Class, System.Text Namespace
Returns the number of bytes required to encode the specified String.
- s
- The String to decode.
A Int32 containing the number of bytes needed to encode s.
Exception Type Condition ArgumentNullException s is null.
[Behaviors: As described above.]
[Overrides: This method is overridden by types derived from Encoding to return the appropriate number of bytes for the particular encoding. ]
[Usage: System.Text.Encoding.GetByteCount(System.Char[]) can be used to determine the exact number of bytes that will be produced from encoding the given String . An appropriately sized buffer for that conversion can then be allocated.
Alternatively, System.Text.Encoding.GetMaxByteCount(System.Int32) can be used to determine the maximum number of bytes that will be produced from converting a given number of characters, regardless of the actual character values. A buffer of that size can then be reused for multiple conversions.
System.Text.Encoding.GetByteCount(System.Char[]) generally uses less memory and System.Text.Encoding.GetMaxByteCount(System.Int32) generally executes faster.
]
System.Text.Encoding Class, System.Text Namespace
Returns the number of bytes required to encode the specified range of characters in the specified Unicode character array.
- chars
- The Char array to encode.
- index
- A Int32 containing the first index of chars to encode.
- count
- A Int32 containing the number of characters to encode.
A Int32 containing the number of bytes required to encode the range in chars from index to index + count - 1.
Exception Type Condition ArgumentNullException chars is null.ArgumentOutOfRangeException The number of bytes required to encode the specified elements in chars is greater than System.Int32.MaxValue. -or-
index or count is less than zero.
-or-
index and count do not specify a valid range in chars (i.e. (index + count) > chars.Length).
[Behaviors: As described above. ]
[Overrides: This method is overridden by types derived from Encoding to return the appropriate number of bytes for the particular encoding. ]
[Usage: System.Text.Encoding.GetByteCount(System.Char[]) can be used to determine the exact the number of bytes that will be produced from encoding a given range of characters. An appropriately sized buffer for that conversion can then be allocated.
Alternatively, System.Text.Encoding.GetMaxByteCount(System.Int32) can be used to determine the maximum number of bytes that will be produced from converting a given number of characters, regardless of the actual character values. A buffer of that size can then be reused for multiple conversions.
System.Text.Encoding.GetByteCount(System.Char[]) generally uses less memory and System.Text.Encoding.GetMaxByteCount(System.Int32) generally executes faster.
]
System.Text.Encoding Class, System.Text Namespace
Encodes the specified Char array.
- chars
- The Char array to encode.
A Byte array containing the encoded representation of chars.
Exception Type Condition ArgumentNullException chars is null.
[Behaviors: As described above.]
[Overrides: This method is overridden by types derived from Encoding to perform the encoding. ]
System.Text.Encoding Class, System.Text Namespace
Encodes the specified range of the specified Char array.
- chars
- The Char array to encode.
- index
- A Int32 containing the first index of chars to encode.
- count
- A Int32 containing the number of characters to encode.
A Byte array containing the encoded representation of the range in chars from index to index + count - 1.
Exception Type Condition ArgumentNullException chars is null.ArgumentOutOfRangeException index and count do not denote a valid range in chars.
[Behaviors: As described above.]
[Overrides: This method is overridden by types derived from Encoding to perform the encoding. ]
System.Text.Encoding Class, System.Text Namespace
Encodes the specified range of the specified Char array into the specified range of the specified Byte array.
- chars
- A Char array to encode.
- charIndex
- A Int32 containing the first index of chars to encode.
- charCount
- A Int32 containing the number of characters to encode.
- bytes
- A Byte array to encode into.
- byteIndex
- A Int32 containing the first index of bytes to encode into.
The number of bytes encoded into bytes .
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-
(chars.Length - charIndex) < charCount.
-or-
byteIndex > bytes.Length.
[Behaviors: As described above.]
[Overrides: This method is overridden by types derived from Encoding to perform the encoding. ]
[Usage: System.Text.Encoding.GetByteCount(System.Char[]) can be used to determine the exact number of bytes that will be produced for a given range of characters. Alternatively, System.Text.Encoding.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.]
System.Text.Encoding Class, System.Text Namespace
Encodes the specified String.
- s
- The String to encode.
A Byte array containing the encoded representation of s.
Exception Type Condition ArgumentNullException s is null.
[Behaviors: As described above.]
[Overrides: This method is overridden by types derived from Encoding to perform the encoding. ]
System.Text.Encoding Class, System.Text Namespace
Encodes the specified range of the specified String into the specified range of the specified Byte array.
- s
- A String to encode.
- charIndex
- A Int32 containing the first index of s from which to encode.
- charCount
- A Int32 containing the number of characters of s to encode.
- bytes
- The Byte array to encode into.
- byteIndex
- A Int32 containing the first index of bytes to encode into.
A Int32 containing the number of bytes encoded into bytes.
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-
(s.Length - charIndex) < charCount.
-or-
byteIndex >= bytes.Length.
[Behaviors: As described above.]
[Overrides: This method is overridden by types derived from Encoding to perform the encoding. ]
System.Text.Encoding Class, System.Text Namespace
Determines the exact number of characters that will be produced by decoding the specified Byte array.
- bytes
- The Byte array to decode.
A Int32 containing the number of characters produced by decoding bytes.
Exception Type Condition ArgumentNullException bytes is null.
[Behaviors: As described above.]
[Overrides: This method is overridden by types derived from Encoding to return the appropriate number of bytes for the particular encoding.]
[Usage: Use System.Text.Encoding.GetCharCount(System.Byte[]) to determine the exact number of characters that will be produced from converting a given byte array. An appropriately sized buffer for that conversion can then be allocated.
Alternatively, use System.Text.Encoding.GetMaxCharCount(System.Int32) to determine the maximum number of characters that will be produced for a given number of bytes, regardless of the actual byte values. A buffer of that size can then be reused for multiple conversions.
System.Text.Encoding.GetCharCount(System.Byte[]) generally uses less memory and System.Text.Encoding.GetMaxCharCount(System.Int32) generally executes faster.
]
System.Text.Encoding Class, System.Text Namespace
Determines the exact number of characters that will be produced by decoding the specified range of the specified Byte array.
- bytes
- The Byte array to decode.
- index
- The first index in bytes to decode.
- count
- The number of bytes to decode.
A Int32 containing the number of characters the next call to System.Text.Decoder.GetChars(System.Byte[],System.Int32,System.Int32,System.Char[],System.Int32) will produce if presented with the specified range of bytes.
Exception Type Condition ArgumentNullException bytes is null.ArgumentOutOfRangeException index and count do not specify a valid range in bytes (i.e. (index + count) > bytes.Length).
[Behaviors: As described above.]
[Overrides: This method is overridden by types derived from Encoding to return the appropriate number of bytes for the particular encoding.]
[Usage: Use System.Text.Encoding.GetCharCount(System.Byte[]) to determine the exact 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, use System.Text.Encoding.GetMaxCharCount(System.Int32) to determine the maximum number of characters that will be produced for a given number of bytes, regardless of the actual byte values. A buffer of that size can then be reused for multiple conversions.
System.Text.Encoding.GetCharCount(System.Byte[]) generally uses less memory and System.Text.Encoding.GetMaxCharCount(System.Int32) generally executes faster.
]
System.Text.Encoding Class, System.Text Namespace
Decodes a Byte array.
- bytes
- The Byte array to decode.
A Char array produced by decoding bytes .
Exception Type Condition ArgumentNullException bytes is null.
System.Text.Encoding Class, System.Text Namespace
Decodes the specified range of the specified Byte array.
- bytes
- The Byte array to decode.
- index
- A Int32 containing the first index of bytes to decode.
- count
- A Int32 containing the number of bytes to decode.
A Char array containing the decoded representation of the range in bytes between index to index + count .
Exception Type Condition ArgumentNullException bytes is null.ArgumentOutOfRangeException index and count do not denote a valid range in the byte array.
System.Text.Encoding Class, System.Text Namespace
Decodes the specified range of the specified Byte array into the specified range of the specified Char array.
- bytes
- The Byte array to decode.
- byteIndex
- A Int32 containing the first index of bytes to decode.
- byteCount
- A Int32 containing the number of bytes to decode.
- chars
- The Char array to decode into.
- charIndex
- A Int32 containing the first index of chars to decode into.
The number of characters stored in chars.
Exception Type Condition ArgumentException chars does not contain sufficient space to store the decoded characters.
ArgumentNullException bytes is null.-or-
chars 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.
[Behaviors: This method requires the caller to provide the destination buffer and ensure that the buffer is large enough to hold the entire result of the conversion.]
[Overrides: This method is overridden by types derived from Encoding to perform the particular decoding.]
[Usage: When using this method directly on a Encoding object or on an associated Decoder or Encoder, use System.Text.Encoding.GetCharCount(System.Byte[]) or System.Text.Encoding.GetMaxCharCount(System.Int32) to allocate destination buffers.]
System.Text.Encoding Class, System.Text Namespace
Returns a Decoder for the current instance.
A Decoder for the current instance.
[Behaviors: As described above.]
[Default: The default implementation returns a Decoder that forwards calls made to the System.Text.Encoding.GetCharCount(System.Byte[]) and System.Text.Encoding.GetChars(System.Byte[]) methods to the corresponding methods of the current instance. ]
[Overrides: Encoding that requires state to be maintained between successive conversions should override this method and return an instance of an appropriate Decoder implementation.]
[Usage: Unlike the System.Text.Encoding.GetChars(System.Byte[]) methods, a Decoder can convert partial sequences of bytes into partial sequences of characters by maintaining the appropriate state between the conversions. ]
System.Text.Encoding Class, System.Text Namespace
Returns a Encoder for the current instance.
A Encoder for the current encoding.
[Behaviors: As described above.]
[Default: The default implementation returns a Encoder that forwards calls made to the System.Text.Encoding.GetByteCount(System.Char[]) and System.Text.Encoding.GetBytes(System.Char[]) methods to the corresponding methods of the current instance.]
[Overrides: Types derived from Encoding override this method to return an instance of an appropriate Encoder .]
[Usage: Unlike the System.Text.Encoding.GetBytes(System.Char[]) method, a Encoder can convert partial sequences of characters into partial sequences of bytes by maintaining the appropriate state between the conversions. ]
System.Text.Encoding Class, System.Text Namespace
Generates a hash code for the current instance.
A Int32 containing the hash code for the current instance.
The algorithm used to generate the hash code is unspecified.[Note: This method overrides System.Object.GetHashCode.]
System.Text.Encoding Class, System.Text Namespace
Returns the maximum number of bytes required to encode the specified number of characters, regardless of the actual character values.
- charCount
- A Int32 containing the number of characters to encode.
A Int32 containing the maximum number of bytes required to encode charCount characters.
[Behaviors: As described above. ]
[Overrides: This method is overridden by types derived from Encoding to return the appropriate number of bytes for the particular encoding.]
[Usage: System.Text.Encoding.GetMaxByteCount(System.Int32) can be used to determine the minimum buffer size for byte arrays passed to the System.Text.Encoding.GetBytes(System.Char[]) of the current encoding. Using this minimum buffer size ensures that no buffer overflow exceptions occur. ]
System.Text.Encoding Class, System.Text Namespace
Returns the maximum number of characters produced by decoding the specified number of bytes, regardless of the actual byte values.
- byteCount
- A Int32 containing the number of bytes to decode.
A Int32 containing the maximum number of characters that would be produced by decoding byteCount bytes.
[Behaviors: As described above.]
[Overrides: This method is overridden by types derived from Encoding to return the appropriate number of bytes for the particular encoding.]
[Usage: System.Text.Encoding.GetMaxCharCount(System.Int32) can be used to determine the minimum buffer size for byte arrays passed to the System.Text.Encoding.GetChars(System.Byte[]) of the current encoding. Using this minimum buffer size ensures that no buffer overflow exceptions will occur.]
System.Text.Encoding Class, System.Text Namespace
Returns the bytes used at the beginning of a Stream to determine which Encoding the stream was created with.
A Byte array that identifies the encoding used on a stream.
[Note: The preamble can be the Unicode byte order mark (U+FEFF written in the appropriate encoding) or any other type of identifying marks. This method can return an empty array.]
[Behaviors: As described above.]
[Default: The default implementation returns an empty Byte array.]
[Overrides: Override this method to return a Byte array containing the preamble appropriate for the type derived from Encoding .]
System.Text.Encoding Class, System.Text Namespace
Decodes the specified Byte array.
- bytes
- The Byte array to decode.
A String containing the decoded representation of bytes.
Exception Type Condition ArgumentNullException bytes is null.
[Behaviors: As described above.]
[Overrides: This method is overridden by particular character encodings.]
System.Text.Encoding Class, System.Text Namespace
Decodes the specified range of the specified Byte array.
- bytes
- The Byte array to decode.
- index
- A Int32 containing the starting index of bytes to decode.
- count
- A Int32 containing the number of bytes to decode.
A String containing the decoded representation of the range of bytes from index to index + count.
Exception Type Condition ArgumentNullException bytes is null.ArgumentOutOfRangeException index and count do not denote a valid range in bytes.
[Behaviors: As described above.]
[Overrides: This method is overridden by particular character encodings.]
System.Text.Encoding Class, System.Text Namespace
public static Encoding ASCII { get; }
Gets an encoding for the ASCII (7-bit) character set.
This property is read-only.[Note: ASCII characters can represent Unicode characters from U+0000 to U+007f, inclusive.
]
System.Text.Encoding Class, System.Text Namespace
public static Encoding BigEndianUnicode { get; }
Gets an encoding for the Unicode format in big-endian byte order.
A Encoding for the Unicode format in big-endian byte order.
This property is read-only.[Note: Unicode characters can be stored in two different byte orders, big-endian and little-endian. On little-endian platforms such as those implemented on Intel processors, it is generally more efficient to store Unicode characters in little-endian byte order. However, many other platforms can store Unicode characters in big-endian byte order. Unicode files can be distinguished by the presence of the byte order mark (U+FEFF), which will be written as either 0xfe 0xff or 0xff 0xfe.
This encoding automatically detects a byte order mark and, if necessary, switches byte orders.
]
System.Text.Encoding Class, System.Text Namespace
public static Encoding Default { get; }
Gets an encoding for the ANSI code page of the current system.
A Encoding for the ANSI code page of the current system.
This property is read-only.
System.Text.Encoding Class, System.Text Namespace
public static Encoding UTF8 { get; }
Gets an encoding for the UTF-8 format.
A Encoding for the UTF-8 format.
This property is read-only.[Note: For detailed information regarding UTF-8 encoding, see UTF8Encoding.
]
System.Text.Encoding Class, System.Text Namespace
public static Encoding Unicode { get; }
Gets an encoding for the Unicode format in little-endian byte order.
A Encoding for the Unicode format in little-endian byte order.
This property is read-only.[Note: Unicode characters can be stored in two different byte orders, big-endian and little-endian. On little-endian platforms such as those implemented on Intel processors, it is generally more efficient to store Unicode characters in little-endian byte order. However, many other platforms can store Unicode characters in big-endian byte order. Unicode files can be distinguished by the presence of the byte order mark (U+FEFF), which will be written as either 0xfe 0xff or 0xff 0xfe.
This encoding automatically detects a byte order mark and, if necessary, switches byte orders.
]
System.Text.Encoding Class, System.Text Namespace