Skip to content

Object.xml -- updating for Try .NET #3346

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Dec 20, 2019
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 23 additions & 9 deletions xml/System/Object.xml
Original file line number Diff line number Diff line change
Expand Up @@ -136,6 +136,15 @@
</AssemblyInfo>
<Docs>
<summary>Determines whether two object instances are equal.</summary>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

[!INCLUDE[interactive-note](~/includes/csharp-interactive-note-some.md)]

]]></format>
</remarks>
</Docs>
</MemberGroup>
<Member MemberName="Equals">
Expand Down Expand Up @@ -188,7 +197,7 @@

## Remarks
The type of comparison between the current instance and the `obj` parameter depends on whether the current instance is a reference type or a value type.

- If the current instance is a reference type, the <xref:System.Object.Equals%28System.Object%29> method tests for reference equality, and a call to the <xref:System.Object.Equals%28System.Object%29> method is equivalent to a call to the <xref:System.Object.ReferenceEquals%2A> method. Reference equality means that the object variables that are compared refer to the same object. The following example illustrates the result of such a comparison. It defines a `Person` class, which is a reference type, and calls the `Person` class constructor to instantiate two new `Person` objects, `person1a` and `person2`, which have the same value. It also assigns `person1a` to another object variable, `person1b`. As the output from the example shows, `person1a` and `person1b` are equal because they reference the same object. However, `person1a` and `person2` are not equal, although they have the same value.

