-
Notifications
You must be signed in to change notification settings - Fork 1.5k
/
IStructuralComparable.xml
188 lines (156 loc) · 15.9 KB
/
IStructuralComparable.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
<Type Name="IStructuralComparable" FullName="System.Collections.IStructuralComparable">
<TypeSignature Language="C#" Value="public interface IStructuralComparable" />
<TypeSignature Language="ILAsm" Value=".class public interface auto ansi abstract IStructuralComparable" FrameworkAlternate="dotnet-uwp-10.0;net-5.0;net-6.0;net-7.0;netcore-1.0;netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netcore-3.1;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;netframework-4.8;netframework-4.8.1;netstandard-1.0;netstandard-1.1;netstandard-1.2;netstandard-1.3;netstandard-1.4;netstandard-1.5;netstandard-1.6;netstandard-2.0;netstandard-2.1" />
<TypeSignature Language="DocId" Value="T:System.Collections.IStructuralComparable" />
<TypeSignature Language="VB.NET" Value="Public Interface IStructuralComparable" />
<TypeSignature Language="F#" Value="type IStructuralComparable = interface" />
<TypeSignature Language="C++ CLI" Value="public interface class IStructuralComparable" />
<TypeSignature Language="ILAsm" Value=".class public interface auto ansi abstract beforefieldinit IStructuralComparable" FrameworkAlternate="net-8.0;net-9.0" />
<AssemblyInfo>
<AssemblyName>System.Runtime</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.10.0</AssemblyVersion>
<AssemblyVersion>4.0.20.0</AssemblyVersion>
<AssemblyVersion>4.1.0.0</AssemblyVersion>
<AssemblyVersion>4.2.0.0</AssemblyVersion>
<AssemblyVersion>4.2.1.0</AssemblyVersion>
<AssemblyVersion>4.2.2.0</AssemblyVersion>
<AssemblyVersion>5.0.0.0</AssemblyVersion>
<AssemblyVersion>6.0.0.0</AssemblyVersion>
<AssemblyVersion>7.0.0.0</AssemblyVersion>
<AssemblyVersion>8.0.0.0</AssemblyVersion>
<AssemblyVersion>9.0.0.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>mscorlib</AssemblyName>
<AssemblyVersion>2.0.5.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>netstandard</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.1.0.0</AssemblyVersion>
</AssemblyInfo>
<TypeForwardingChain>
<TypeForwarding From="mscorlib" FromVersion="4.0.0.0" To="System.Runtime" ToVersion="0.0.0.0" FrameworkAlternate="dotnet-uwp-10.0" />
<TypeForwarding From="netstandard" FromVersion="2.1.0.0" To="System.Runtime" ToVersion="5.0.0.0" FrameworkAlternate="net-5.0" />
<TypeForwarding From="netstandard" FromVersion="2.1.0.0" To="System.Runtime" ToVersion="6.0.0.0" FrameworkAlternate="net-6.0" />
<TypeForwarding From="netstandard" FromVersion="2.1.0.0" To="System.Runtime" ToVersion="7.0.0.0" FrameworkAlternate="net-7.0" />
<TypeForwarding From="netstandard" FromVersion="2.1.0.0" To="System.Runtime" ToVersion="8.0.0.0" FrameworkAlternate="net-8.0" />
<TypeForwarding From="netstandard" FromVersion="2.1.0.0" To="System.Runtime" ToVersion="9.0.0.0" FrameworkAlternate="net-9.0" />
<TypeForwarding From="System.Runtime" FromVersion="4.1.1.1" To="mscorlib" ToVersion="4.0.0.0" FrameworkAlternate="netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netframework-4.8.1" />
</TypeForwardingChain>
<Interfaces />
<Attributes>
<Attribute FrameworkAlternate="net-8.0;net-9.0">
<AttributeName Language="C#">[System.Runtime.CompilerServices.NullableContext(1)]</AttributeName>
<AttributeName Language="F#">[<System.Runtime.CompilerServices.NullableContext(1)>]</AttributeName>
</Attribute>
</Attributes>
<Docs>
<summary>Supports the structural comparison of collection objects.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The <xref:System.Collections.IStructuralComparable> interface enables you to implement customized comparisons for collection members. That is, you can define precisely what it means for one collection object to precede, follow, or occur in the same position in the sort order as a second collection object. You can then specify that this definition be used with a collection type that accepts the <xref:System.Collections.IStructuralComparable> interface.
The interface has a single member, <xref:System.Collections.IStructuralComparable.CompareTo%2A>, which determines whether the current collection object is less than, equal to, or greater than a second object in the sort order. The actual comparison of the members or elements in the current instance with those in a second object is performed by an <xref:System.Collections.IComparer> interface implementation, which contains the definition of your custom comparison.
> [!NOTE]
> The <xref:System.Collections.IStructuralComparable> interface supports only structural comparisons for sorting or ordering. The <xref:System.Collections.IStructuralEquatable> interface supports custom comparisons for structural equality.
The .NET Framework provides two default comparers. One is returned by the <xref:System.Collections.StructuralComparisons.StructuralComparer%2A?displayProperty=nameWithType> property; the other is returned by the <xref:System.Collections.Generic.Comparer%601.Default%2A?displayProperty=nameWithType> property.
The generic tuple classes (<xref:System.Tuple%601>, <xref:System.Tuple%602>, <xref:System.Tuple%603>, and so on) and the <xref:System.Array> class provide explicit implementations of the <xref:System.Collections.IStructuralComparable> interface. By casting (in C#) or converting (in Visual Basic) the current instance of an array or tuple to an <xref:System.Collections.IStructuralComparable> interface value and providing your <xref:System.Collections.IComparer> implementation as an argument to the <xref:System.Collections.IStructuralComparable.CompareTo%2A> method, you can define a custom sort order for the array or collection. However, you do not call the <xref:System.Collections.IStructuralComparable.CompareTo%2A> method directly in most cases. Instead, the <xref:System.Collections.IStructuralComparable.CompareTo%2A> method is called by sorting methods such as <xref:System.Array.Sort%28System.Array%2CSystem.Collections.IComparer%29>. In this case, you define your <xref:System.Collections.IComparer> implementation and pass it as an argument to a sorting method or collection object's class constructor. The <xref:System.Collections.IStructuralComparable.CompareTo%2A> method with your custom comparer is then called automatically whenever the collection is sorted.
## Examples
The following example creates an array of <xref:System.Tuple%606> objects that contains population data for three U.S. cities from 1960 to 2000. The sextuple's first component is the city name. The remaining five components represent the population at ten-year intervals from 1960 to 2000.
The `PopulationComparer` class provides an <xref:System.Collections.IComparer> implementation that allows the array of sextuples to be sorted by any one of its components. Two values are provided to the `PopulationComparer` class in its constructor: the position of the component that defines the sort order, and a Boolean value that indicates whether the tuple objects should be sorted in ascending or descending order.
The example then displays the elements in the array in unsorted order, sorts them by the third component (the population in 1970) and displays them, and then sorts them by the sixth component (the population in 2000) and displays them. Note that the example does not directly call the <xref:System.Collections.IStructuralComparable.CompareTo%2A> method. The method is called implicitly by the <xref:System.Array.Sort%28System.Array%2CSystem.Collections.IComparer%29> method for each tuple object in the array.
:::code language="csharp" source="~/snippets/csharp/System/TupleT1,T2,T3,T4,T5,T6/System.Collections.IStructuralComparable.CompareTo/compareto2.cs" id="Snippet2":::
:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.tuple`6.compareto/vb/compareto2.vb" id="Snippet2":::
]]></format>
</remarks>
<altmember cref="T:System.IComparable" />
<altmember cref="T:System.Collections.IStructuralEquatable" />
<altmember cref="P:System.Collections.StructuralComparisons.StructuralComparer" />
</Docs>
<Members>
<Member MemberName="CompareTo">
<MemberSignature Language="C#" Value="public int CompareTo (object other, System.Collections.IComparer comparer);" FrameworkAlternate="dotnet-uwp-10.0;netcore-1.0;netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;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;netframework-4.8;netframework-4.8.1;netstandard-1.0;netstandard-1.1;netstandard-1.2;netstandard-1.3;netstandard-1.4;netstandard-1.5;netstandard-1.6;netstandard-2.0;netstandard-2.1" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance int32 CompareTo(object other, class System.Collections.IComparer comparer) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Collections.IStructuralComparable.CompareTo(System.Object,System.Collections.IComparer)" />
<MemberSignature Language="VB.NET" Value="Public Function CompareTo (other As Object, comparer As IComparer) As Integer" />
<MemberSignature Language="F#" Value="abstract member CompareTo : obj * System.Collections.IComparer -> int" Usage="iStructuralComparable.CompareTo (other, comparer)" />
<MemberSignature Language="C++ CLI" Value="public:
 int CompareTo(System::Object ^ other, System::Collections::IComparer ^ comparer);" />
<MemberSignature Language="C#" Value="public int CompareTo (object? other, System.Collections.IComparer comparer);" FrameworkAlternate="net-5.0;net-6.0;net-7.0;net-8.0;net-9.0;netcore-3.0;netcore-3.1" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>System.Runtime</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.10.0</AssemblyVersion>
<AssemblyVersion>4.0.20.0</AssemblyVersion>
<AssemblyVersion>4.1.0.0</AssemblyVersion>
<AssemblyVersion>4.2.0.0</AssemblyVersion>
<AssemblyVersion>4.2.1.0</AssemblyVersion>
<AssemblyVersion>4.2.2.0</AssemblyVersion>
<AssemblyVersion>5.0.0.0</AssemblyVersion>
<AssemblyVersion>6.0.0.0</AssemblyVersion>
<AssemblyVersion>7.0.0.0</AssemblyVersion>
<AssemblyVersion>8.0.0.0</AssemblyVersion>
<AssemblyVersion>9.0.0.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>mscorlib</AssemblyName>
<AssemblyVersion>2.0.5.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>netstandard</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.1.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Int32</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="other" Type="System.Object">
<Attributes>
<Attribute FrameworkAlternate="net-8.0;net-9.0">
<AttributeName Language="C#">[System.Runtime.CompilerServices.Nullable(2)]</AttributeName>
<AttributeName Language="F#">[<System.Runtime.CompilerServices.Nullable(2)>]</AttributeName>
</Attribute>
</Attributes>
</Parameter>
<Parameter Name="comparer" Type="System.Collections.IComparer" />
</Parameters>
<Docs>
<param name="other">The object to compare with the current instance.</param>
<param name="comparer">An object that compares members of the current collection object with the corresponding members of <paramref name="other" />.</param>
<summary>Determines whether the current collection object precedes, occurs in the same position as, or follows another object in the sort order.</summary>
<returns>A signed integer that indicates the relationship of the current collection object to <paramref name="other" /> in the sort order:<br /> - If less than 0, the current instance precedes <paramref name="other" />.<br /> - If 0, the current instance and <paramref name="other" /> are equal.<br /> - If greater than 0, the current instance follows <paramref name="other" />.
<list type="table"><listheader><term> Return value
</term><description> Description
</description></listheader><item><term> -1
</term><description> The current instance precedes <paramref name="other" />.
</description></item><item><term> 0
</term><description> The current instance and <paramref name="other" /> are equal.
</description></item><item><term> 1
</term><description> The current instance follows <paramref name="other" />.
</description></item></list></returns>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The <xref:System.Collections.IStructuralComparable.CompareTo%2A> method supports custom structural comparison and sorting of array and tuple objects. The <xref:System.Collections.IStructuralComparable.CompareTo%2A> method calls the `comparer` object's <xref:System.Collections.IComparer.Compare%2A?displayProperty=nameWithType> method to compare individual array elements or tuple components, starting with the first element or component. The individual calls to <xref:System.Collections.IComparer.Compare%2A?displayProperty=nameWithType> end and the <xref:System.Collections.IStructuralComparable.CompareTo%2A> method returns a value when one of the following conditions becomes true:
- The <xref:System.Collections.IComparer.Compare%2A?displayProperty=nameWithType> method returns -1.
- The <xref:System.Collections.IComparer.Compare%2A?displayProperty=nameWithType> method returns 1.
- The <xref:System.Collections.IComparer.Compare%2A?displayProperty=nameWithType> method is called for the last element or component in the collection object.
## Examples
The following example creates an array of <xref:System.Tuple%606> objects that contains population data for three U.S. cities from 1960 to 2000. The sextuple's first component is the city name. The remaining five components represent the population at ten-year intervals from 1960 to 2000.
The `PopulationComparer` class provides an <xref:System.Collections.IComparer> implementation that allows the array of sextuples to be sorted by any one of its components. Two values are provided to the `PopulationComparer` class in its constructor: the position of the component that defines the sort order, and a <xref:System.Boolean> value that indicates whether the tuple objects should be sorted in ascending or descending order.
The example then displays the elements in the array in unsorted order, sorts them by the third component (the population in 1970) and displays them, and then sorts them by the sixth component (the population in 2000) and displays them. Note that the example does not directly call the <xref:System.Collections.IStructuralComparable.CompareTo%2A?displayProperty=nameWithType> implementation. The method is called implicitly by the <xref:System.Array.Sort%28System.Array%2CSystem.Collections.IComparer%29> method for each tuple object in the array.
:::code language="csharp" source="~/snippets/csharp/System/TupleT1,T2,T3,T4,T5,T6/System.Collections.IStructuralComparable.CompareTo/compareto2.cs" id="Snippet2":::
:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.tuple`6.compareto/vb/compareto2.vb" id="Snippet2":::
]]></format>
</remarks>
<exception cref="T:System.ArgumentException">This instance and <paramref name="other" /> are not the same type.</exception>
<altmember cref="T:System.Collections.IComparer" />
</Docs>
</Member>
</Members>
</Type>