Permalink
Fetching contributors…
Cannot retrieve contributors at this time
373 lines (347 sloc) 22.8 KB
<Type Name="EqualityComparer&lt;T&gt;" FullName="System.Collections.Generic.EqualityComparer&lt;T&gt;">
<TypeSignature Language="C#" Value="public abstract class EqualityComparer&lt;T&gt; : System.Collections.Generic.IEqualityComparer&lt;T&gt;, System.Collections.IEqualityComparer" />
<TypeSignature Language="ILAsm" Value=".class public auto ansi abstract serializable beforefieldinit EqualityComparer`1&lt;T&gt; extends System.Object implements class System.Collections.Generic.IEqualityComparer`1&lt;!T&gt;, class System.Collections.IEqualityComparer" />
<TypeSignature Language="DocId" Value="T:System.Collections.Generic.EqualityComparer`1" />
<TypeSignature Language="VB.NET" Value="Public MustInherit Class EqualityComparer(Of T)&#xA;Implements IEqualityComparer, IEqualityComparer(Of T)" />
<TypeSignature Language="C++ CLI" Value="generic &lt;typename T&gt;&#xA;public ref class EqualityComparer abstract : System::Collections::Generic::IEqualityComparer&lt;T&gt;, System::Collections::IEqualityComparer" />
<TypeSignature Language="F#" Value="type EqualityComparer&lt;'T&gt; = class&#xA; interface IEqualityComparer&#xA; interface IEqualityComparer&lt;'T&gt;" />
<AssemblyInfo>
<AssemblyName>System.Collections</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.10.0</AssemblyVersion>
<AssemblyVersion>4.1.0.0</AssemblyVersion>
<AssemblyVersion>4.1.1.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>mscorlib</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.0.5.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>netstandard</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
</AssemblyInfo>
<TypeParameters>
<TypeParameter Name="T" />
</TypeParameters>
<Base>
<BaseTypeName>System.Object</BaseTypeName>
</Base>
<Interfaces>
<Interface>
<InterfaceName>System.Collections.Generic.IEqualityComparer&lt;T&gt;</InterfaceName>
</Interface>
<Interface>
<InterfaceName>System.Collections.IEqualityComparer</InterfaceName>
</Interface>
</Interfaces>
<Attributes>
<Attribute FrameworkAlternate="netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;xamarinandroid-7.1;xamarinios-10.8;xamarinmac-3.0">
<AttributeName>Serializable</AttributeName>
</Attribute>
</Attributes>
<Docs>
<typeparam name="T">The type of objects to compare.</typeparam>
<summary>Provides a base class for implementations of the <see cref="T:System.Collections.Generic.IEqualityComparer`1" /> generic interface.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
Derive from this class to provide a custom implementation of the <xref:System.Collections.Generic.IEqualityComparer%601> generic interface for use with collection classes such as the <xref:System.Collections.Generic.Dictionary%602> generic class, or with methods such as <xref:System.Collections.Generic.List%601.Sort%2A?displayProperty=nameWithType>.
The <xref:System.Collections.Generic.EqualityComparer%601.Default%2A> property checks whether type `T` implements the <xref:System.IEquatable%601?displayProperty=nameWithType> generic interface and, if so, returns an <xref:System.Collections.Generic.EqualityComparer%601> that invokes the implementation of the <xref:System.IEquatable%601.Equals%2A?displayProperty=nameWithType> method. Otherwise, it returns an <xref:System.Collections.Generic.EqualityComparer%601>, as provided by `T`.
We recommend that you derive from the <xref:System.Collections.Generic.EqualityComparer%601> class instead of implementing the <xref:System.Collections.Generic.IEqualityComparer%601> interface, because the <xref:System.Collections.Generic.EqualityComparer%601> class tests for equality using the <xref:System.IEquatable%601.Equals%2A?displayProperty=nameWithType> method instead of the <xref:System.Object.Equals%2A?displayProperty=nameWithType> method. This is consistent with the `Contains`, `IndexOf`, `LastIndexOf`, and `Remove` methods of the <xref:System.Collections.Generic.Dictionary%602> class and other generic collections.
## Examples
The following example creates a dictionary collection of objects of type `Box` with an equality comparer. Two boxes are considered equal if their dimensions are the same. It then adds the boxes to the collection.
The dictionary is recreated with an equality comparer that defines equality in a different way: Two boxes are considered equal if their volumes are the same.
[!code-csharp[System.Collections.Generic.EqualityComparer#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.generic.equalitycomparer/cs/program.cs#1)]
[!code-vb[System.Collections.Generic.EqualityComparer#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.equalitycomparer/vb/program.vb#1)]
]]></format>
</remarks>
<altmember cref="T:System.Collections.Generic.IEqualityComparer`1" />
<altmember cref="T:System.IEquatable`1" />
</Docs>
<Members>
<Member MemberName=".ctor">
<MemberSignature Language="C#" Value="protected EqualityComparer ();" />
<MemberSignature Language="ILAsm" Value=".method familyhidebysig specialname rtspecialname instance void .ctor() cil managed" />
<MemberSignature Language="DocId" Value="M:System.Collections.Generic.EqualityComparer`1.#ctor" />
<MemberSignature Language="VB.NET" Value="Protected Sub New ()" />
<MemberSignature Language="C++ CLI" Value="protected:&#xA; EqualityComparer();" />
<MemberType>Constructor</MemberType>
<AssemblyInfo>
<AssemblyName>System.Collections</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.10.0</AssemblyVersion>
<AssemblyVersion>4.1.0.0</AssemblyVersion>
<AssemblyVersion>4.1.1.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>mscorlib</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.0.5.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>netstandard</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Parameters />
<Docs>
<summary>Initializes a new instance of the <see cref="T:System.Collections.Generic.EqualityComparer`1" /> class.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
<Member MemberName="Default">
<MemberSignature Language="C#" Value="public static System.Collections.Generic.EqualityComparer&lt;T&gt; Default { get; }" />
<MemberSignature Language="ILAsm" Value=".property class System.Collections.Generic.EqualityComparer`1&lt;!T&gt; Default" />
<MemberSignature Language="DocId" Value="P:System.Collections.Generic.EqualityComparer`1.Default" />
<MemberSignature Language="VB.NET" Value="Public Shared ReadOnly Property Default As EqualityComparer(Of T)" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; static property System::Collections::Generic::EqualityComparer&lt;T&gt; ^ Default { System::Collections::Generic::EqualityComparer&lt;T&gt; ^ get(); };" />
<MemberSignature Language="F#" Value="member this.Default : System.Collections.Generic.EqualityComparer&lt;'T&gt;" Usage="System.Collections.Generic.EqualityComparer&lt;'T&gt;.Default" />
<MemberType>Property</MemberType>
<AssemblyInfo>
<AssemblyName>System.Collections</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.10.0</AssemblyVersion>
<AssemblyVersion>4.1.0.0</AssemblyVersion>
<AssemblyVersion>4.1.1.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>mscorlib</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.0.5.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>netstandard</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
</AssemblyInfo>
<Attributes>
<Attribute FrameworkAlternate="netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2">
<AttributeName>get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")</AttributeName>
</Attribute>
<Attribute FrameworkAlternate="netframework-4.0">
<AttributeName>get: System.Security.SecuritySafeCritical</AttributeName>
</Attribute>
</Attributes>
<ReturnValue>
<ReturnType>System.Collections.Generic.EqualityComparer&lt;T&gt;</ReturnType>
</ReturnValue>
<Docs>
<summary>Returns a default equality comparer for the type specified by the generic argument.</summary>
<value>The default instance of the <see cref="T:System.Collections.Generic.EqualityComparer`1" /> class for type <typeparamref name="T" />.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The <xref:System.Collections.Generic.EqualityComparer%601.Default%2A> property checks whether type `T` implements the <xref:System.IEquatable%601?displayProperty=nameWithType> interface and, if so, returns an <xref:System.Collections.Generic.EqualityComparer%601> that uses that implementation. Otherwise, it returns an <xref:System.Collections.Generic.EqualityComparer%601> that uses the overrides of <xref:System.Object.Equals%2A?displayProperty=nameWithType> and <xref:System.Object.GetHashCode%2A?displayProperty=nameWithType> provided by `T`.
## Examples
The following example creates a collection that contains elements of the `Box` type and then searches it for a box matching another box by calling the `FindFirst` method, twice.
The first search does not specify any equality comparer, which means `FindFirst` uses <xref:System.Collections.Generic.EqualityComparer%601.Default%2A?displayProperty=nameWithType> to determine equality of boxes. That in turn uses the implementation of the <xref:System.IEquatable%601.Equals%2A?displayProperty=nameWithType> method in the `Box` class. Two boxes are considered equal if their dimensions are the same.
The second search specifies an equality comparer (`BoxEqVolume`) that defines equality by volume. Two boxes are considered equal if their volumes are the same.
[!code-csharp[System.Collections.Generic.EqualityComparer.Default#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.generic.equalitycomparer.default/cs/program.cs)]
[!code-vb[System.Collections.Generic.EqualityComparer.Default#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.equalitycomparer.default/vb/program.vb)]
]]></format>
</remarks>
<altmember cref="T:System.Collections.Generic.IEqualityComparer`1" />
<altmember cref="T:System.IEquatable`1" />
<altmember cref="T:System.Object" />
</Docs>
</Member>
<Member MemberName="Equals">
<MemberSignature Language="C#" Value="public abstract bool Equals (T x, T y);" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance bool Equals(!T x, !T y) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Collections.Generic.EqualityComparer`1.Equals(`0,`0)" />
<MemberSignature Language="VB.NET" Value="Public MustOverride Function Equals (x As T, y As T) As Boolean" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; abstract bool Equals(T x, T y);" />
<MemberSignature Language="F#" Value="override this.Equals : 'T * 'T -&gt; bool" Usage="equalityComparer.Equals (x, y)" />
<MemberType>Method</MemberType>
<Implements>
<InterfaceMember>M:System.Collections.Generic.IEqualityComparer`1.Equals(`0,`0)</InterfaceMember>
</Implements>
<AssemblyInfo>
<AssemblyName>System.Collections</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.10.0</AssemblyVersion>
<AssemblyVersion>4.1.0.0</AssemblyVersion>
<AssemblyVersion>4.1.1.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>mscorlib</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.0.5.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>netstandard</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="x" Type="T" />
<Parameter Name="y" Type="T" />
</Parameters>
<Docs>
<param name="x">The first object to compare.</param>
<param name="y">The second object to compare.</param>
<summary>When overridden in a derived class, determines whether two objects of type <typeparamref name="T" /> are equal.</summary>
<returns>
<see langword="true" /> if the specified objects are equal; otherwise, <see langword="false" />.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The <xref:System.Collections.Generic.EqualityComparer%601.Equals%2A> method is reflexive, symmetric, and transitive. That is, it returns `true` if used to compare an object with itself; `true` for two objects `x` and `y` if it is `true` for `y` and `x`; and `true` for two objects `x` and `z` if it is `true` for `x` and `y` and also `true` for `y` and `z`.
]]></format>
</remarks>
<block subset="none" type="overrides">
<para>Implementations are required to ensure that if the <see cref="M:System.Collections.Generic.EqualityComparer`1.Equals(`0,`0)" /> method returns <see langword="true" /> for two objects <c>x</c> and <c>y</c>, then the value returned by the <see cref="M:System.Collections.Generic.EqualityComparer`1.GetHashCode(`0)" /> method for <c>x</c> must equal the value returned for <c>y</c>.</para>
</block>
</Docs>
</Member>
<Member MemberName="GetHashCode">
<MemberSignature Language="C#" Value="public abstract int GetHashCode (T obj);" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance int32 GetHashCode(!T obj) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Collections.Generic.EqualityComparer`1.GetHashCode(`0)" />
<MemberSignature Language="VB.NET" Value="Public MustOverride Function GetHashCode (obj As T) As Integer" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; abstract int GetHashCode(T obj);" />
<MemberSignature Language="F#" Value="override this.GetHashCode : 'T -&gt; int" Usage="equalityComparer.GetHashCode obj" />
<MemberType>Method</MemberType>
<Implements>
<InterfaceMember>M:System.Collections.Generic.IEqualityComparer`1.GetHashCode(`0)</InterfaceMember>
</Implements>
<AssemblyInfo>
<AssemblyName>System.Collections</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.10.0</AssemblyVersion>
<AssemblyVersion>4.1.0.0</AssemblyVersion>
<AssemblyVersion>4.1.1.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>mscorlib</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.0.5.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>netstandard</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Int32</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="obj" Type="T" />
</Parameters>
<Docs>
<param name="obj">The object for which to get a hash code.</param>
<summary>When overridden in a derived class, serves as a hash function for the specified object for hashing algorithms and data structures, such as a hash table.</summary>
<returns>A hash code for the specified object.</returns>
<remarks>To be added.</remarks>
<exception cref="T:System.ArgumentNullException">The type of <paramref name="obj" /> is a reference type and <paramref name="obj" /> is <see langword="null" />.</exception>
<block subset="none" type="overrides">
<para>Implementations are required to ensure that if the <see cref="M:System.Collections.Generic.EqualityComparer`1.Equals(`0,`0)" /> method returns <see langword="true" /> for two objects <c>x</c> and <c>y</c>, then the value returned by the <see cref="M:System.Collections.Generic.EqualityComparer`1.GetHashCode(`0)" /> method for <c>x</c> must equal the value returned for <c>y</c>.</para>
</block>
</Docs>
</Member>
<Member MemberName="System.Collections.IEqualityComparer.Equals">
<MemberSignature Language="C#" Value="bool IEqualityComparer.Equals (object x, object y);" />
<MemberSignature Language="ILAsm" Value=".method hidebysig newslot virtual instance bool System.Collections.IEqualityComparer.Equals(object x, object y) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Collections.Generic.EqualityComparer`1.System#Collections#IEqualityComparer#Equals(System.Object,System.Object)" />
<MemberSignature Language="VB.NET" Value="Function Equals (x As Object, y As Object) As Boolean Implements IEqualityComparer.Equals" />
<MemberSignature Language="C++ CLI" Value=" virtual bool System.Collections.IEqualityComparer.Equals(System::Object ^ x, System::Object ^ y) = System::Collections::IEqualityComparer::Equals;" />
<MemberType>Method</MemberType>
<Implements>
<InterfaceMember>M:System.Collections.IEqualityComparer.Equals(System.Object,System.Object)</InterfaceMember>
</Implements>
<AssemblyInfo>
<AssemblyName>System.Collections</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.10.0</AssemblyVersion>
<AssemblyVersion>4.1.0.0</AssemblyVersion>
<AssemblyVersion>4.1.1.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>mscorlib</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.0.5.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>netstandard</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="x" Type="System.Object" />
<Parameter Name="y" Type="System.Object" />
</Parameters>
<Docs>
<param name="x">The first object to compare.</param>
<param name="y">The second object to compare.</param>
<summary>Determines whether the specified objects are equal.</summary>
<returns>
<see langword="true" /> if the specified objects are equal; otherwise, <see langword="false" />.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
This method is a wrapper for the <xref:System.Collections.Generic.EqualityComparer%601.Equals%28%600%2C%600%29> method, so `obj` must be cast to the type specified by the generic argument `T` of the current instance. If it cannot be cast to `T`, an <xref:System.ArgumentException> is thrown.
Comparing `null` is allowed and does not generate an exception.
]]></format>
</remarks>
<exception cref="T:System.ArgumentException">
<paramref name="x" /> or <paramref name="y" /> is of a type that cannot be cast to type <typeparamref name="T" />.</exception>
</Docs>
</Member>
<Member MemberName="System.Collections.IEqualityComparer.GetHashCode">
<MemberSignature Language="C#" Value="int IEqualityComparer.GetHashCode (object obj);" />
<MemberSignature Language="ILAsm" Value=".method hidebysig newslot virtual instance int32 System.Collections.IEqualityComparer.GetHashCode(object obj) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Collections.Generic.EqualityComparer`1.System#Collections#IEqualityComparer#GetHashCode(System.Object)" />
<MemberSignature Language="VB.NET" Value="Function GetHashCode (obj As Object) As Integer Implements IEqualityComparer.GetHashCode" />
<MemberSignature Language="C++ CLI" Value=" virtual int System.Collections.IEqualityComparer.GetHashCode(System::Object ^ obj) = System::Collections::IEqualityComparer::GetHashCode;" />
<MemberType>Method</MemberType>
<Implements>
<InterfaceMember>M:System.Collections.IEqualityComparer.GetHashCode(System.Object)</InterfaceMember>
</Implements>
<AssemblyInfo>
<AssemblyName>System.Collections</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.10.0</AssemblyVersion>
<AssemblyVersion>4.1.0.0</AssemblyVersion>
<AssemblyVersion>4.1.1.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>mscorlib</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.0.5.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>netstandard</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Int32</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="obj" Type="System.Object" />
</Parameters>
<Docs>
<param name="obj">The <see cref="T:System.Object" /> for which a hash code is to be returned.</param>
<summary>Returns a hash code for the specified object.</summary>
<returns>A hash code for the specified object.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
This method is a wrapper for the <xref:System.Collections.Generic.EqualityComparer%601.GetHashCode%28%600%29> method, so `obj` must be a type that can be cast to the type specified by the generic type argument `T` of the current instance.
]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException">The type of <paramref name="obj" /> is a reference type and <paramref name="obj" /> is <see langword="null" />.
-or-
<paramref name="obj" /> is of a type that cannot be cast to type <typeparamref name="T" />.</exception>
</Docs>
</Member>
</Members>
</Type>