[!code-csharp[System.Object.Equals#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.object.equals/cs/equals_ref.cs#2)]
Expand All @@ -198,7 +207,7 @@

- The two objects are of the same type. As the following example shows, a <xref:System.Byte> object that has a value of 12 does not equal an <xref:System.Int32> object that has a value of 12, because the two objects have different run-time types.

[!code-csharp[System.Object.Equals#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.object.equals/cs/equals_val1.cs#3)]
[!code-csharp-interactive[System.Object.Equals#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.object.equals/cs/equals_val1.cs#3)]
[!code-vb[System.Object.Equals#3](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.object.equals/vb/equals_val1.vb#3)]

- The values of the public and private fields of the two objects are equal. The following example tests for value equality. It defines a `Person` structure, which is a value type, and calls the `Person` class constructor to instantiate two new `Person` objects, `person1` and `person2`, which have the same value. As the output from the example shows, although the two object variables refer to different objects, `person1` and `person2` are equal because they have the same value for the private `personName` field.
Expand Down Expand Up @@ -762,6 +771,8 @@ and the <xref:System.IDisposable> interface. The <xref:System.IDisposable.Dispos

For two objects `x` and `y` that have identical runtime types, `Object.ReferenceEquals(x.GetType(),y.GetType())` returns `true`. The following example uses the <xref:System.Object.GetType%2A> method with the <xref:System.Object.ReferenceEquals%2A> method to determine whether one numeric value is the same type as two other numeric values.

[!INCLUDE[interactive-note](~/includes/csharp-interactive-note-some.md)]

[!code-csharp-interactive[System.Object.GetType#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.object.gettype/cs/gettype1.cs#1)]
[!code-vb[System.Object.GetType#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.object.gettype/vb/gettype1.vb#1)]

Expand All @@ -779,8 +790,6 @@ and the <xref:System.IDisposable> interface. The <xref:System.IDisposable.Dispos

## Examples

[!INCLUDE[interactive-note](~/includes/csharp-interactive-note-some.md)]

The following code example demonstrates that <xref:System.Object.GetType%2A> returns the runtime type of the current instance.

[!code-cpp[ECMA-System.Object.GetType#1](~/samples/snippets/cpp/VS_Snippets_CLR/ECMA-System.Object.GetType/CPP/gettype.cpp#1)]
Expand Down Expand Up @@ -925,25 +934,28 @@ and the <xref:System.IDisposable> interface. The <xref:System.IDisposable.Dispos

- When comparing value types. If `objA` and `objB` are value types, they are boxed before they are passed to the <xref:System.Object.ReferenceEquals%2A> method. This means that if both `objA` and `objB` represent the same instance of a value type, the <xref:System.Object.ReferenceEquals%2A> method nevertheless returns `false`, as the following example shows.

[!code-csharp[System.Object.ReferenceEquals#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.object.referenceequals/cs/referenceequals4.cs#1)]
[!code-csharp-interactive[System.Object.ReferenceEquals#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.object.referenceequals/cs/referenceequals4.cs#1)]
[!code-vb[System.Object.ReferenceEquals#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.object.referenceequals/vb/referenceequals4.vb#1)]

For information on boxing value types, see [Boxing and Unboxing](~/docs/csharp/programming-guide/types/boxing-and-unboxing.md).

- When comparing strings. If `objA` and `objB` are strings, the <xref:System.Object.ReferenceEquals%2A> method returns `true` if the string is interned. It does not perform a test for value equality. In the following example, `s1` and `s2` are equal because they are two instances of a single interned string. However, `s3` and `s4` are not equal, because although they are have identical string values, that string is not interned.

[!code-csharp[System.Object.ReferenceEquals#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.object.referenceequals/cs/referenceequalsa.cs#2)]
[!code-csharp-interactive[System.Object.ReferenceEquals#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.object.referenceequals/cs/referenceequalsa.cs#2)]
[!code-vb[System.Object.ReferenceEquals#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.object.referenceequals/vb/referenceequalsa.vb#2)]

For more information about string interning, see <xref:System.String.IsInterned%2A?displayProperty=nameWithType>.



## Examples

[!INCLUDE[interactive-note](~/includes/csharp-interactive-note.md)]

The following example uses <xref:System.Object.ReferenceEquals%2A> to determine if two objects are the same instance.

[!code-cpp[ECMA-System.Object.ReferenceEquals#1](~/samples/snippets/cpp/VS_Snippets_CLR/ECMA-System.Object.ReferenceEquals/CPP/referenceequals.cpp#1)]
[!code-csharp[ECMA-System.Object.ReferenceEquals#1](~/samples/snippets/csharp/VS_Snippets_CLR/ECMA-System.Object.ReferenceEquals/CS/referenceequals.cs#1)]
[!code-csharp-interactive[ECMA-System.Object.ReferenceEquals#1](~/samples/snippets/csharp/VS_Snippets_CLR/ECMA-System.Object.ReferenceEquals/CS/referenceequals.cs#1)]
[!code-vb[ECMA-System.Object.ReferenceEquals#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/ECMA-System.Object.ReferenceEquals/vb/referenceequals.vb#1)]

]]></format>
Expand Down Expand Up @@ -998,8 +1010,6 @@ and the <xref:System.IDisposable> interface. The <xref:System.IDisposable.Dispos

Types frequently override the <xref:System.Object.ToString%2A?displayProperty=nameWithType> method to provide a more suitable string representation of a particular type. Types also frequently overload the <xref:System.Object.ToString%2A?displayProperty=nameWithType> method to provide support for format strings or culture-sensitive formatting.

[!INCLUDE[interactive-note](~/includes/csharp-interactive-note-some.md)]

In this section:

[The default Object.ToString() method](#Default)
Expand All @@ -1012,6 +1022,8 @@ and the <xref:System.IDisposable> interface. The <xref:System.IDisposable.Dispos
## The default Object.ToString() method
The default implementation of the <xref:System.Object.ToString%2A> method returns the fully qualified name of the type of the <xref:System.Object>, as the following example shows.

[!INCLUDE[interactive-note](~/includes/csharp-interactive-note-some.md)]

[!code-cpp[System.Object.ToString#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.object.tostring/cpp/tostring1.cpp#1)]
[!code-csharp-interactive[System.Object.ToString#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.object.tostring/cs/tostring1.cs#1)]
[!code-vb[System.Object.ToString#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.object.tostring/vb/tostring1.vb#1)]
Expand Down Expand Up @@ -1062,6 +1074,8 @@ and the <xref:System.IDisposable> interface. The <xref:System.IDisposable.Dispos
## Extending the Object.ToString method
Because a type inherits the default <xref:System.Object.ToString%2A?displayProperty=nameWithType> method, you may find its behavior undesirable and want to change it. This is particularly true of arrays and collection classes. While you may expect the `ToString` method of an array or collection class to display the values of its members, it instead displays the type fully qualified type name, as the following example shows.

[!INCLUDE[interactive-note](~/includes/csharp-interactive-note-some.md)]

[!code-csharp-interactive[System.Object.ToString#6](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.object.tostring/cs/array1.cs#6)]
[!code-vb[System.Object.ToString#6](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.object.tostring/vb/array1.vb#6)]

Expand Down