-
Notifications
You must be signed in to change notification settings - Fork 1.6k
/
Copy pathIComparable.xml
198 lines (166 loc) · 13.5 KB
/
IComparable.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
189
190
191
192
193
194
195
196
197
198
<Type Name="IComparable" FullName="System.IComparable">
<TypeSignature Language="C#" Value="public interface IComparable" />
<TypeSignature Language="ILAsm" Value=".class public interface auto ansi abstract IComparable" 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-1.1;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;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.IComparable" />
<TypeSignature Language="VB.NET" Value="Public Interface IComparable" />
<TypeSignature Language="F#" Value="type IComparable = interface" />
<TypeSignature Language="C++ CLI" Value="public interface class IComparable" />
<TypeSignature Language="ILAsm" Value=".class public interface auto ansi abstract beforefieldinit IComparable" 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>1.0.5000.0</AssemblyVersion>
<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>
<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(2)]</AttributeName>
<AttributeName Language="F#">[<System.Runtime.CompilerServices.NullableContext(2)>]</AttributeName>
</Attribute>
<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;netframework-4.8;netframework-4.8.1">
<AttributeName Language="C#">[System.Runtime.InteropServices.ComVisible(true)]</AttributeName>
<AttributeName Language="F#">[<System.Runtime.InteropServices.ComVisible(true)>]</AttributeName>
</Attribute>
</Attributes>
<Docs>
<summary>Defines a generalized type-specific comparison method that a value type or class implements to order or sort its instances.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
This interface is implemented by types whose values can be ordered or sorted. It requires that implementing types define a single method, <xref:System.IComparable.CompareTo%28System.Object%29>, that indicates whether the position of the current instance in the sort order is before, after, or the same as a second object of the same type. The instance's <xref:System.IComparable> implementation is called automatically by methods such as <xref:System.Array.Sort%2A?displayProperty=nameWithType> and <xref:System.Collections.ArrayList.Sort%2A?displayProperty=nameWithType>.
The implementation of the <xref:System.IComparable.CompareTo%28System.Object%29> method must return an <xref:System.Int32> that has one of three values, as shown in the following table.
|Value|Meaning|
|-----------|-------------|
|Less than zero|The current instance precedes the object specified by the <xref:System.IComparable.CompareTo%2A> method in the sort order.|
|Zero|This current instance occurs in the same position in the sort order as the object specified by the <xref:System.IComparable.CompareTo%2A> method.|
|Greater than zero|This current instance follows the object specified by the <xref:System.IComparable.CompareTo%2A> method in the sort order.|
All numeric types (such as <xref:System.Int32> and <xref:System.Double>) implement <xref:System.IComparable>, as do <xref:System.String>, <xref:System.Char>, and <xref:System.DateTime>. Custom types should also provide their own implementation of <xref:System.IComparable> to enable object instances to be ordered or sorted.
## Examples
The following example illustrates the implementation of <xref:System.IComparable> and the requisite <xref:System.IComparable.CompareTo%2A> method.
:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/IComparable Example/CPP/source.cpp" id="Snippet1":::
:::code language="csharp" source="~/snippets/csharp/System/IComparable/Overview/source.cs" interactive="try-dotnet" id="Snippet1":::
:::code language="fsharp" source="~/snippets/fsharp/System/IComparable/Overview/source.fs" id="Snippet1":::
:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/IComparable Example/VB/source.vb" id="Snippet1":::
]]></format>
</remarks>
</Docs>
<Members>
<Member MemberName="CompareTo">
<MemberSignature Language="C#" Value="public int CompareTo (object obj);" FrameworkAlternate="dotnet-uwp-10.0;netcore-1.0;netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netframework-1.1;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;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 obj) cil managed" />
<MemberSignature Language="DocId" Value="M:System.IComparable.CompareTo(System.Object)" />
<MemberSignature Language="VB.NET" Value="Public Function CompareTo (obj As Object) As Integer" />
<MemberSignature Language="F#" Value="abstract member CompareTo : obj -> int" Usage="iComparable.CompareTo obj" />
<MemberSignature Language="C++ CLI" Value="public:
 int CompareTo(System::Object ^ obj);" />
