mscorlib 2.0.0.0 4.0.0.0 System.Text.Encoding

Encoding is the process of transforming a set of Unicode characters into a sequence of bytes. Decoding is the process of transforming a sequence of encoded bytes into a set of Unicode characters.

The UTF-32 encoding represents each code point as a 32-bit integer. For more information about the UTFs and other encodings supported by , see Understanding Encodings.

The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding.

Likewise, the method determines how many characters result in decoding a sequence of bytes, and the and methods perform the actual decoding.

corresponds to the Windows code pages 12000 (little endian byte order) and 12001 (big endian byte order).

The encoder can use the big endian byte order (most significant byte first) or the little endian byte order (least significant byte first). For example, the Latin Capital Letter A (code point U+0041) is serialized as follows (in hexadecimal):

Big endian byte order: 00 00 00 41

Little endian byte order: 41 00 00 00

It is generally more efficient to store Unicode characters using the native byte order. For example, it is better to use the little endian byte order on little endian platforms, such as Intel computers.

The method retrieves an array of bytes that can include the byte order mark (BOM). If this byte array is prefixed to an encoded stream, it helps the decoder to identify the encoding format used.

For more information on byte order and the byte order mark, see The Unicode Standard at the Unicode home page.

To enable error detection and to make the class instance more secure, the application should use the constructor that takes a parameter, and set that parameter to true. With error detection, a method that detects an invalid sequence of characters or bytes throws a . Without error detection, no exception is thrown, and the invalid sequence is generally ignored.

Represents a UTF-32 encoding of Unicode characters.

- Constructor
  2.0.0.0
  4.0.0.0

  This constructor creates an instance that uses the little endian byte order, provides a Unicode byte order mark, and does not throw an exception when an invalid encoding is detected.

  For security reasons, your applications are recommended to enable error detection by using the constructor that accepts a parameter and setting that parameter to true.

  Initializes a new instance of the class.

- Constructor
  2.0.0.0
  4.0.0.0

  This constructor creates an instance that does not throw an exception when an invalid encoding is detected.

  For security reasons, your applications are recommended to enable error detection by using the constructor that accepts a parameter and setting that parameter to true.

  Initializes a new instance of the class. Parameters specify whether to use the big endian byte order and whether to provide a Unicode byte order mark.

  true to use the big endian byte order (most significant byte first), or false to use the little endian byte order (least significant byte first).
  true to specify that a Unicode byte order mark is provided; otherwise, false.
- Constructor
  2.0.0.0
  4.0.0.0

  If is true, a method that detects an invalid byte sequence throws . Otherwise, the method does not throw an exception, and the invalid sequence is ignored.

  For security reasons, your applications are recommended to use this constructor to create an instance of the class and turn on error detection by setting to true.

  Initializes a new instance of the class. Parameters specify whether to use the big endian byte order, whether to provide a Unicode byte order mark, and whether to throw an exception when an invalid encoding is detected.

  true to use the big endian byte order (most significant byte first), or false to use the little endian byte order (least significant byte first).
  true to specify that a Unicode byte order mark is provided; otherwise, false.
  true to specify that an exception should be thrown when an invalid encoding is detected; otherwise, false.
- Method
  2.0.0.0
  4.0.0.0
  System.Boolean ``

  Two objects are considered equal if all of the following conditions are true:

  Both objects use the same byte order.

  Both objects provide the byte order mark, or both do not.

  Both objects throw an exception when encountering invalid encoding, or both do not.

  Determines whether the specified is equal to the current object.

  true if is an instance of and is equal to the current object; otherwise, false.

  The to compare with the current object.
- Method
  2.0.0.0
  4.0.0.0
  System.Int32 ``

  To calculate the exact array size required by to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster.

  With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown.

  To ensure that the encoded bytes are decoded properly, the application should prefix encoded bytes with a preamble.

  Calculates the number of bytes produced by encoding the characters in the specified .

  The number of bytes produced by encoding the specified characters.

  The containing the set of characters to encode.
- Method
  2.0.0.0
  4.0.0.0
  System.CLSCompliant(false)
  System.Int32 `` ``

  To calculate the exact array size required by to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster.

  With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown.

  To ensure that the encoded bytes are decoded properly, the application should prefix encoded bytes with a preamble.

  Calculates the number of bytes produced by encoding a set of characters starting at the specified character pointer.

  The number of bytes produced by encoding the specified characters.

  A pointer to the first character to encode. The number of characters to encode.
- Method
  2.0.0.0
  4.0.0.0
  System.Int32 `` `` ``

  To calculate the exact array size required by to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster.

  With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown.

  To ensure that the encoded bytes are decoded properly, the application should prefix encoded bytes with a preamble.

  Calculates the number of bytes produced by encoding a set of characters from the specified character array.

  The number of bytes produced by encoding the specified characters.

  The character array containing the set of characters to encode. The index of the first character to encode. The number of characters to encode.
- Method
  2.0.0.0
  4.0.0.0
  System.CLSCompliant(false)
  System.Int32 `` `` `` ``

  To calculate the exact array size required by to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster.

  With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown.

  Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application uses the or the provided by the method or the method, respectively.

  To ensure that the encoded bytes are decoded properly, the application should prefix encoded bytes with a preamble.

  Encodes a set of characters starting at the specified character pointer into a sequence of bytes that are stored starting at the specified byte pointer.

  The actual number of bytes written at the location indicated by the parameter.

  A pointer to the first character to encode. The number of characters to encode. A pointer to the location at which to start writing the resulting sequence of bytes. The maximum number of bytes to write.
- Method
  2.0.0.0
  4.0.0.0
  System.Int32 `` `` `` `` ``

  To calculate the exact array size required by to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster.

  With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown.

  Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application uses the or the provided by the method or the method, respectively.

  To ensure that the encoded bytes are decoded properly, the application should prefix encoded bytes with a preamble.

  Encodes a set of characters from the specified character array into the specified byte array.

  The actual number of bytes written into .

  The character array containing the set of characters to encode. The index of the first character to encode. The number of characters to encode. The byte array to contain the resulting sequence of bytes. The index at which to start writing the resulting sequence of bytes.
- Method
  2.0.0.0
  4.0.0.0
  System.Int32 `` `` `` `` ``

  To calculate the exact array size required by to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster.

  With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown.

  Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application uses the or the provided by the method or the method, respectively.

  To ensure that the encoded bytes are decoded properly, the application should prefix encoded bytes with a preamble.

  Encodes a set of characters from the specified into the specified byte array.

  The actual number of bytes written into .

  The containing the set of characters to encode. The index of the first character to encode. The number of characters to encode. The byte array to contain the resulting sequence of bytes. The index at which to start writing the resulting sequence of bytes.
- Method
  2.0.0.0
  4.0.0.0
  System.CLSCompliant(false)
  System.Int32 `` ``

  To calculate the exact array size required by to store the resulting characters, use . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster.

  With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown.

  Calculates the number of characters produced by decoding a sequence of bytes starting at the specified byte pointer.

  The number of characters produced by decoding the specified sequence of bytes.

  A pointer to the first byte to decode. The number of bytes to decode.
- Method
  2.0.0.0
  4.0.0.0
  System.Int32 `` `` ``

  To calculate the exact array size required by to store the resulting characters, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster.

  With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown.

  Calculates the number of characters produced by decoding a sequence of bytes from the specified byte array.

  The number of characters produced by decoding the specified sequence of bytes.

  The byte array containing the sequence of bytes to decode. The index of the first byte to decode. The number of bytes to decode.
- Method
  2.0.0.0
  4.0.0.0
  System.CLSCompliant(false)
  System.Int32 `` `` `` ``

  To calculate the exact array size required by to store the resulting characters, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster.

  With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown.

  Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application uses the or the provided by the method or the method, respectively.

  Decodes a sequence of bytes starting at the specified byte pointer into a set of characters that are stored starting at the specified character pointer.

  The actual number of characters written at the location indicated by .

  A pointer to the first byte to decode. The number of bytes to decode. A pointer to the location at which to start writing the resulting set of characters. The maximum number of characters to write.
- Method
  2.0.0.0
  4.0.0.0
  System.Int32 `` `` `` `` ``

  To calculate the exact array size required by to store the resulting characters, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster.

  With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown.

  Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application uses the or the provided by the method or the method, respectively.

  Decodes a sequence of bytes from the specified byte array into the specified character array.

  The actual number of characters written into .

  The byte array containing the sequence of bytes to decode. The index of the first byte to decode. The number of bytes to decode. The character array to contain the resulting set of characters. The index at which to start writing the resulting set of characters.
- Method
  2.0.0.0
  4.0.0.0
  System.Text.Decoder

  The method converts sequential blocks of bytes into sequential blocks of characters, in a manner similar to the method. However, a maintains state information between calls so it can correctly decode byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream.

  If error detection is enabled, that is, the parameter of the constructor was set to true, error detection is also enabled in the returned by this method. If error detection is enabled and an invalid sequence is encountered, the state of the decoder is undefined and processing must stop.

  Obtains a decoder that converts a UTF-32 encoded sequence of bytes into a sequence of Unicode characters.

  A that converts a UTF-32 encoded sequence of bytes into a sequence of Unicode characters.

