extends System.Text.Encoding
| Variables: |
|---|
| Constructors: |
|---|
public System.Text.UTF8Encoding(System.Boolean encoderShouldEmitUTF8Identifier, System.Boolean throwOnInvalidBytes) Constructs a new instance of the System.Text.UTF8Encoding class using the specified System.Boolean flags. Parameter encoderShouldEmitUTF8Identifier: A System.Boolean that indicates whether the Unicode byte order mark in UTF-8 is recognized or emitted when reading from or writing to a System.IO.Stream . Parameter throwOnInvalidBytes: A System.Boolean that indicates whether error-checking is turned on for the current instance. |
public System.Text.UTF8Encoding(System.Boolean encoderShouldEmitUTF8Identifier) Constructs a new instance of the System.Text.UTF8Encoding class with the specified System.Boolean that indicates whether the Unicode byte order mark in UTF-8 is recognized or emitted when reading from or writing to a System.IO.Stream. Parameter encoderShouldEmitUTF8Identifier: A System.Boolean that indicates whether the Unicode byte order mark in UTF-8 is recognized or emitted when reading from or writing to a System.IO.Stream . This constructor is equivalent to System.Text.UTF8Encoding (encoderShouldEmitUTF8Identifier, false ). By default, this constructor turns error-checking off for the new instance. |
public System.Text.UTF8Encoding() Constructs a new instance of the System.Text.UTF8Encoding class. This constructor is equivalent to System.Text.UTF8Encoding (false, false ). By default, this constructor turns error-checking off for the new instance. |
| Functions: |
|---|
public System.Boolean Equals(System.Object value) Determines whether the current instance and the specified System.Object represent the same type and value. Parameter value: A System.Object to compare with the current instance. Returns: true if value is a System.Text.UTF8Encoding and represents the same type and value as the current instance; otherwise, false. This method overrides System.Object.Equals(System.Object). |
public System.Int32 GetByteCount(System.String chars) Determines the number of bytes required to encode the characters in the specified System.String as a System.Text.UTF8Encoding. Parameter chars: A System.String to encode as a System.Text.UTF8Encoding. Returns: A System.Int32 that specifies the number of bytes necessary to encode chars as a System.Text.UTF8Encoding. Throws: : chars is null. Throws: : Error-checking is turned on for the current instance and chars contains an invalid surrogate sequence. Throws: : The return value is greater than System.Int32.MaxValue. If error-checking 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. This method overrides System.Text.Encoding.GetByteCount(System.Char[]). |
public System.Int32 GetByteCount(System.Char[] chars, System.Int32 index, System.Int32 count) Determines the number of bytes required to encode the specified range of characters in the specified Unicode character array as a System.Text.UTF8Encoding. Parameter chars: The System.Char array to encode as a System.Text.UTF8Encoding . Parameter index: A System.Int32 that specifies the first index of chars to encode. Parameter count: A System.Int32 that specifies the number of characters to encode. Returns: A System.Int32 containing the number of bytes necessary to encode the range in chars from index to index + count - 1 as a System.Text.UTF8Encoding. Throws: : chars is null . Throws: : The return value 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). Throws: : Error-checking is turned on for the current instance and chars contains an invalid surrogate sequence. If error-checking 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. This method overrides System.Text.Encoder.GetByteCount(System.Char[],System.Int32,System.Int32,System.Boolean) . |
public System.Int32 GetBytes(System.String s, System.Int32 charIndex, System.Int32 charCount, System.Byte[] bytes, System.Int32 byteIndex) Encodes the specified range of the specified System.String into the specified range of the specified System.Byte array as a System.Text.UTF8Encoding . Parameter s: The System.String to encode as a System.Text.UTF8Encoding . Parameter charIndex: A System.Int32 that specifies the first index of s to encode. Parameter charCount: A System.Int32 that specifies the number of characters to encode. Parameter bytes: The System.Byte array to encode into. Parameter byteIndex: A System.Int32 that specifies the first index of bytes to encode into. Returns: A System.Int32 that indicates the number of bytes encoded into bytes as a System.Text.UTF8Encoding . Throws: : bytes does not contain sufficient space to store the encoded characters. -or- Error-checking is turned on for the current instance and chars contains an invalid surrogate sequence. Throws: : chars or bytes is null . Throws: : charIndex, charCount, or byteIndex is less than zero. -or- (s.Length - charIndex) < charCount. -or- byteIndex >= bytes.Length. If error-checking is turned off and an invalid surrogate sequence is detected, the invalid characters are ignored and are not encoded into bytes, and no exception is thrown. This method overrides System.Text.Encoding.GetBytes(System.Char[]). |
public System.Byte[] GetBytes(System.String s) Encodes the specified System.String as a System.Text.UTF8Encoding. Parameter s: The System.String to encode as a System.Text.UTF8Encoding. Returns: A System.Byte array containing the values encoded from s as a System.Text.UTF8Encoding. Throws: : Error-checking is turned on for the current instance and s contains an invalid surrogate sequence. Throws: : s is null. If error-checking is turned off and an invalid surrogate sequence is detected, the invalid characters are ignored and are not encoded into the returned System.Byte array, and no exception is thrown. This method overrides System.Text.Encoding.GetBytes(System.Char[]). |
public System.Int32 GetBytes(System.Char[] chars, System.Int32 charIndex, System.Int32 charCount, System.Byte[] bytes, System.Int32 byteIndex) Encodes the specified range of the specified System.Char array into the specified range of the specified System.Byte array as a System.Text.UTF8Encoding. Parameter chars: The System.Char array to encode as a System.Text.UTF8Encoding . Parameter charIndex: A System.Int32 that specifies the first index of chars to encode. Parameter charCount: A System.Int32 that specifies the number of characters to encode. Parameter bytes: The System.Byte array to encode into. Parameter byteIndex: A System.Int32 that specifies the first index of bytes to encode into. Returns: A System.Int32 that indicates the number of bytes encoded into bytes as a System.Text.UTF8Encoding. Throws: : bytes does not contain sufficient space to store the encoded characters. -or- Error-checking is turned on for the current instance and chars contains an invalid surrogate sequence. Throws: : chars or bytes is null. Throws: : charIndex, charCount, or byteIndex is less than zero. -or- (chars.Length - charIndex) < charCount. -or- byteIndex > bytes.Length. If error-checking is turned off and an invalid surrogate sequence is detected, the invalid characters are ignored and are not encoded into bytes, and no exception is thrown. This method overrides System.Text.Encoding.GetBytes(System.Char[]). System.Text.UTF8Encoding.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.UTF8Encoding.GetMaxByteCount(System.Int32) can be used to determine the maximum number of bytes that will be produced for a specified number of characters, regardless of the actual character values. |
public System.Int32 GetCharCount(System.Byte[] bytes, System.Int32 index, System.Int32 count) Returns the number of characters produced by decoding the specified range of the specified System.Byte array as a System.Text.UTF8Encoding . Parameter bytes: The System.Byte array to decode as a System.Text.UTF8Encoding . Parameter index: A System.Int32 that specifies the first index of bytes to decode. Parameter count: A System.Int32 that specifies the number of bytes to decode. Returns: A System.Int32 that indicates the number of characters produced by decoding the range in bytes from index to index + count - 1 as a System.Text.UTF8Encoding . Throws: : bytes is null. Throws: : index or count is less than zero. -or- index and count do not specify a valid range in bytes (i.e. (index + count) > bytes.Length). Throws: : Error-checking is turned on for the current instance and bytes contains an invalid surrogate sequence. If error-checking is turned off and an invalid surrogate sequence is detected, the invalid bytes are ignored and do not affect the return value, and no exception is thrown. This method overrides System.Text.Encoding.GetCharCount(System.Byte[]). |
public System.Int32 GetChars(System.Byte[] bytes, System.Int32 byteIndex, System.Int32 byteCount, System.Char[] chars, System.Int32 charIndex) Decodes the specified range of the specified System.Byte array into the specified range of the specified System.Char array as a System.Text.UTF8Encoding . Parameter bytes: The System.Byte array to decode as a System.Text.UTF8Encoding . Parameter byteIndex: A System.Int32 that specifies the first index of bytes to decode. Parameter byteCount: A System.Int32 that specifies the number of bytes to decode. Parameter chars: The System.Char array to decode into. Parameter charIndex: A System.Int32 that specifies the first index of chars to decode into. Returns: The number of characters decoded into chars as a System.Text.UTF8Encoding . Throws: : chars does not contain sufficient space to store the decoded characters. -or- Error-checking is turned on for the current instance and bytes contains an invalid surrogate sequence. Throws: : bytes or chars is null. Throws: : byteIndex, byteCount, or charIndex is less than zero. -or- (bytes.Length - byteIndex) < byteCount. -or- charIndex > chars.Length. If error-checking is turned off and an invalid surrogate sequence is detected, the invalid bytes are ignored and are not encoded into chars, and no exception is thrown. This method overrides System.Text.Encoding.GetChars(System.Byte[]) . System.Text.UTF8Encoding.GetCharCount(System.Byte[],System.Int32,System.Int32) can be used to determine the exact number of characters that will be produced for a specified range of bytes. Alternatively, System.Text.UTF8Encoding.GetMaxCharCount(System.Int32) can be used to determine the maximum number of characters that will be produced for a specified number of bytes, regardless of the actual byte values. |
public System.Text.Decoder GetDecoder() Returns a System.Text.Decoder for the current instance. Returns: A System.Text.Decoder for the current instance. This method overrides System.Text.Encoding.GetDecoder . Contrary to System.Text.UTF8Encoding.GetChars(System.Byte[],System.Int32,System.Int32,System.Char[],System.Int32) , a decoder can convert partial sequences of bytes into partial sequences of characters by maintaining the appropriate state between the conversions. |
public System.Text.Encoder GetEncoder() Returns a System.Text.Encoder for the current instance. Returns: A System.Text.Encoder for the current instance. This method overrides System.Text.Encoding.GetEncoder. Contrary to System.Text.UTF8Encoding.GetBytes(System.Char[],System.Int32,System.Int32,System.Byte[],System.Int32) , an encoder can convert partial sequences of characters into partial sequences of bytes by maintaining the appropriate state between the conversions. |
public System.Int32 GetHashCode() Generates a hash code for the current instance. Returns: A System.Int32 value containing a hash code for the current instance The algorithm used to generate the hash code is unspecified. This method overrides System.Object.GetHashCode. |
public System.Int32 GetMaxByteCount(System.Int32 charCount) Returns the maximum number of bytes required to encode the specified number of characters as a System.Text.UTF8Encoding, regardless of the actual character values. Parameter charCount: A System.Int32 that specifies the number of characters to encode as a System.Text.UTF8Encoding . Returns: A System.Int32 that specifies the maximum number of bytes required to encode charCount characters as a System.Text.UTF8Encoding . Throws: : charCount < 0. This method overrides System.Text.Encoding.GetMaxByteCount(System.Int32) . This method can be used to determine an appropriate buffer size for byte arrays passed to System.Text.UTF8Encoding.GetBytes(System.Char[],System.Int32,System.Int32,System.Byte[],System.Int32). Using this minimum buffer size can help ensure that no buffer overflow exceptions will occur. |
public System.Int32 GetMaxCharCount(System.Int32 byteCount) Returns the maximum number of characters produced by decoding the specified number of bytes as a System.Text.UTF8Encoding, regardless of the actual byte values. Parameter byteCount: A System.Int32 that specifies the number of bytes to decode as a System.Text.UTF8Encoding . Returns: A System.Int32 that specifies the maximum number of characters produced by decoding byteCount bytes as a System.Text.UTF8Encoding . Throws: : byteCount < 0. This method overrides System.Text.Encoding.GetMaxCharCount(System.Int32) . This method can be used to determine an appropriate minimum buffer size for character arrays passed to System.Text.UTF8Encoding.GetChars(System.Byte[],System.Int32,System.Int32,System.Char[],System.Int32) . Using this minimum buffer size can help ensure that no buffer overflow exceptions will occur. |
public System.Byte[] GetPreamble() Returns the bytes used at the beginning of a stream to determine which encoding a file was created with. Returns: A System.Byte array containing the UTF-8 encoding preamble. This method overrides System.Text.Encoding.GetPreamble . System.Text.UTF8Encoding.GetPreamble returns the Unicode byte order mark (U+FEFF) written in UTF-8 (0xef, 0xbb, 0xbf) if this instance was constructed with a request to emit the UTF-8 identifier. |
| Functions inherited from System.Text.Encoding: |
|---|
public static System.Byte[] Convert(System.Text.Encoding srcEncoding, System.Text.Encoding dstEncoding, System.Byte[] bytes, System.Int32 index, System.Int32 count) Converts the specified range of the specified System.Byte array from one specified encoding to another specified encoding. Parameter srcEncoding: The System.Text.Encoding that bytes is in. Parameter dstEncoding: The System.Text.Encoding desired for the returned System.Byte array. Parameter bytes: The System.Byte array containing the values to convert. Parameter index: A System.Int32 containing the first index of bytes from which to convert. Parameter count: A System.Int32 containing the number of bytes to convert. Returns: A System.Byte array containing the result of the conversion. Throws: : srcEncoding, dstEncoding , or bytes is null. Throws: : index and count do not denote a valid range in bytes . |
public static System.Byte[] Convert(System.Text.Encoding srcEncoding, System.Text.Encoding dstEncoding, System.Byte[] bytes) Converts the specified System.Byte array from one specified encoding to another specified encoding. Parameter srcEncoding: The System.Text.Encoding that bytes is in. Parameter dstEncoding: The System.Text.Encoding desired for the returned System.Byte array. Parameter bytes: The System.Byte array containing the values to convert. Returns: A System.Byte array containing the result of the conversion. Throws: : srcEncoding, dstEncoding or bytes is null. |
public System.Boolean Equals(System.Object value) Determines whether the current instance and the specified System.Object represent the same type and value. Parameter value: The System.Object to compare to the current instance. Returns: true if obj represents the same type and value as the current instance. If obj is a null reference or is not an instance of System.Text.Encoding, returns false. This method overrides System.Object.Equals(System.Object). |
public virtual System.Int32 GetByteCount(System.Char[] chars) Returns the number of bytes required to encode the specified System.Char array. Parameter chars: The System.Char array to encode. Returns: A System.Int32 containing the number of bytes needed to encode chars. Throws: : chars is null. As described above. This method is overridden by types derived from System.Text.Encoding to return the appropriate number of bytes for the particular encoding. 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. |
public virtual System.Int32 GetByteCount(System.String s) Returns the number of bytes required to encode the specified System.String. Parameter s: The System.String to decode. Returns: A System.Int32 containing the number of bytes needed to encode s. Throws: : s is null. As described above. This method is overridden by types derived from System.Text.Encoding to return the appropriate number of bytes for the particular encoding. System.Text.Encoding.GetByteCount(System.Char[]) can be used to determine the exact number of bytes that will be produced from encoding the given System.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. |
public System.Int32 GetByteCount(System.Char[] chars, System.Int32 index, System.Int32 count) Returns the number of bytes required to encode the specified range of characters in the specified Unicode character array. Parameter chars: The System.Char array to encode. Parameter index: A System.Int32 containing the first index of chars to encode. Parameter count: A System.Int32 containing the number of characters to encode. Returns: A System.Int32 containing the number of bytes required to encode the range in chars from index to index + count - 1. Throws: : chars is null . Throws: : 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). As described above. This method is overridden by types derived from System.Text.Encoding to return the appropriate number of bytes for the particular encoding. 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. |
public virtual System.Byte[] GetBytes(System.Char[] chars) Encodes the specified System.Char array. Parameter chars: The System.Char array to encode. Returns: A System.Byte array containing the encoded representation of chars. Throws: : chars is null. As described above. This method is overridden by types derived from System.Text.Encoding to perform the encoding. |
public virtual System.Byte[] GetBytes(System.Char[] chars, System.Int32 index, System.Int32 count) Encodes the specified range of the specified System.Char array. Parameter chars: The System.Char array to encode. Parameter index: A System.Int32 containing the first index of chars to encode. Parameter count: A System.Int32 containing the number of characters to encode. Returns: A System.Byte array containing the encoded representation of the range in chars from index to index + count - 1. Throws: : chars is null. Throws: : index and count do not denote a valid range in chars. As described above. This method is overridden by types derived from System.Text.Encoding to perform the encoding. |
public System.Int32 GetBytes(System.Char[] chars, System.Int32 charIndex, System.Int32 charCount, System.Byte[] bytes, System.Int32 byteIndex) Encodes the specified range of the specified System.Char array into the specified range of the specified System.Byte array. Parameter chars: A System.Char array to encode. Parameter charIndex: A System.Int32 containing the first index of chars to encode. Parameter charCount: A System.Int32 containing the number of characters to encode. Parameter bytes: A System.Byte array to encode into. Parameter byteIndex: A System.Int32 containing the first index of bytes to encode into. Returns: The number of bytes encoded into bytes . Throws: : bytes does not contain sufficient space to store the encoded characters. Throws: : chars is null. -or- bytes is null. Throws: : charIndex < 0. -or- charCount < 0. -or- byteIndex < 0. -or- (chars.Length - charIndex) < charCount. -or- byteIndex > bytes.Length. As described above. This method is overridden by types derived from System.Text.Encoding to perform the encoding. 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. |
public virtual System.Byte[] GetBytes(System.String s) Encodes the specified System.String. Parameter s: The System.String to encode. Returns: A System.Byte array containing the encoded representation of s. Throws: : s is null. As described above. This method is overridden by types derived from System.Text.Encoding to perform the encoding. |
public virtual System.Int32 GetBytes(System.String s, System.Int32 charIndex, System.Int32 charCount, System.Byte[] bytes, System.Int32 byteIndex) Encodes the specified range of the specified System.String into the specified range of the specified System.Byte array. Parameter s: A System.String to encode. Parameter charIndex: A System.Int32 containing the first index of s from which to encode. Parameter charCount: A System.Int32 containing the number of characters of s to encode. Parameter bytes: The System.Byte array to encode into. Parameter byteIndex: A System.Int32 containing the first index of bytes to encode into. Returns: A System.Int32 containing the number of bytes encoded into bytes. Throws: : bytes does not contain sufficient space to store the encoded characters. Throws: : s is null. -or- bytes is null. Throws: : charIndex < 0. -or- charCount < 0. -or- byteIndex < 0. -or- (s.Length - charIndex) < charCount. -or- byteIndex >= bytes.Length. As described above. This method is overridden by types derived from System.Text.Encoding to perform the encoding. |
public virtual System.Int32 GetCharCount(System.Byte[] bytes) Determines the exact number of characters that will be produced by decoding the specified System.Byte array. Parameter bytes: The System.Byte array to decode. Returns: A System.Int32 containing the number of characters produced by decoding bytes. Throws: : bytes is null. As described above. This method is overridden by types derived from System.Text.Encoding to return the appropriate number of bytes for the particular encoding. 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. |
public System.Int32 GetCharCount(System.Byte[] bytes, System.Int32 index, System.Int32 count) Determines the exact number of characters that will be produced by decoding the specified range of the specified System.Byte array. Parameter bytes: The System.Byte array to decode. Parameter index: The first index in bytes to decode. Parameter count: The number of bytes to decode. Returns: A System.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. Throws: : bytes is null. Throws: : index and count do not specify a valid range in bytes (i.e. (index + count) > bytes.Length). As described above. This method is overridden by types derived from System.Text.Encoding to return the appropriate number of bytes for the particular encoding. 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. |
public virtual System.Char[] GetChars(System.Byte[] bytes) Decodes a System.Byte array. Parameter bytes: The System.Byte array to decode. Returns: A System.Char array produced by decoding bytes . Throws: : bytes is null. |
public virtual System.Char[] GetChars(System.Byte[] bytes, System.Int32 index, System.Int32 count) Decodes the specified range of the specified System.Byte array. Parameter bytes: The System.Byte array to decode. Parameter index: A System.Int32 containing the first index of bytes to decode. Parameter count: A System.Int32 containing the number of bytes to decode. Returns: A System.Char array containing the decoded representation of the range in bytes between index to index + count . Throws: : bytes is null . Throws: : index and count do not denote a valid range in the byte array. |
public System.Int32 GetChars(System.Byte[] bytes, System.Int32 byteIndex, System.Int32 byteCount, System.Char[] chars, System.Int32 charIndex) Decodes the specified range of the specified System.Byte array into the specified range of the specified System.Char array. Parameter bytes: The System.Byte array to decode. Parameter byteIndex: A System.Int32 containing the first index of bytes to decode. Parameter byteCount: A System.Int32 containing the number of bytes to decode. Parameter chars: The System.Char array to decode into. Parameter charIndex: A System.Int32 containing the first index of chars to decode into. Returns: The number of characters stored in chars. Throws: : chars does not contain sufficient space to store the decoded characters. Throws: : bytes is null . -or- chars is null . Throws: : 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. 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. This method is overridden by types derived from System.Text.Encoding to perform the particular decoding. When using this method directly on a System.Text.Encoding object or on an associated System.Text.Decoder or System.Text.Encoder, use System.Text.Encoding.GetCharCount(System.Byte[]) or System.Text.Encoding.GetMaxCharCount(System.Int32) to allocate destination buffers. |
public virtual System.Text.Decoder GetDecoder() Returns a System.Text.Decoder for the current instance. Returns: A System.Text.Decoder for the current instance. As described above. The default implementation returns a System.Text.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. Encoding that requires state to be maintained between successive conversions should override this method and return an instance of an appropriate System.Text.Decoder implementation. Unlike the System.Text.Encoding.GetChars(System.Byte[]) methods, a System.Text.Decoder can convert partial sequences of bytes into partial sequences of characters by maintaining the appropriate state between the conversions. |
public virtual System.Text.Encoder GetEncoder() Returns a System.Text.Encoder for the current instance. Returns: A System.Text.Encoder for the current encoding. As described above. The default implementation returns a System.Text.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. Types derived from System.Text.Encoding override this method to return an instance of an appropriate System.Text.Encoder . Unlike the System.Text.Encoding.GetBytes(System.Char[]) method, a System.Text.Encoder can convert partial sequences of characters into partial sequences of bytes by maintaining the appropriate state between the conversions. |
public System.Int32 GetHashCode() Generates a hash code for the current instance. Returns: A System.Int32 containing the hash code for the current instance. The algorithm used to generate the hash code is unspecified. This method overrides System.Object.GetHashCode. |
public System.Int32 GetMaxByteCount(System.Int32 charCount) Returns the maximum number of bytes required to encode the specified number of characters, regardless of the actual character values. Parameter charCount: A System.Int32 containing the number of characters to encode. Returns: A System.Int32 containing the maximum number of bytes required to encode charCount characters. As described above. This method is overridden by types derived from System.Text.Encoding to return the appropriate number of bytes for the particular encoding. 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. |
public System.Int32 GetMaxCharCount(System.Int32 byteCount) Returns the maximum number of characters produced by decoding the specified number of bytes, regardless of the actual byte values. Parameter byteCount: A System.Int32 containing the number of bytes to decode. Returns: A System.Int32 containing the maximum number of characters that would be produced by decoding byteCount bytes. As described above. This method is overridden by types derived from System.Text.Encoding to return the appropriate number of bytes for the particular encoding. 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. |
public virtual System.Byte[] GetPreamble() Returns the bytes used at the beginning of a System.IO.Stream to determine which System.Text.Encoding the stream was created with. Returns: A System.Byte array that identifies the encoding used on a stream. 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. As described above. The default implementation returns an empty System.Byte array. Override this method to return a System.Byte array containing the preamble appropriate for the type derived from System.Text.Encoding . |
public virtual System.String GetString(System.Byte[] bytes) Decodes the specified System.Byte array. Parameter bytes: The System.Byte array to decode. Returns: A System.String containing the decoded representation of bytes. Throws: : bytes is null. As described above. This method is overridden by particular character encodings. |
public virtual System.String GetString(System.Byte[] bytes, System.Int32 index, System.Int32 count) Decodes the specified range of the specified System.Byte array. Parameter bytes: The System.Byte array to decode. Parameter index: A System.Int32 containing the starting index of bytes to decode. Parameter count: A System.Int32 containing the number of bytes to decode. Returns: A System.String containing the decoded representation of the range of bytes from index to index + count. Throws: : bytes is null. Throws: : index and count do not denote a valid range in bytes. As described above. This method is overridden by particular character encodings. |
| Functions inherited from System.Object: |
|---|
public virtual System.Boolean Equals(System.Object obj) Determines whether the specified System.Object is equal to the current instance. Parameter obj: The System.Object to compare with the current instance. Returns: true if obj is equal to the current instance; otherwise, false. The statements listed below are required to be true for all implementations of the System.Object.Equals(System.Object) method. In the list, x, y, and z represent non-null object references. See System.Object.GetHashCode for additional required behaviors pertaining to the System.Object.Equals(System.Object) method. Implementations of System.Object.Equals(System.Object) should not throw exceptions. The System.Object.Equals(System.Object) method tests for referential equality , which means that System.Object.Equals(System.Object) returns true if the specified instance of Object and the current instance are the same instance; otherwise, it returns false . An implementation of the System.Object.Equals(System.Object) method is shown in the following C# code: public virtual bool Equals(Object obj) { return this == obj; } For some kinds of objects, it is desirable to have System.Object.Equals(System.Object) test for value equality instead of referential equality. Such implementations of Equals return true if the two objects have the same "value", even if they are not the same instance. The definition of what constitutes an object's "value" is up to the implementer of the type, but it is typically some or all of the data stored in the instance variables of the object. For example, the value of a System.String is based on the characters of the string; the Equals method of the System.String class returns true for any two string instances that contain exactly the same characters in the same order. When the Equals method of a base class provides value equality, an override of Equals in a class derived from that base class should invoke the inherited implementation of Equals . It is recommended (but not required) that types overriding System.Object.Equals(System.Object) also override System.Object.GetHashCode. Hashtables cannot be relied on to work correctly if this recommendation is not followed. If your programming language supports operator overloading, and if you choose to overload the equality operator for a given type, that type should override the Equals method. Such implementations of the Equals method should return the same results as the equality operator. Following this guideline will help ensure that class library code using Equals (such as System.Collections.ArrayList and System.Collections.Hashtable ) behaves in a manner that is consistent with the way the equality operator is used by application code. If you are implementing a value type, you should follow these guidelines: For reference types, the guidelines are as follows: If you implement System.IComparable on a given type, you should override Equals on that type. The System.Object.Equals(System.Object) method is called by methods in collections classes that perform search operations, including the System.Array.IndexOf(System.Array,System.Object) method and the System.Collections.ArrayList.Contains(System.Object) method. Example: Example 1: The following example contains two calls to the default implementation of System.Object.Equals(System.Object) . using System;
class MyClass {
static void Main() {
Object obj1 = new Object();
Object obj2 = new Object();
Console.WriteLine(obj1.Equals(obj2));
obj1 = obj2;
Console.WriteLine(obj1.Equals(obj2));
}
}
The output is False True Example 2: The following example shows a Point class that overrides the System.Object.Equals(System.Object) method to provide value equality and a class Point3D, which is derived from Point . Because Point's override of System.Object.Equals(System.Object) is the first in the inheritance chain to introduce value equality, the Equals method of the base class (which is inherited from System.Object and checks for referential equality) is not invoked. However, Point3D.Equals invokes Point.Equals because Point implements Equals in a manner that provides value equality. using System;
public class Point: object {
int x, y;
public override bool Equals(Object obj) {
//Check for null and compare run-time types.
if (obj == null || GetType() != obj.GetType()) return false;
Point p = (Point)obj;
return (x == p.x) && (y == p.y);
}
public override int GetHashCode() {
return x ^ y;
}
}
class Point3D: Point {
int z;
public override bool Equals(Object obj) {
return base.Equals(obj) && z == ((Point3D)obj).z;
}
public override int GetHashCode() {
return base.GetHashCode() ^ z;
}
}
The Point.Equals method checks that the obj
argument is non-null and that it references an instance of the same type as this
object. If either of those checks fail, the method returns false. The
System.Object.Equals(System.Object) method uses
System.Object.GetType to determine whether
the run-time types of the two objects are identical. (Note that
typeof is not used here because it returns the static type.) If
instead the method had used a check of the form
In Point3D.Equals , the inherited Equals method is invoked before anything else is done; the inherited Equals method checks to see that obj is non-null, that obj is an instance of the same class as this object, and that the inherited instance variables match. Only when the inherited Equals returns true does the method compare the instance variables introduced in the subclass. Specifically, the cast to Point3D is not executed unless obj has been determined to be of type Point3D or a subclass of Point3D . Example 3: In the previous example, operator == (the equality operator) is used to compare the individual instance variables. In some cases, it is appropriate to use the System.Object.Equals(System.Object) method to compare instance variables in an Equals implementation, as shown in the following example: using System;
class Rectangle {
Point a, b;
public override bool Equals(Object obj) {
if (obj == null || GetType() != obj.GetType()) return false;
Rectangle r = (Rectangle)obj;
//Use Equals to compare instance variables
return a.Equals(r.a) && b.Equals(r.b);
}
public override int GetHashCode() {
return a.GetHashCode() ^ b.GetHashCode();
}
}
Example 4: In some languages, such as C#, operator overloading is supported. When a type overloads operator ==, it should also override the System.Object.Equals(System.Object) method to provide the same functionality. This is typically accomplished by writing the Equals method in terms of the overloaded operator ==. For example: using System;
public struct Complex {
double re, im;
public override bool Equals(Object obj) {
return obj is Complex && this == (Complex)obj;
}
public override int GetHashCode() {
return re.GetHashCode() ^ im.GetHashCode();
}
public static bool operator ==(Complex x, Complex y) {
return x.re == y.re && x.im == y.im;
}
public static bool operator !=(Complex x, Complex y) {
return !(x == y);
}
}
Because Complex is a C# struct (a value type), it is known that there will be no subclasses of Complex . Therefore, the System.Object.Equals(System.Object) method need not compare the GetType() results for each object, but can instead use the is operator to check the type of the obj parameter. |
public static System.Boolean Equals(System.Object objA, System.Object objB) Determines whether two object references are equal. Parameter objA: First object to compare. Parameter objB: Second object to compare. Returns: true if one or more of the following statements is true: otherwise returns false. This static method checks for null references before it calls objA.Equals(objB ) and returns false if either objA or objB is null. If the Equals(object obj) implementation throws an exception, this method throws an exception. Example: The following example demonstrates the System.Object.Equals(System.Object) method. using System;
public class MyClass {
public static void Main() {
string s1 = "Tom";
string s2 = "Carol";
Console.WriteLine("Object.Equals(\"{0}\", \"{1}\") => {2}",
s1, s2, Object.Equals(s1, s2));
s1 = "Tom";
s2 = "Tom";
Console.WriteLine("Object.Equals(\"{0}\", \"{1}\") => {2}",
s1, s2, Object.Equals(s1, s2));
s1 = null;
s2 = "Tom";
Console.WriteLine("Object.Equals(null, \"{1}\") => {2}",
s1, s2, Object.Equals(s1, s2));
s1 = "Carol";
s2 = null;
Console.WriteLine("Object.Equals(\"{0}\", null) => {2}",
s1, s2, Object.Equals(s1, s2));
s1 = null;
s2 = null;
Console.WriteLine("Object.Equals(null, null) => {2}",
s1, s2, Object.Equals(s1, s2));
}
}
The output is Object.Equals("Tom", "Carol") => False Object.Equals("Tom", "Tom") => True Object.Equals(null, "Tom") => False Object.Equals("Carol", null) => False Object.Equals(null, null) => True |
public System.Void Finalize() Allows a System.Object to perform cleanup operations before the memory allocated for the System.Object is automatically reclaimed. During execution, System.Object.Finalize is automatically called after an object becomes inaccessible, unless the object has been exempted from finalization by a call to System.GC.SuppressFinalize(System.Object). During shutdown of an application domain, System.Object.Finalize is automatically called on objects that are not exempt from finalization, even those that are still accessible. System.Object.Finalize is automatically called only once on a given instance, unless the object is re-registered using a mechanism such as System.GC.ReRegisterForFinalize(System.Object) and System.GC.SuppressFinalize(System.Object) has not been subsequently called. Conforming implementations of the CLI are required to make every effort to ensure that for every object that has not been exempted from finalization, the System.Object.Finalize method is called after the object becomes inaccessible. However, there may be some circumstances under which Finalize is not called. Conforming CLI implementations are required to explicitly specify the conditions under which Finalize is not guaranteed to be called. For example, Finalize might not be guaranteed to be called in the event of equipment failure, power failure, or other catastrophic system failures. In addition to System.GC.ReRegisterForFinalize(System.Object) and System.GC.SuppressFinalize(System.Object), conforming implementations of the CLI are allowed to provide other mechanisms that affect the behavior of System.Object.Finalize . Any mechanisms provided are required to be specified by the CLI implementation. The order in which the Finalize methods of two objects are run is unspecified, even if one object refers to the other. The thread on which Finalize is run is unspecified. Every implementation of System.Object.Finalize in a derived type is required to call its base type's implementation of Finalize . This is the only case in which application code calls System.Object.Finalize . The System.Object.Finalize implementation does nothing. A type should implement Finalize when it uses unmanaged resources such as file handles or database connections that must be released when the managed object that uses them is reclaimed. Because Finalize methods may be invoked in any order (including from multiple threads), synchronization may be necessary if the Finalize method may interact with other objects, whether accessible or not. Furthermore, since the order in which Finalize is called is unspecified, implementers of Finalize (or of destructors implemented through overriding Finalize) must take care to correctly handle references to other objects, as their Finalize method may already have been invoked. In general, referenced objects should not be considered valid during finalization. See the System.IDisposable interface for an alternate means of disposing of resources. For C# developers: Destructors are the C# mechanism for performing cleanup operations. Destructors provide appropriate safeguards, such as automatically calling the base type's destructor. In C# code, System.Object.Finalize cannot be called or overridden. |
public virtual System.Int32 GetHashCode() Generates a hash code for the current instance. Returns: A System.Int32 containing the hash code for the current instance. System.Object.GetHashCode serves as a hash function for a specific type. A hash function is used to quickly generate a number (a hash code) corresponding to the value of an object. Hash functions are used with hashtables. A good hash function algorithm rarely generates hash codes that collide. For more information about hash functions, see The Art of Computer Programming , Vol. 3, by Donald E. Knuth. All implementations of System.Object.GetHashCode are required to ensure that for any two object references x and y, if x.Equals(y) == true, then x.GetHashCode() == y.GetHashCode(). Hash codes generated by System.Object.GetHashCode need not be unique. Implementations of System.Object.GetHashCode are not permitted to throw exceptions. The System.Object.GetHashCode implementation attempts to produce a unique hash code for every object, but the hash codes generated by this method are not guaranteed to be unique. Therefore, System.Object.GetHashCode may generate the same hash code for two different instances. It is recommended (but not required) that types overriding System.Object.GetHashCode also override System.Object.Equals(System.Object) . Hashtables cannot be relied on to work correctly if this recommendation is not followed. Use this method to obtain the hash code of an object. Hash codes should not be persisted (i.e. in a database or file) as they are allowed to change from run to run. Example: Example 1 In some cases, System.Object.GetHashCode is implemented to simply return an integer value. The following example illustrates an implementation of System.Int32.GetHashCode , which returns an integer value: using System;
public struct Int32 {
int value;
//other methods...
public override int GetHashCode() {
return value;
}
}
Example 2 Frequently, a type has multiple data members that can participate in generating the hash code. One way to generate a hash code is to combine these fields using an xor (exclusive or) operation, as shown in the following example: using System;
public struct Point {
int x;
int y;
//other methods
public override int GetHashCode() {
return x ^ y;
}
}
Example 3 The following example illustrates another case where the type's fields are combined using xor (exclusive or) to generate the hash code. Notice that in this example, the fields represent user-defined types, each of which implements System.Object.GetHashCode (and should implement System.Object.Equals(System.Object) as well): using System;
public class SomeType {
public override int GetHashCode() {
return 0;
}
}
public class AnotherType {
public override int GetHashCode() {
return 1;
}
}
public class LastType {
public override int GetHashCode() {
return 2;
}
}
public class MyClass {
SomeType a = new SomeType();
AnotherType b = new AnotherType();
LastType c = new LastType();
public override int GetHashCode () {
return a.GetHashCode() ^ b.GetHashCode() ^ c.GetHashCode();
}
}
Avoid implementing System.Object.GetHashCode in a manner that results in circular references. In other words, if AClass.GetHashCode calls BClass.GetHashCode, it should not be the case that BClass.GetHashCode calls AClass.GetHashCode. Example 4 In some cases, the data member of the class in which you are implementing System.Object.GetHashCode is bigger than a System.Int32. In such cases, you could combine the high order bits of the value with the low order bits using an XOR operation, as shown in the following example: using System;
public struct Int64 {
long value;
//other methods...
public override int GetHashCode() {
return ((int)value ^ (int)(value >> 32));
}
}
|
public System.Type GetType() Gets the type of the current instance. Returns: The instance of System.Type that represents the run-time type (the exact type) of the current instance. For two objects x and y that have identical run-time types, System.Object.ReferenceEquals(System.Object,System.Object)(x.GetType(),y.GetType()) returns true . Example: The following example demonstrates the fact that System.Object.GetType returns the run-time type of the current instance: using System;
public class MyBaseClass: Object {
}
public class MyDerivedClass: MyBaseClass {
}
public class Test {
public static void Main() {
MyBaseClass myBase = new MyBaseClass();
MyDerivedClass myDerived = new MyDerivedClass();
object o = myDerived;
MyBaseClass b = myDerived;
Console.WriteLine("mybase: Type is {0}", myBase.GetType());
Console.WriteLine("myDerived: Type is {0}", myDerived.GetType());
Console.WriteLine("object o = myDerived: Type is {0}", o.GetType());
Console.WriteLine("MyBaseClass b = myDerived: Type is {0}", b.GetType());
}
}
The output is mybase: Type is MyBaseClass myDerived: Type is MyDerivedClass object o = myDerived: Type is MyDerivedClass MyBaseClass b = myDerived: Type is MyDerivedClass |
protected System.Object MemberwiseClone() Creates a shallow copy of the current instance. Returns: A shallow copy of the current instance. The run-time type (the exact type) of the returned object is the same as the run-time type of the object that was copied. System.Object.MemberwiseClone creates a new instance of the same type as the current instance and then copies each of the object's non-static fields in a manner that depends on whether the field is a value type or a reference type. If the field is a value type, a bit-by-bit copy of all the field's bits is performed. If the field is a reference type, only the reference is copied. The algorithm for performing a shallow copy is as follows (in pseudo-code): for each instance field f in this instance if (f is a value type) bitwise copy the field if (f is a reference type) copy the reference end for loop This mechanism is referred to as a shallow copy because it copies rather than clones the non-static fields. Because System.Object.MemberwiseClone implements the above algorithm, for any object, a, the following statements are required to be true: System.Object.MemberwiseClone does not call any of the type's constructors. If System.Object.Equals(System.Object) has been overridden, a.MemberwiseClone().Equals(a) might return false . For an alternate copying mechanism, see System.ICloneable . System.Object.MemberwiseClone is protected (rather than public) to ensure that from verifiable code it is only possible to clone objects of the same class as the one performing the operation (or one of its subclasses). Although cloning an object does not directly open security holes, it does allow an object to be created without running any of its constructors. Since these constructors may establish important invariants, objects created by cloning may not have these invariants established, and this may lead to incorrect program behavior. For example, a constructor might add the new object to a linked list of all objects of this class, and cloning the object would not add the new object to that list -- thus operations that relied on the list to locate all instances would fail to notice the cloned object. By making the method protected, only objects of the same class (or a subclass) can produce a clone and implementers of those classes are (presumably) aware of the appropriate invariants and can arrange for them to be true without necessarily calling a constructor. Example: The following example shows a class called MyClass as well as a representation of the instance of MyClass returned by System.Object.MemberwiseClone . using System;
class MyBaseClass {
public static string CompanyName = "My Company";
public int age;
public string name;
}
class MyDerivedClass: MyBaseClass {
static void Main() {
//Create an instance of MyDerivedClass
//and assign values to its fields.
MyDerivedClass m1 = new MyDerivedClass();
m1.age = 42;
m1.name = "Sam";
//Do a shallow copy of m1
//and assign it to m2.
MyDerivedClass m2 = (MyDerivedClass) m1.MemberwiseClone();
}
}
A graphical representation of m1 and m2 might look like this
+---------------+
| 42 | m1
+---------------+
| +---------|-----------------> "Sam"
+---------------+ /|\
|
+---------------+ |
| 42 | | m2
+---------------+ |
| +--------|---------------------|
+---------------+
|
public static System.Boolean ReferenceEquals(System.Object objA, System.Object objB) Determines whether two object references are identical. Parameter objA: First object to compare. Parameter objB: Second object to compare. Returns: True if a and b refer to the same object or are both null references; otherwise, false. This static method provides a way to compare two objects for reference equality. It does not call any user-defined code, including overrides of System.Object.Equals(System.Object) . Example: using System;
class MyClass {
static void Main() {
object o = null;
object p = null;
object q = new Object();
Console.WriteLine(Object.ReferenceEquals(o, p));
p = q;
Console.WriteLine(Object.ReferenceEquals(p, q));
Console.WriteLine(Object.ReferenceEquals(o, p));
}
}
The output is True True False |
public virtual System.String ToString() Creates and returns a System.String representation of the current instance. Returns: A System.String representation of the current instance. System.Object.ToString returns a string whose content is intended to be understood by humans. Where the object contains culture-sensitive data, the string representation returned by System.Object.ToString takes into account the current system culture. For example, for an instance of the System.Double class whose value is zero, the implementation of System.Double.ToString might return "0.00" or "0,00" depending on the current UI culture. Although there are no exact requirements for the format of the returned string, it should as much as possible reflect the value of the object as perceived by the user. System.Object.ToString is equivalent to calling System.Object.GetType to obtain the System.Type object for the current instance and then returning the result of calling the System.Object.ToString implementation for that type. The value returned includes the full name of the type. It is recommended, but not required, that System.Object.ToString be overridden in a derived class to return values that are meaningful for that type. For example, the base data types, such as System.Int32, implement System.Object.ToString so that it returns the string form of the value the object represents. Subclasses that require more control over the formatting of strings than System.Object.ToString provides should implement System.IFormattable, whose System.Object.ToString method uses the culture of the current thread. Example: The following example outputs the textual description of the value of an object of type System.Object to the console. using System;
class MyClass {
static void Main() {
object o = new object();
Console.WriteLine (o.ToString());
}
}
The output is System.Object |