<MemberSignature Language="C#" Value="public int CompareTo (object? obj);" 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>1.0.5000.0</AssemblyVersion>
<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>
<AssemblyVersion>2.1.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Int32</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="obj" Type="System.Object" />
</Parameters>
<Docs>
<param name="obj">An object to compare with this instance.</param>
<summary>Compares the current instance with another object of the same type and returns an integer that indicates whether the current instance precedes, follows, or occurs in the same position in the sort order as the other object.</summary>
<returns>A value that indicates the relative order of the objects being compared. The return value has these meanings:
<list type="table"><listheader><term> Value
</term><description> Meaning
</description></listheader><item><term> Less than zero
</term><description> This instance precedes <paramref name="obj" /> in the sort order.
</description></item><item><term> Zero
</term><description> This instance occurs in the same position in the sort order as <paramref name="obj" />.
</description></item><item><term> Greater than zero
</term><description> This instance follows <paramref name="obj" /> in the sort order.
</description></item></list></returns>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The <xref:System.IComparable.CompareTo%2A> method is implemented by types whose values can be ordered or sorted. It is called automatically by methods of non-generic collection objects, such as <xref:System.Array.Sort%2A?displayProperty=nameWithType>, to order each member of the array. If a custom class or structure does not implement <xref:System.IComparable>, its members cannot be ordered and the sort operation can throw an <xref:System.InvalidOperationException>.
This method is only a definition and must be implemented by a specific class or value type to have effect. The meaning of the comparisons specified in the Return Value section ("precedes", "occurs in the same position as", and "follows") depends on the particular implementation.
By definition, any object compares greater than (or follows) `null`, and two null references compare equal to each other.
The parameter, `obj`, must be the same type as the class or value type that implements this interface; otherwise, an <xref:System.ArgumentException> is thrown.
## Examples
The following example illustrates the use of <xref:System.IComparable.CompareTo%2A> to compare a `Temperature` object implementing <xref:System.IComparable> with another object. The `Temperature` object implements <xref:System.IComparable.CompareTo%2A> by simply wrapping a call to the <xref:System.Int32.CompareTo%2A?displayProperty=nameWithType> method.
:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/IComparable Example/CPP/source.cpp" id="Snippet1":::
:::code language="csharp" source="~/snippets/csharp/System/IComparable/Overview/source.cs" interactive="try-dotnet" id="Snippet1":::
:::code language="fsharp" source="~/snippets/fsharp/System/IComparable/Overview/source.fs" id="Snippet1":::
:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/IComparable Example/VB/source.vb" id="Snippet1":::
]]></format>
</remarks>
<exception cref="T:System.ArgumentException">
<paramref name="obj" /> is not the same type as this instance.</exception>
<block subset="none" type="overrides">
<para>For objects A, B and C, the following must be true:
<c>A.CompareTo(A)</c> must return zero.
If <c>A.CompareTo(B)</c> returns zero, then <c>B.CompareTo(A)</c> must return zero.
If <c>A.CompareTo(B)</c> returns zero and <c>B.CompareTo(C)</c> returns zero, then <c>A.CompareTo(C)</c> must return zero.
If <c>A.CompareTo(B)</c> returns a value other than zero, then <c>B.CompareTo(A)</c> must return a value of the opposite sign.
If <c>A.CompareTo(B)</c> returns a value "x" not equal to zero, and <c>B.CompareTo(C)</c> returns a value "y" of the same sign as "x", then <c>A.CompareTo(C)</c> must return a value of the same sign as "x" and "y".</para>
</block>
<block subset="none" type="usage">
<para>Use the <see cref="M:System.IComparable.CompareTo(System.Object)" /> method to determine the ordering of instances of a class.</para>
</block>
<altmember cref="T:System.Object" />
</Docs>
</Member>
</Members>
</Type>