- Method
  2.0.0.0
  4.0.0.0
  System.Text.Encoder

  The method converts sequential blocks of characters into sequential blocks of bytes, in a manner similar to the method. However, a maintains state information between calls so it can correctly encode character sequences that span blocks. The also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. For example, a data block might end with an unmatched high-surrogate, and the matching low-surrogate might be in the next data block. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream.

  If error detection is enabled, that is, the parameter of the constructor was set to true, error detection is also enabled in the returned by this method. If error detection is enabled and an invalid sequence is encountered, the state of the encoder is undefined and processing must stop.

  Obtains an encoder that converts a sequence of Unicode characters into a UTF-32 encoded sequence of bytes.

  A that converts a sequence of Unicode characters into a UTF-32 encoded sequence of bytes.

- Method
  2.0.0.0
  4.0.0.0
  System.Int32 To be added.

  Returns the hash code for the current instance.

  The hash code for the current object.

- Method
  2.0.0.0
  4.0.0.0
  System.Int32 ``

  To calculate the exact array size required by to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster.

  is a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, M can return large values.

  In most cases, this method returns reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is exceeded. You might also want to consider a different approach and use or .

  has no relation to . If your application needs a similar function to use with , it should use .

  GetMaxByteCount(N) is not necessarily the same value as N* GetMaxByteCount(1).

  Calculates the maximum number of bytes produced by encoding the specified number of characters.

  The maximum number of bytes produced by encoding the specified number of characters.

  The number of characters to encode.
- Method
  2.0.0.0
  4.0.0.0
  System.Int32 ``

  To calculate the exact array size required by to store the resulting characters, the application uses . To calculate the maximum array size, the application should use . The method generally allows allocation of less memory, while the method generally executes faster.

  is a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, can return large values.

  In most cases, this method returns reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is exceeded. You might also want to consider a different approach and use or .

  has no relation to . If your application needs a similar function to use with , it should use .

  GetMaxCharCount(N) is not necessarily the same value as N* GetMaxCharCount(1).

  Calculates the maximum number of characters produced by decoding the specified number of bytes.

  The maximum number of characters produced by decoding the specified number of bytes.

  The number of bytes to decode.
- Method
  2.0.0.0
  4.0.0.0
  System.Byte[]

  Optionally, the object provides a preamble, which is an array of bytes that can be prefixed to the sequence of bytes resulting from the encoding process. If the preamble contains a byte order mark (code point U+FEFF), it helps the decoder determine the byte order and the transformation format or UTF. The Unicode byte order mark is serialized as follows (in hexadecimal):

  Big endian byte order: 00 00 FE FF

  Little endian byte order: FF FE 00 00

  Your applications are recommended to use the BOM, as it provides nearly certain identification of an encoding for files that otherwise have lost reference to the UTF32Encoding object, for example, untagged or improperly tagged web data or random text files stored when a business did not have international concerns or other data. Often user problems might be avoided if data is consistently and properly tagged.

  For standards that provide an encoding type, a BOM is somewhat redundant. However, it can be used to help a server send the correct encoding header. Alternatively, it can be used as a fallback in case the encoding is otherwise lost.

  There are some disadvantages to using a BOM. For example, knowing how to limit the database fields that use a BOM can be difficult. Concatenation of files can be a problem also, for example, when files are merged in such a way that an unnecessary character can end up in the middle of data. In spite of the few disadvantages, however, the use of a BOM is highly recommended.

  For more information on byte order and the byte order mark, see The Unicode Standard at the Unicode home page.

  To ensure that the encoded bytes are decoded properly, your application should prefix encoded bytes with a preamble.

  Returns a Unicode byte order mark encoded in UTF-32 format, if the constructor for this instance requests a byte order mark.

  A byte array containing the Unicode byte order mark, if the constructor for this instance requests a byte order mark. Otherwise, this method returns a byte array of length zero.

- Method
  2.0.0.0
  4.0.0.0
  System.String `` `` ``

  With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown.

  Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the provided by the method or the method, respectively.

  Decodes a range of bytes from a byte array into a string.

  A containing the results of decoding the specified sequence of bytes.

  The byte array containing the sequence of bytes to decode. The index of the first byte to decode. The number of bytes to decode.