-
Notifications
You must be signed in to change notification settings - Fork 4.5k
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
IComparer and IComparer<T> documentation should note ordering properties required #19571
Comments
cc: @rpetrusha, @AArnott |
cc: @mairaw |
Is that a responsibility of |
I would consider it reasonable to either:
I think either of those would be a big improvement over not documenting it either way. I could be convinced that the former would be too big a breaking change to be acceptable. In either case, I think it would improve clarity to also document it on the individual |
I think the warning is a good idea. |
I own these docs so I'd be the one making the updates. Just let me know who I should be working with to figure out what's the guidance we want to provide there. /cc @karelz |
Could an extra page be added describing total ordering? A concise statement linking to it would probably be clearer and with less text added to the individual pages affected. |
@JonHanna yes, it's possible to add a separate article explaining the concepts and then link to it from the affected pages. |
Total OrderA total order is a binary relation that has the following properties:
In other words:
Exceptions to Total OrderIt can perhaps be easier to think of total order by considering cases that don’t have total order. Floating point operators.Because XML Schema Datetimes without Time ZonesXML Schema defines some datatypes that are only partially ordered. One example is Not knowing the time zone, it could be e.g. 2001-04-23T09:17:39 in Copenhagen compared to 2001-04-23T11:31:09 in Dublin (earlier), or 2001-04-23T09:17:39 in Montreal compared to 2001-04-23T11:31:09 in Bangalore (later). To offer a dependable ordering within the international context XML Schema time-related data types consider, one Importance or Total Order to Sort operations.Many methods, especially sorting methods, that take an Other methods may have similar issues, such as those that find minima and maxima, such as Linq's Providing a Total Order on Partially Ordered values.If you want to sort values that are not normally totally ordered, you need to define a total ordering for it. For example, as mentioned above An approach that works for many cases, is to add a tie-breaker rule onto a partial ordering. This is used here, with most comparisons being the same as with |
@JonHanna that's a great doc on total order. 👍very concise and informative. The DateTime section is a bit verbose but explains the reasoning behind the exception to total order well. |
I split up the sentences and hopefully clarified a bit (sometimes attempts at concision end up reading more verbose than otherwise) and added a sentence at the end about using tie-breaking rules in creating total orders out of parial. |
Also fixed the copy-pasting in the example dates, as I had Montreal and Bangalore in time zones over a week apart 😁 |
Did you mean |
@svick I did indeed. Fixed. |
@mairaw did you get a chance to take a look at this? |
Not yet @ianhays. I'm completely swamped at the moment with the .NET Core release. |
Gotcha, thanks for the update :) |
Issue moved to dotnet/docs dotnet/corefx#1939 via ZenHub |
The documentation for
IComparer
(@docs.microsoft.com, @msdn) andIComparer<T>
(@docs.microsoft.com, @msdn) do not note whether any particular ordering properties are expected of a valid implementation, but at leastList<T>.Sort
assumes some (antisymmetry, per this Connect feedback circa .NET 4.5).The interface documentation should note what sort of ordering properties the rest of the standard library will be assuming/demanding of a
Compare
implementation. I'd expect this to be the usual properties of a total order.The text was updated successfully, but these errors were encountered: