MLML System.Uri API Documentation

Type System.Uri

Variables:
public System.String AbsolutePath
public System.String AbsoluteUri
public System.String Authority
public System.String Fragment
public System.String Host
public System.UriHostNameType HostNameType
public System.Boolean IsDefaultPort
public System.Boolean IsFile
public System.Boolean IsLoopback
public System.String LocalPath
public System.String PathAndQuery
public System.Int32 Port
public System.String Query
public System.String Scheme
public System.Boolean UserEscaped
public System.String UserInfo

Constructors:

Constructors:
public System.Uri(System.String uriString) Constructs and initializes a new instance of the `System.Uri` class by parsing the specified URI. Parameter `uriString`: A `System.String` containing a URI. Throws: : `uriString` is `null` . Throws: : `uriString` is a zero length string or contains only spaces. `uriString` is in an invalid form and cannot be parsed. This constructor is equivalent to calling the `System.Uri` (`System.String`, `System.Boolean`) constructor, and specifying `uriString` and `false` as the arguments.
public System.Uri(System.String uriString, System.Boolean dontEscape) Constructs and initializes a new instance of the `System.Uri` class by parsing the specified URI. Parameter `uriString`: A `System.String` containing a URI. Parameter `dontEscape`: `true` if the URI in `uriString` is already escaped; otherwise, `false`. Throws: : `uriString` is `null` . Throws: : `uriString` is a zero length string or contains only spaces. The parsing routine detected a scheme in an invalid form. The parser detected more than two consecutive slashes in a URI that does not use the "file" scheme. `uriString` is in an invalid form and cannot be parsed. This constructor parses the URI, places its components into the appropriate properties, and puts the URI in canonical form. If the specified URI does not contain a scheme component, the URI is parsed using "file" as the scheme. Example: The following example creates a `System.Uri` instance for the URI "http://www.contoso.com/Hello%20World.htm". Because the URI contains escaped characters, the third parameter, `dontEscape` , is set to `true` . using System; public class UriTest { public static void Main() { Uri myUri = new Uri("http://www.contoso.com/Hello%20World.htm", true); Console.WriteLine(myUri.ToString()); } } The output is http://www.contoso.com/Hello World.htm
public System.Uri(System.Uri baseUri, System.String relativeUri) Constructs and initializes a new instance of the `System.Uri` class by combining the specified base and relative URIs. Parameter `baseUri`: A `System.Uri` containing a base URI. Parameter `relativeUri`: A `System.String` containing a relative URI. Throws: : `relativeUri` is in an invalid form. Throws: : `baseUri` is `null`. This constructor is equivalent to calling the `System.Uri` (`System.Uri`, `System.String`, `System.Boolean`) constructor, and specifying `baseUri, relativeUri,` and `false` as the arguments.
public System.Uri(System.Uri baseUri, System.String relativeUri, System.Boolean dontEscape) Constructs and initializes a new instance of the `System.Uri` class by combining the specified base and relative URIs. Parameter `baseUri`: A `System.Uri` containing the base URI. This parameter can, but is not required to contain a terminating slash ("/") character. Parameter `relativeUri`: A `System.String` containing the relative URI to add to the base URI. This parameter can, but is not required to contain a leading slash ("/") character. Parameter `dontEscape`: `true` if `baseUri` and `relativeUri` are already escaped; otherwise, `false`. Throws: : `relativeUri` is in an invalid form. Throws: : `baseUri` is `null`. This constructor compensates for the presence or absence of a terminating slash in `baseUri` and/or a leading slash in `relativeUri` to produce a well-formed URI. If the relative URI contains a System.Uri.Scheme that is the same as the scheme of the base URI and the System.Uri.SchemeDelimiter is not present, or the relative URI does not contain a scheme, the new instance is composed of the relative URI (without its scheme component, if any) qualified by the scheme and authority information from the base URI. If the relative URI contains a System.Uri.Scheme followed by the System.Uri.SchemeDelimiter, it is treated as an absolute URI and the base URI is ignored. If the relative URI contains a scheme that differs from the scheme of the base URI, the base URI is ignored. If the System.Uri.SchemeDelimiter is not present in the relative URI, it is assumed, and the new instance is constructed as though the relative URI were an absolute URI. When the base URI is ignored, only the components of the relative URI are used to construct the new instance. Example: The following example creates new instances of the `System.Uri` class by combining a `System.Uri` instance representing the base URI and a string containing a relative URI. using System; public class UriTest { public static void Main() { // Typical base and relative URI constructor usage. Uri baseUri = new Uri("http://www.contoso.com", true); Uri myUri = new Uri(baseUri, "index.htm",true); Console.WriteLine("Typical usage: {0}",myUri.ToString()); // Base and relative URI contain slashes. Uri baseUri2 = new Uri("http://www.contoso.com/", true); Uri myUri2 = new Uri(baseUri2, "/index.htm",true); Console.WriteLine("Slash example: {0}",myUri2.ToString()); // Relative URI contains a different scheme than the base URI. Uri baseUri3 = new Uri("http://www.contoso.com/", true); Uri myUri3 = new Uri(baseUri3, "ftp://www.contoso2.com/index.htm",true); Console.WriteLine("Different schemes: {0}", myUri3.ToString()); // Relative URI contains the same scheme as the base URI. // The scheme delimiter is not present in the relative URI. Uri baseUri4 = new Uri("http://www.contoso.com/", true); Uri myUri4 = new Uri(baseUri4, "http:www.contoso2.com/index.htm",true); Console.WriteLine("Same schemes - relative treated as relative: {0}",myUri4.ToString()); // Relative URI contains the same scheme as the base URI. // The scheme delimiter is present in the relative URI. Uri baseUri5 = new Uri("http://www.contoso.com/", true); Uri myUri5 = new Uri(baseUri5, "http://www.contoso2/index.htm",true); Console.WriteLine("Same schemes - relative treated as absolute: {0}",myUri5.ToString()); } } The output is Typical usage: http://www.contoso.com/index.htm Slash example: http://www.contoso.com/index.htm Different schemes: ftp://www.contoso2.com/index.htm Same schemes - relative treated as relative: http://www.contoso.com/www.contoso2 .com/index.htm Same schemes - relative treated as absolute: http://www.contoso2/index.htm

public System.Uri(System.String uriString)

Constructs and initializes a new instance of the System.Uri class by parsing the specified URI.

Parameter uriString: A System.String containing a URI.

Throws: : uriString is null .

Throws: : uriString is a zero length string or contains only spaces. uriString is in an invalid form and cannot be parsed.

This constructor is equivalent to calling the System.Uri (System.String, System.Boolean) constructor, and specifying uriString and false as the arguments.

public System.Uri(System.String uriString, System.Boolean dontEscape)

Constructs and initializes a new instance of the System.Uri class by parsing the specified URI.

Parameter uriString: A System.String containing a URI.

Parameter dontEscape: true if the URI in uriString is already escaped; otherwise, false.

Throws: : uriString is null .

Throws: : uriString is a zero length string or contains only spaces. The parsing routine detected a scheme in an invalid form. The parser detected more than two consecutive slashes in a URI that does not use the "file" scheme. uriString is in an invalid form and cannot be parsed.

This constructor parses the URI, places its components into the appropriate properties, and puts the URI in canonical form. If the specified URI does not contain a scheme component, the URI is parsed using "file" as the scheme.

Example:

The following example creates a System.Uri instance for the URI "http://www.contoso.com/Hello%20World.htm". Because the URI contains escaped characters, the third parameter, dontEscape , is set to true .

using System;

public class UriTest {
 public static void Main() {
 
 Uri myUri = new Uri("http://www.contoso.com/Hello%20World.htm", true);

 Console.WriteLine(myUri.ToString());
 }
}

The output is

http://www.contoso.com/Hello World.htm

public System.Uri(System.Uri baseUri, System.String relativeUri)

Constructs and initializes a new instance of the System.Uri class by combining the specified base and relative URIs.

Parameter baseUri: A System.Uri containing a base URI.

Parameter relativeUri: A System.String containing a relative URI.

Throws: : relativeUri is in an invalid form.

Throws: : baseUri is null.

This constructor is equivalent to calling the System.Uri (System.Uri, System.String, System.Boolean) constructor, and specifying baseUri, relativeUri, and false as the arguments.

public System.Uri(System.Uri baseUri, System.String relativeUri, System.Boolean dontEscape)

Constructs and initializes a new instance of the System.Uri class by combining the specified base and relative URIs.

Parameter baseUri: A System.Uri containing the base URI. This parameter can, but is not required to contain a terminating slash ("/") character.

Parameter relativeUri: A System.String containing the relative URI to add to the base URI. This parameter can, but is not required to contain a leading slash ("/") character.

Parameter dontEscape: true if baseUri and relativeUri are already escaped; otherwise, false.

Throws: : relativeUri is in an invalid form.

Throws: : baseUri is null.

This constructor compensates for the presence or absence of a terminating slash in baseUri and/or a leading slash in relativeUri to produce a well-formed URI. If the relative URI contains a System.Uri.Scheme that is the same as the scheme of the base URI and the System.Uri.SchemeDelimiter is not present, or the relative URI does not contain a scheme, the new instance is composed of the relative URI (without its scheme component, if any) qualified by the scheme and authority information from the base URI. If the relative URI contains a System.Uri.Scheme followed by the System.Uri.SchemeDelimiter, it is treated as an absolute URI and the base URI is ignored. If the relative URI contains a scheme that differs from the scheme of the base URI, the base URI is ignored. If the System.Uri.SchemeDelimiter is not present in the relative URI, it is assumed, and the new instance is constructed as though the relative URI were an absolute URI. When the base URI is ignored, only the components of the relative URI are used to construct the new instance.

Example:

The following example creates new instances of the System.Uri class by combining a System.Uri instance representing the base URI and a string containing a relative URI.

using System;

public class UriTest {
 public static void Main() {

 // Typical base and relative URI constructor usage.

 Uri baseUri = new Uri("http://www.contoso.com", true);
 Uri myUri = new Uri(baseUri, "index.htm",true);
 Console.WriteLine("Typical usage: {0}",myUri.ToString());

 // Base and relative URI contain slashes.
 Uri baseUri2 = new Uri("http://www.contoso.com/", true);
 Uri myUri2 = new Uri(baseUri2, "/index.htm",true);
 Console.WriteLine("Slash example: {0}",myUri2.ToString());

 // Relative URI contains a different scheme than the base URI.
 Uri baseUri3 = new Uri("http://www.contoso.com/", true);
 Uri myUri3 = new Uri(baseUri3, "ftp://www.contoso2.com/index.htm",true);
 Console.WriteLine("Different schemes: {0}", myUri3.ToString());


 // Relative URI contains the same scheme as the base URI.
 // The scheme delimiter is not present in the relative URI.
 Uri baseUri4 = new Uri("http://www.contoso.com/", true);
 Uri myUri4 = new Uri(baseUri4, "http:www.contoso2.com/index.htm",true);
 Console.WriteLine("Same schemes - relative treated as relative: {0}",myUri4.ToString());

 // Relative URI contains the same scheme as the base URI.
 // The scheme delimiter is present in the relative URI.
 Uri baseUri5 = new Uri("http://www.contoso.com/", true);
 Uri myUri5 = new Uri(baseUri5, "http://www.contoso2/index.htm",true);
 Console.WriteLine("Same schemes - relative treated as absolute: {0}",myUri5.ToString());

 }
}

The output is

Typical usage: http://www.contoso.com/index.htm

Slash example: http://www.contoso.com/index.htm

Different schemes: ftp://www.contoso2.com/index.htm

Same schemes - relative treated as relative: http://www.contoso.com/www.contoso2 .com/index.htm

Same schemes - relative treated as absolute: http://www.contoso2/index.htm

Functions:

Functions:
protected virtual System.Void Canonicalize() Converts the components of the URI represented by the current instance to canonical form. This method converts the URI to a format suitable for machine interpretation according to the scheme of the current instance. The conversions are required to preserve all information that could, if removed or altered, change the URI represented by the current instance. This method performs the following conversions: Override this method to canonicalize the type derived from `System.Uri` . Applications do not call this method; it is called by constructors after parsing the URI and escaping the components.
public static System.UriHostNameType CheckHostName(System.String name) Returns a value that describes the format of a host name string. Parameter `name`: A `System.String` containing the host name to validate. Returns: A `System.UriHostNameType` that indicates the type of the host name. If the type of the host name cannot be determined, or the host name is `null` or a zero-length string, returns System.UriHostNameType.Unknown . Example: The following example demonstrates using the System.Uri.CheckHostName(System.String) method. using System; public class UriTest { public static void Main() { Console.WriteLine(Uri.CheckHostName("www.contoso.com")); } } The output is Dns
public static System.Boolean CheckSchemeName(System.String schemeName) Returns a `System.Boolean` value indicating whether the specified scheme name is valid. Parameter `schemeName`: A `System.String` containing the scheme name to validate. Returns: `true` if the scheme name is valid; otherwise, `false`. If `schemeName` is `null` or is a zero-length string, returns `false`. The scheme name is required to begin with a letter, and contain only letters, digits, and the characters '.', '+' or '-'.
protected virtual System.Void CheckSecurity() Checks the current instance for character sequences that can result in unauthorized access to resources, and removes them. This method checks for invalid or dangerous character sequences in the components of the current instance, and removes them. The semantics that determine whether a character sequence presents a security risk are determined by the scheme of the current instance. The default implementation does nothing. Override this method to provide security checks for types derived from `System.Uri`. Invoke this method on instances of types derived from `System.Uri` to remove any URI content that allows unauthorized access to resources.
public System.Boolean Equals(System.Object comparand) Compares the current instance and the specified object for equality. Parameter `comparand`: The `System.Uri` instance to compare with the current instance. This argument can be a `System.String` or a `System.Uri` . Returns: `true` if `comparand` represents the same URI (ignoring any fragment or query information) as the current instance; otherwise, `false` . If `comparand` is `null`, a zero-length string, or is not an instance of `System.String` or `System.Uri` , returns false. If `comparand` is a `System.String`, it is converted to a `System.Uri` by calling `System.Uri`(`comparand`). The System.Uri.Scheme, System.Uri.Host and unescaped version of the System.Uri.AbsolutePath of the current instance and `comparand` are compared for equality. If the scheme of the current instance is the System.Uri.UriSchemeFile scheme, the absolute paths are compared in accordance with the case sensitivity of the current platform. This method overrides System.Object.Equals(System.Object).
protected virtual System.Void Escape() Converts any unsafe or reserved characters in the System.Uri.AbsolutePath component to equivalent escaped hexadecimal sequences. Converts any unsafe or reserved characters in the System.Uri.AbsolutePath component to a character sequence consisting of a "%" followed by the hexadecimal value of the character as described by IETF 2396. If the path component of the current instance is `null`, the escaped path is System.String.Empty. As described above. Override this method to customize the escaping behavior provided by the `System.Uri` type. Applications typically do not call this method; it is intended for use by the constructors. For additional information on escaping URI, see section 2 of RFC 2396.
protected static System.String EscapeString(System.String str) Converts a string to its escaped representation. Parameter `str`: A `System.String` to convert to its escaped representation. Returns: A `System.String` containing the escaped representation of `str` . The string is escaped in accordance with RFC 2396.
public static System.Int32 FromHex(System.Char digit) Returns the decimal value of a hexadecimal digit. Parameter `digit`: The hexadecimal digit (0-9, a-f, A-F) to convert. Returns: A `System.Int32` containing an integer from 0 - 15 that corresponds to the specified hexadecimal digit. Throws: : `digit` is not a valid hexadecimal digit (0-9, a-f, A-F).
public System.Int32 GetHashCode() Generates a hash code for the current instance. Returns: A `System.Int32` containing the hash code for this instance. The hash code is generated without the fragment component. For example, the URIs "http://www.contoso.com/index.htm#search" and "http://www.contoso.com/index.htm" produce the same hash code. The algorithm used to generate the hash code is unspecified. This method overrides System.Object.GetHashCode.
public System.String GetLeftPart(System.UriPartial part) Returns the specified portion of the URI represented by the current instance. Parameter `part`: A `System.UriPartial` value that specifies the component to return. Returns: A `System.String` containing all components up to the specified portion of the URI, or System.String.Empty if the current instance does not contain the component identified by `part` . Throws: : The `part` parameter is not a valid `System.UriPartial` value. The System.Uri.GetLeftPart(System.UriPartial) method returns a string containing the URI components starting with the left-most component of the URI and ending with the component specified by `part` . The returned string does not include fragment or query information. System.Uri.GetLeftPart(System.UriPartial) includes delimiters as follows: Example: The following example demonstrates the System.Uri.GetLeftPart(System.UriPartial) method. using System; public class UriTest { public static void Main() { string[] myUri = { "http://www.contoso.com/index.htm", "http:www.contoso.com/index.htm#mark", "mailto:user@contoso.com?subject=uri", "nntp://news.contoso.com/123456@contoso.com" }; foreach (string s in myUri) { Uri aUri = new Uri(s); Console.WriteLine("URI: {0}", aUri.ToString()); Console.WriteLine("Scheme: {0}",aUri.GetLeftPart(UriPartial.Scheme)); Console.WriteLine("Authority: {0}",aUri.GetLeftPart(UriPartial.Authority)); Console.WriteLine("Path: {0}",aUri.GetLeftPart(UriPartial.Path)); } } } The output is URI: http://www.contoso.com/index.htm Scheme: http:// Authority: http://www.contoso.com Path: http://www.contoso.com/index.htm URI: http://www.contoso.com/index.htm#mark Scheme: http:// Authority: http://www.contoso.com Path: http://www.contoso.com/index.htm URI: mailto:user@contoso.com?subject=uri Scheme: mailto: Authority: Path: mailto:user@contoso.com URI: nntp://news.contoso.com/123456@contoso.com Scheme: nntp:// Authority: nntp://news.contoso.com Path: nntp://news.contoso.com/123456@contoso.com
public static System.String HexEscape(System.Char character) Converts a specified ASCII character into its escaped hexadecimal equivalent. Parameter `character`: A `System.Char` containing the character to convert to escaped hexadecimal representation. Returns: A `System.String` containing the escaped hexadecimal representation of the specified character. Throws: : The numerical value of `character` is greater than 255. The returned string is in the form "%XX", where X represents a hexadecimal digit (0-9, A-F).
public static System.Char HexUnescape(System.String pattern, System.Int32& index) Converts a specified escaped hexadecimal representation of a character to the character. Parameter `pattern`: A `System.String` containing the hexadecimal representation of a character. Parameter `index`: A `System.Int32` containing the location in `pattern` where the hexadecimal representation of a character begins. Returns: A `System.Char` containing a character. If the character pointed to by `index` is a "%" and there are at least two characters following the "%", and the two characters are valid hexadecimal digits, the hexadecimal digits are converted to `System.Char`. Otherwise, the character at `index` is returned. Valid hexadecimal digits are: 0-9, a-f, A-F. On return, the value of `index` contains the index of the character following the one returned. Throws: : `index <` 0 or `index` >= the number of characters in pattern.
protected virtual System.Boolean IsBadFileSystemCharacter(System.Char character) Returns a `System.Boolean` value that indicates whether the specified character would be an invalid character if used in a file system name. Parameter `character`: A `System.Char` containing the character to check. Returns: `true` if the specified character is not acceptable for use in a file system name; otherwise, `false`. The value returned by this method is implementation-defined. This method returns `false` if the specified character cannot be used in a URI that identifies a file, as defined by the current file system on the current platform. As described above. Override this method to provide a check for invalid characters as defined by the current file system on the current platform. Use this method to determine if a character can be used in a file name.
protected static System.Boolean IsExcludedCharacter(System.Char character) Returns a `System.Boolean` value that indicates whether the specified character is excluded from use or is unwise in URIs, as defined by IETF RFC 2396. Parameter `character`: A `System.Char` containing the character to check. Returns: `true` if the specified character is required to be escaped; otherwise, `false` . This method returns `true` for the following characters:
public static System.Boolean IsHexDigit(System.Char character) Returns a `System.Boolean` value that indicates whether the specified character is a valid hexadecimal digit. Parameter `character`: A `System.Char` containing the character to validate. Returns: `true` if the character is a valid hexadecimal digit (0-9, A-F, a-f); otherwise `false`.
public static System.Boolean IsHexEncoding(System.String pattern, System.Int32 index) Returns a `System.Boolean` value that indicates whether a substring of the specified string is in escaped hexadecimal encoding format ("%" followed by two hexadecimal characters). Parameter `pattern`: The `System.String` to check. Parameter `index`: A `System.Int32` containing the location in `pattern` to check for hex encoding. Returns: `true` if the specified location in `pattern` contains a substring in escaped hexadecimal encoding format; otherwise, `false`. The System.Uri.IsHexEncoding(System.String,System.Int32) method checks for hexadecimal digits case-insensitively.
protected virtual System.Boolean IsReservedCharacter(System.Char character) Returns a `System.Boolean` value that indicates whether a character is part of the URI reserved set. Returns: `true` if `character` is a URI reserved character as defined by IETF RFC 2396; otherwise, `false`. The following characters are reserved for the use in URI: As described above. Override this method to customize the escaping behavior provided by the `System.Uri` type. Use this method to determine if a character is reserved.
public System.String MakeRelative(System.Uri toUri) Returns the specified `System.Uri` as a relative URI. Parameter `toUri`: The URI to compare to the current URI. Returns: A `System.String` with the difference between the current instance and `toUri` if the two URIs are the same except for the path information. If the two URIs differ in more than the System.Uri.AbsolutePath, this method returns a `System.String` with the absolute URI of `toUri`. Example: The following example demonstrates the System.Uri.MakeRelative(System.Uri) method. using System; public class UriTest { public static void Main() { Uri myUri = new Uri("http://www.contoso.com/Hello%20World.htm", true); Console.WriteLine(myUri.ToString()); Console.WriteLine(myUri.MakeRelative(new Uri ("http://www.contoso.com/index.htm"))); } } The output is http://www.contoso.com/Hello World.htm index.htm
protected virtual System.Void Parse() Parses the URI into its constituent components. Throws: : The scheme of the URI is in an invalid format. The URI is in an invalid form and cannot be parsed. This method parses the System.Uri.AbsolutePath property, separates it into various URI components, and stores the components in the appropriate `System.Uri` properties. This method parses path components as defined in IETF RFC 2396. Override this method to provide parsing for URIs in formats that are not defined in IETF RFC 2396. Applications typically do not call this method; it is intended for use by the constructors.
public System.String ToString() Returns the unescaped, canonical form of the URI information used to construct the current instance. Returns: A `System.String` containing the unescaped, canonical form of the URI represented by the current instance. The string returned by this method includes the System.Uri.Query and System.Uri.Fragment components. This method overrides System.Object.ToString.
protected virtual System.String Unescape(System.String path) Converts escape sequences in the specified `System.String` into their unescaped equivalents. Parameter `path`: The `System.String` to unescape. Returns: A `System.String` containing `path` with its escaped characters converted to their unescaped equivalents. If path is `null` or a zero-length string, returns System.String.Empty. Escape sequences can be hex-encoded reserved characters (for example "%40") or hex-encoded UTF-8 sequences (for example "%C4%D2").

protected virtual System.Void Canonicalize()

Converts the components of the URI represented by the current instance to canonical form.

This method converts the URI to a format suitable for machine interpretation according to the scheme of the current instance. The conversions are required to preserve all information that could, if removed or altered, change the URI represented by the current instance. This method performs the following conversions: Override this method to canonicalize the type derived from System.Uri . Applications do not call this method; it is called by constructors after parsing the URI and escaping the components.

public static System.UriHostNameType CheckHostName(System.String name)

Returns a value that describes the format of a host name string.

Parameter name: A System.String containing the host name to validate.

Returns: A System.UriHostNameType that indicates the type of the host name. If the type of the host name cannot be determined, or the host name is null or a zero-length string, returns System.UriHostNameType.Unknown .

Example:

The following example demonstrates using the System.Uri.CheckHostName(System.String) method.

using System;

public class UriTest {
 public static void Main() {
 
 Console.WriteLine(Uri.CheckHostName("www.contoso.com"));
 }
}

The output is

Dns

public static System.Boolean CheckSchemeName(System.String schemeName)

Returns a System.Boolean value indicating whether the specified scheme name is valid.

Parameter schemeName: A System.String containing the scheme name to validate.

Returns: true if the scheme name is valid; otherwise, false. If schemeName is null or is a zero-length string, returns false.

The scheme name is required to begin with a letter, and contain only letters, digits, and the characters '.', '+' or '-'.

protected virtual System.Void CheckSecurity()

Checks the current instance for character sequences that can result in unauthorized access to resources, and removes them.

This method checks for invalid or dangerous character sequences in the components of the current instance, and removes them. The semantics that determine whether a character sequence presents a security risk are determined by the scheme of the current instance. The default implementation does nothing. Override this method to provide security checks for types derived from System.Uri. Invoke this method on instances of types derived from System.Uri to remove any URI content that allows unauthorized access to resources.

public System.Boolean Equals(System.Object comparand)

Compares the current instance and the specified object for equality.

Parameter comparand: The System.Uri instance to compare with the current instance. This argument can be a System.String or a System.Uri .

Returns: true if comparand represents the same URI (ignoring any fragment or query information) as the current instance; otherwise, false . If comparand is null, a zero-length string, or is not an instance of System.String or System.Uri , returns false.

If comparand is a System.String, it is converted to a System.Uri by calling System.Uri(comparand). The System.Uri.Scheme, System.Uri.Host and unescaped version of the System.Uri.AbsolutePath of the current instance and comparand are compared for equality. If the scheme of the current instance is the System.Uri.UriSchemeFile scheme, the absolute paths are compared in accordance with the case sensitivity of the current platform. This method overrides System.Object.Equals(System.Object).

protected virtual System.Void Escape()

Converts any unsafe or reserved characters in the System.Uri.AbsolutePath component to equivalent escaped hexadecimal sequences.

Converts any unsafe or reserved characters in the System.Uri.AbsolutePath component to a character sequence consisting of a "%" followed by the hexadecimal value of the character as described by IETF 2396. If the path component of the current instance is null, the escaped path is System.String.Empty. As described above. Override this method to customize the escaping behavior provided by the System.Uri type. Applications typically do not call this method; it is intended for use by the constructors. For additional information on escaping URI, see section 2 of RFC 2396.

protected static System.String EscapeString(System.String str)

Converts a string to its escaped representation.

Parameter str: A System.String to convert to its escaped representation.

Returns: A System.String containing the escaped representation of str .

The string is escaped in accordance with RFC 2396.

public static System.Int32 FromHex(System.Char digit)

Returns the decimal value of a hexadecimal digit.

Parameter digit: The hexadecimal digit (0-9, a-f, A-F) to convert.

Returns: A System.Int32 containing an integer from 0 - 15 that corresponds to the specified hexadecimal digit.

Throws: : digit is not a valid hexadecimal digit (0-9, a-f, A-F).

public System.Int32 GetHashCode()

Generates a hash code for the current instance.

Returns: A System.Int32 containing the hash code for this instance.

The hash code is generated without the fragment component. For example, the URIs "http://www.contoso.com/index.htm#search" and "http://www.contoso.com/index.htm" produce the same hash code. The algorithm used to generate the hash code is unspecified. This method overrides System.Object.GetHashCode.

public System.String GetLeftPart(System.UriPartial part)

Returns the specified portion of the URI represented by the current instance.

Parameter part: A System.UriPartial value that specifies the component to return.

Returns: A System.String containing all components up to the specified portion of the URI, or System.String.Empty if the current instance does not contain the component identified by part .

Throws: : The part parameter is not a valid System.UriPartial value.

The System.Uri.GetLeftPart(System.UriPartial) method returns a string containing the URI components starting with the left-most component of the URI and ending with the component specified by part . The returned string does not include fragment or query information. System.Uri.GetLeftPart(System.UriPartial) includes delimiters as follows:

Example:

The following example demonstrates the System.Uri.GetLeftPart(System.UriPartial) method.

using System;

public class UriTest {
  public static void Main() {
    string[] myUri  = {
            "http://www.contoso.com/index.htm",
            "http:www.contoso.com/index.htm#mark",
                    "mailto:user@contoso.com?subject=uri",
                    "nntp://news.contoso.com/123456@contoso.com"
    };
    foreach (string s in myUri) {
      Uri aUri = new Uri(s);
      Console.WriteLine("URI: {0}", aUri.ToString());
      Console.WriteLine("Scheme: {0}",aUri.GetLeftPart(UriPartial.Scheme));
      Console.WriteLine("Authority: {0}",aUri.GetLeftPart(UriPartial.Authority));
      Console.WriteLine("Path: {0}",aUri.GetLeftPart(UriPartial.Path));
    }  
  }
}

The output is

URI: http://www.contoso.com/index.htm

Scheme: http://

Authority: http://www.contoso.com

Path: http://www.contoso.com/index.htm

URI: http://www.contoso.com/index.htm#mark

Scheme: http://

Authority: http://www.contoso.com

Path: http://www.contoso.com/index.htm

URI: mailto:user@contoso.com?subject=uri

Scheme: mailto:

Authority:

Path: mailto:user@contoso.com

URI: nntp://news.contoso.com/123456@contoso.com

Scheme: nntp://

Authority: nntp://news.contoso.com

Path: nntp://news.contoso.com/123456@contoso.com

public static System.String HexEscape(System.Char character)

Converts a specified ASCII character into its escaped hexadecimal equivalent.

Parameter character: A System.Char containing the character to convert to escaped hexadecimal representation.

Returns: A System.String containing the escaped hexadecimal representation of the specified character.

Throws: : The numerical value of character is greater than 255.

The returned string is in the form "%XX", where X represents a hexadecimal digit (0-9, A-F).

public static System.Char HexUnescape(System.String pattern, System.Int32& index)

Converts a specified escaped hexadecimal representation of a character to the character.

Parameter pattern: A System.String containing the hexadecimal representation of a character.

Parameter index: A System.Int32 containing the location in pattern where the hexadecimal representation of a character begins.

Returns: A System.Char containing a character. If the character pointed to by index is a "%" and there are at least two characters following the "%", and the two characters are valid hexadecimal digits, the hexadecimal digits are converted to System.Char. Otherwise, the character at index is returned. Valid hexadecimal digits are: 0-9, a-f, A-F. On return, the value of index contains the index of the character following the one returned.

Throws: : index < 0 or index >= the number of characters in pattern.

protected virtual System.Boolean IsBadFileSystemCharacter(System.Char character)

Returns a System.Boolean value that indicates whether the specified character would be an invalid character if used in a file system name.

Parameter character: A System.Char containing the character to check.

Returns: true if the specified character is not acceptable for use in a file system name; otherwise, false. The value returned by this method is implementation-defined.

This method returns false if the specified character cannot be used in a URI that identifies a file, as defined by the current file system on the current platform. As described above. Override this method to provide a check for invalid characters as defined by the current file system on the current platform. Use this method to determine if a character can be used in a file name.

protected static System.Boolean IsExcludedCharacter(System.Char character)

Returns a System.Boolean value that indicates whether the specified character is excluded from use or is unwise in URIs, as defined by IETF RFC 2396.

Parameter character: A System.Char containing the character to check.

Returns: true if the specified character is required to be escaped; otherwise, false .

This method returns true for the following characters:

public static System.Boolean IsHexDigit(System.Char character)

Returns a System.Boolean value that indicates whether the specified character is a valid hexadecimal digit.

Parameter character: A System.Char containing the character to validate.

Returns: true if the character is a valid hexadecimal digit (0-9, A-F, a-f); otherwise false.

public static System.Boolean IsHexEncoding(System.String pattern, System.Int32 index)

Returns a System.Boolean value that indicates whether a substring of the specified string is in escaped hexadecimal encoding format ("%" followed by two hexadecimal characters).

Parameter pattern: The System.String to check.

Parameter index: A System.Int32 containing the location in pattern to check for hex encoding.

Returns: true if the specified location in pattern contains a substring in escaped hexadecimal encoding format; otherwise, false.

The System.Uri.IsHexEncoding(System.String,System.Int32) method checks for hexadecimal digits case-insensitively.

protected virtual System.Boolean IsReservedCharacter(System.Char character)

Returns a System.Boolean value that indicates whether a character is part of the URI reserved set.

Returns: true if character is a URI reserved character as defined by IETF RFC 2396; otherwise, false.

The following characters are reserved for the use in URI: As described above. Override this method to customize the escaping behavior provided by the System.Uri type. Use this method to determine if a character is reserved.

public System.String MakeRelative(System.Uri toUri)

Returns the specified System.Uri as a relative URI.

Parameter toUri: The URI to compare to the current URI.

Returns: A System.String with the difference between the current instance and toUri if the two URIs are the same except for the path information. If the two URIs differ in more than the System.Uri.AbsolutePath, this method returns a System.String with the absolute URI of toUri.

Example:

The following example demonstrates the System.Uri.MakeRelative(System.Uri) method.

using System;
public class UriTest {
  public static void Main() {
    Uri myUri = new Uri("http://www.contoso.com/Hello%20World.htm", true);
    Console.WriteLine(myUri.ToString());
    Console.WriteLine(myUri.MakeRelative(new Uri ("http://www.contoso.com/index.htm")));
  }
}

The output is

http://www.contoso.com/Hello World.htm

index.htm

protected virtual System.Void Parse()

Parses the URI into its constituent components.

Throws: : The scheme of the URI is in an invalid format. The URI is in an invalid form and cannot be parsed.

This method parses the System.Uri.AbsolutePath property, separates it into various URI components, and stores the components in the appropriate System.Uri properties. This method parses path components as defined in IETF RFC 2396. Override this method to provide parsing for URIs in formats that are not defined in IETF RFC 2396. Applications typically do not call this method; it is intended for use by the constructors.

public System.String ToString()

Returns the unescaped, canonical form of the URI information used to construct the current instance.

Returns: A System.String containing the unescaped, canonical form of the URI represented by the current instance.

The string returned by this method includes the System.Uri.Query and System.Uri.Fragment components. This method overrides System.Object.ToString.

protected virtual System.String Unescape(System.String path)

Converts escape sequences in the specified System.String into their unescaped equivalents.

Parameter path: The System.String to unescape.

Returns: A System.String containing path with its escaped characters converted to their unescaped equivalents. If path is null or a zero-length string, returns System.String.Empty.

Escape sequences can be hex-encoded reserved characters (for example "%40") or hex-encoded UTF-8 sequences (for example "%C4%D2").

Functions inherited from System.MarshalByRefObject:

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 `<doc:param name="obj"/>` `is Point` , the check would return true in cases where `obj` is an instance of a subclass of `Point` , even though `obj` and the current instance are not of the same runtime type. Having verified that both objects are of the same type, the method casts `obj` to type `Point` and returns the result of comparing the instance variables of the two objects. 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`

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

<doc:param name="obj"/>

is Point , the check would return true in cases where obj is an instance of a subclass of Point , even though obj and the current instance are not of the same runtime type. Having verified that both objects are of the same type, the method casts obj to type Point and returns the result of comparing the instance variables of the two objects.

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

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