Change:
The docs do not document what is de facto required of trait implementors in order for data structures to work correctly. We should update them! Per : <details<summaryThis post used to say something different. Here is the original post</summaryWhy doesn't require irreflexivity over ? AFAICT does not actually express any kind of ordering relation for . For: a strict partial order on : we need + non-strict partial order on : we need + since must be reflexive. total order: we need Is this an oversight? If not, we should document that requires: irreflexivity: as well. That would make 's denote a strict partial order on . AFAICT this is actually what was intended, since all the discussions I can find online about talk about floats, and floats are strictly partially ordered under , but not non-strictly partially ordered under , which would fit our current model that floats don't implement . Also, the docs of do not say what () and () actually mean. AFAICT they mean nothing for in isolation. From reading the source the default implementation is , which would denote a non-strict total ordering over when is implemented. But since is not required for , I'd guess that those overriding these implementations are allowed to do something else as long as they don't implement . It is unclear to me what that "something else" might mean, but the docs should probably say something about this. Also, I haven't been able to find any document explaining why things are the way they are, but the fact that requires makes no sense to me, and it doesn't make much sense either that exposes () and () methods, since as mentioned above, without , and do not express any meaningful ordering relation. It seems that these traits, like all other "operators" traits, mix operator overloading with mathematical semantics: in some cases they are used to express mathematical concepts, like a strict partial ordering relation under , and in some other cases they are used "to provide <= for floats". If anybody has any links to any discussions / documentation about why things are the way they are I'd like to read them, and maybe we should add rationale sections to the docs. </details
In the RFC thread for , mentioned that probably also requires: if and only if (they called it "the 'notational' axiom"). Irreflexivity is implied by said notational axiom and the semantics of . Simple proof: for irreflexivity to not be satisfied, would have to be false for some . This means that for some , would have to be true. Using the notational axiom that means that would have to be true as well (I swapped the two s). But and cannot be true at the same time (this last fact is merely implied by the type ... but I guess it's worth putting it in the docs explicitly). Thus, instead of adding the axiom of Irreflexivity to the docs, one could also add the notational axiom (which we probably want to add anyway). The docs are also unclear or plain wrong in regards to the provided methods , and friends. The docs say: This implies that one has to manually implement and friends to achieve a non-total ordering. This is false. In fact it's misleading because and friends need to be implemented in a way that has the same behavior as the default implementation. Otherwise would disagree with and friends. The docs should explicitly disallow such disagreement between methods. (Since semantics of and friends mustn't be changed, the only reason to provide a manual implementation is speed.)
mentioned on IRC: That is, the docs should state that is equivalent to and is equivalent to and that any manual implementation must respect that.
Agreed. This is stated explicitly for PartialEq, it seems it as forgotten here. I think that's the wrong way to think about it: PartialOrd is only a single operation, . This operation is then used to define <, <=, and =. There is no choice left here, the only reason it is possible to override the default implementations (as said) is to make them go faster.
Yeah that sounds pretty reasonable. I'd express this as "is the dual to <", I think that's the common terminology in maths. I briefly wondered how this relates to antisymmetry... but antisymmetry is a strange axiom in this context. In fact, antisymmetry is impossible to violate! If , then , so we already have . So, I think we can just drop it. If we require that and are defined in terms of (or equivalent), antisymmetry will always hold. (EDIT: This assume is the negated boolean ... because I cannot imagine any other reasonable interpretation.)
Wouldn't we then need to require that if then or something like that? EDIT: I see this as just trading one axiom for another. We probably should document the axioms both in term of the comparisons , , ... (which is more easy for some people to understand) and in terms of (which is what everybody has to implement).
That's the "notational" (or "duality") axiom: implies .
Aha! Yeah if we add that axiom then we don't need anti-symmetry. Nice! The wikipedia page on actually mentions this, that one axiom follows from the other two: (just note that we don't require irreflexivity yet)
So to make a more concrete proposal. We currently have specified as: Including all feedback above, we could change that to (strawman): I am not sure if everything does indeed follow properly from and . Even if it does, this is a question that some might have, and even if this is all trivial to prove, I think we should have a "Proofs" section in the docs of with the proofs. Do you think that such a section makes sense?
Awesome, thank you! A few things though: Are you sure? I don't think transitivity (" and implies ") can be derived from the axioms. E.g. if and , then either or and could be uncomparable. I don't see how the current axioms prevent and from being uncomparable, but maybe I missed something. I would change this to "Strict partial ordering relationS." as the trait adds and , two new strict partial ordering relations. Maybe even change it to "Strict partial ordering relations and ." Maybe we want to explicitly state that and friends return if returns . Or in general we might want to talk about what returning means. And maybe add the information implied by : "At most one of , and is true." I don't think you only need duality and transitivity of here:
I was talking here about , not and which "follow" from it. I don't know a better way to put it yet, but I wanted to emphasize that is the "relation" that users have to implement. From there it follows that and are strict partial orders. I don't know, I find a bit weird to think about. So when I wrote the axioms in term of I wrote . Maybe we should explicitly mention this: is is Yes you are correct, I ninja edited the post. Step by step: "if and implies " is equivalent to " implies which is equivalent to " implies or implies " which is "true or false" which is "true". Or what am I missing? The only requirement of over is reflexivity: . So IIUC that requires a to be comparable with itself.
Mhh, yes that's tricky :/ But as far as I understand it, is not a relation in the mathematical sense. it looks like a binary relation is just a subset of the cartesian product X × Y of two sets. Basically meaning that a relation just says or for every pair of members of the two sets. certainly says more than that. In fact, I think that defines exactly three (disjunct) relations (disjunct meaning that no two of those relations have a member in common). I mean yes, "relation" is also just an English word that would fit here from a non-math standpoint. But since the documentation mentions some exact math terms, I wouldn't use "relation" (which has an exact mathematical definition) in the non-mathematical sense. Maybe the first paragraph of docs should be targeted at the standard user who is not interested in axioms or exact mathematical terms. Maybe explain it in terms of "comparison"? I'd say so. I'm not sure about your first step: you say " and " is equivalent to "". I mean it intuitively makes sense but can that be derived from the axioms? As far as I can think it through, you can only show that: is false: otherwise is true, which is equivalent to (duality and swapping two terms), which is equivalent to (transitivity of ), which is (disjunction of and relation). is false: otherwise is true, which is equivalent to , which is (again due to disjunction of and ) So we still have two possibilities: either (what we want to show) or and are not comparable. To show that is in fact implied, we'd have to show that and are necessarily comparable, right? And: This only requires everything to be comparable with itself, which doesn't help us because and are not the same element. But again, maybe I'm missing something.
nice first strawman! I overall like it. I think before stating any axioms, however, we should define , , and (or maybe just and ) in terms of . Otherwise the axioms don't actually mean anything. Moreover, we should spell out what it means to "agree" with , I guess we want an axiom like " if and only if "? As pointed out, these statements are not well-typed: is not a relation (it does not have type ). Please spell out which relation(s) you mean: , , , ? I'd add "and from the definition of et al. in terms of the same " This is some kind of congruence statement: Essentially, we demand that implies , or similar (and also for replacing the second argument). So maybe, instead of what I said above, the real meaning of " agrees with " is and imply , AND if and only if However, these may be too strong for irreflexive equalities? seems fine though (this mandates that , but that seems reasonable). Can we derive one of these axioms from the other? Or find one nicer axiom that implies both of them?
So, I've only been half-following this. I'm afraid I'll really only just be adding to the noise; but here's how I feel inclined to look at it: We need at least as many axioms as we have methods. This is unavoidable. Most axioms can be as boring as the notational/duality axiom, simply defining one method in terms of another. I am fairly certain that all methods of the traits can be defined in terms of alone. Is difficult to elaborate right now as I am on my phone, but I picture the directed graph formed by edges from to wherever . What are the axioms of ? I think that for PartialOrd, it's just ~associativity.~ i mean transitivity!
Tagging with they need to make a call before we can write docs.
Seems reasonable. The docs in seem plausible to me. Would it make sense to use rfcbot to gather consensus asynchronously?
Is there a recommended way to put up a documment that we could quickly edit for this collaboratively? It appears to me that after and comments we are 95 % there, we just need to finish it, and for that it might be better if we would just have something that's "uptodate" and that we can quickly eidt.
I don't know if that's what you had in mind, but I created from your comment. Everyone can login via GitHub and edit. But it might be better to have a tiny repository where we submit the documentation as PR and we can leave line comments?
thanks! I worked a bit on it there and this is how it looks now (it would be cool if the tool could create diffs, so maybe a github repo would be better for something like this in the future): Documentation . This trait extends the partial equivalence relation provided by () with , which is a ) of the ordering relation when its result is : if then if then if then and the absence of an ordering between and when . Furthermore, this trait defines as and as . The comparisons must satisfy, for all , , and : transitivity: if and then duality: if then The (), (), (), and () methods are implemented in terms of according to these rules. The default implementations can be overridden for performance reasons, but manual implementations must satisfy the rules above. From these rules it follows that must be implemented symmetrically and transitively: if and then and . The following corollaries follow from transitivity of , duality, and from the definition of et al. in terms of the same : irreflexivity of : transitivity of : if and then asymmetry of : if then antisymmetry of : if then Stronger ordering relations can be expressed by using the and traits, where the methods provide: a if a if
Yes, diffs and PR-comments would be nice. I created a temporary repository and . I'd suggest we could discuss everything there. I already left a few comments on the PR. I also gave you push access to the repo, so feel free to change things as you like.
(small note: is the "strict partial order", and the "non-strict partial order" - but the latter also requires - mathematically, the "operators" are the orders, not )
I a comment with an alternative formulation .
Looks like . I'm not sure, but it almost seems like they have an combination?
The latest paper is . The most relevant section for this discussion is probably "Section 2: Design" which defines the following comparison categories as types: is a is a is a is a and a The values of the equality categories are: returns returns which are converted to when converted to results. This is very similar to rust: interpret returning as and as , and when is also implemented interpret these as and respectively. The orderings are also pretty similar: values are which can be implicitly converted to the values as values are and implicitly convert to: values as values as values are and implicitly convert to: values as values as values as The paper is a bit light on math details; maybe some of this is covered in Stepanov's "From Mathematics to Generic Programming" or "Elements of Programming, worth checking this out. Basically, the paper says that a type should implement if only should be provided, and only if should also be provided. It also says that it should implement if values can be unordered, if does not imply , and if implies , where in both last cases " reads only comparison-salient state that is accessible using the public members". The most interesting examples are: s: implement multiple orderings. The default provided by is because of , however a total ordering is available in an opt-in way via the named comparison functions. That is returns the partial order, but returns the IEEE total order. The system is flexible enough to support this. It is as if in Rust one could implement with different semantics than , and also choose whether the or the implementations map to (I happen to think that one of Rust's lib biggest mistakes is mixing operator overloading with mathematical semantics; they are orthogonal concerns that don't mix well). implements because does not imply
Another related concern I have with how the current traits work is that there is no way to express that some relations actually denote a total order. For example, given: there is no way to implement .
I am confused, of course you can implement ...? Or do you mean because it requires ?
I've filled an issue in the rfc repo: Maybe the explanation there is more clear?
Yes, I understand now where you are coming from. Thanks.
Cc
I really like the proposal above by but we are still abusing terminology from math. Partial and full equivalence relations as well as partial and total orders are all defined using binary relations on the same set—which is roughly analogous to types. Since the traits allow one to talk about two different sets/types though, this means those terms aren't even applicable. After all what does "symmetric" or "reflexive" even mean when the binary relation is on two different sets? If we use encoding of a binary relation (i.e., a function, , where the "inputs" that get mapped to represent the binary relation), then I suppose that means we say the pair of functions is "symmetric" iff for all in and in ? No clue how one would adapt reflexivity and irreflexivity though. I feel like one can come up with some form of argument that invokes vacuous truths. Something like the function is "reflexive" on since it is impossible to come up with a counterexample (i.e., a value such that ). Clearly this is a nonsense though since isn't even defined on .
Indeed symmetry can be defined on "heterogeneous" relations like you say, but (ir)reflexivity just doesn't make sense in general.
should require that types that implement for some type to be either empty (e.g., ) or for there to exist elements/terms/instances, of and of , such that ? What is stopping all types from implementing that trait? Clearly the motivation of that trait is due to IEEE 754, but at least the binary and decimal formats defined by that have some values that evaluate as equivalent.
I am not sure what would be the point of such a requirement. While / are certainly the most prominent examples, the concept of a "partial equivalence relation" (a relation that's symmetric and transitive but not necessarily reflexive) is well established and used throughout the math/CS academic literature.
I realize that, but Rust is intentionally not the most "theoretically sound" language (nor should it be). Consequently there not existing some beautiful theoretical justification—as nice as that would be—is not enough reason to not add a requirement. After all, doesn't even have the bound on despite clearly requiring such a thing in the interest of ergonomics. The dilemma I am facing is differentiating between the semantics of a type not implementing of itself vs. implementing such that always returns . I don't have this problem with most traits. When a type implements a trait, you are not just defining some functionality for that type but in fact imbuing the type with additional structure. This is where using sets as analogs to types breaks down since sets have effectively no structure unlike things like topological spaces or categories. For example, it is "obvious" why does not implement for any type . There is a sufficient amount of structure that goes along with being an iterator that the difference between not implementing it and implementing the degenerative form of it (i.e., always returning ) is clear. s obviously don't have that kind of structure. In contrast, is so "primitive" that I am genuinely struggling in gaining an intuition of when a type should not implement it vs. implement its degenerative form. This is why I suggested the requirement that the type is either uninhabited or have at least two terms (potentially being the same) that evaluate as equivalent. This "solves" this dilemma since there is now a clear distinction between not implementing the trait and implementing its most degenerative form. I cannot come up with a type where not implementing has obviously different semantics than implementing it such that always returns . Can you provide one? Edit After reflecting on what I said, there are two interpretations of why a type would not implement of itself: either the type has some terms that can be interpreted as being "similar", but this "similarity" fails either symmetry or transitivity or the type has no notion of equivalence for any of the terms. It is the latter situation that I am struggling in distinguishing from implementing such that always returns . Perhaps this is where my math background is rearing its ugly head and I am conflating extensional equality/equivalence with intentional?
You say that, and then you go on making arguments based entirely on theoretic concerns about the "structure" that a trait imbues on a type. I really don't know how to make sense of that.^^ Usually in partial equivalence relations (but you probably know this), means that is "valid" in some sense -- i.e., elements such as NaN that are not equal to themselves are considered "invalid" elements. I see no issue with having a type like So, I guess I don't share your issues with types whose equivalence relation is empty. Yes, there is a trivial partial equivalence relation for each type. However, note that there even is a trivial proper equivalence relation for each type, namely always returning -- this even satisfies all the conditions for ! Would you say that provides "no structure"? The type that picked does provide more information than a bare type ("an unstructured set") just by virtue of picking this partial equivalence relation instead of any other one that it might have picked. The absence of any interesting structure is still some information about the structure of the type. FWIW there also is a trivial and fairly canonical (I would say) implementation for each type that satisfies all the laws, namely always returning . So I really can't follow your arguments for why you feel that a trait needs to be non-trivial to implement for it to provide meaningful "structure". I am a type theorist more than a set theorist, so I fully agree that structure is important, but I see no problem with a type that decides (via its implementation) to have trivial structure. Having "free" instances of a structure is a common theme in algebra / category theory (and indeed "free" is a technical term here). Can you come up with any concrete problems in real consumers of that such a type might cause?
I suppose what I meant—but clearly did a poor job in conveying—is that I don't need the super technical encoding of some concept. While I realize having words like "structure" are more technical than others; from the perspective of math, it is very much informal (i.e., I am ignoring any formulation based on first-order logic/type theory of what that term means). I also hope I did not come off as rude or dismissive. Not that it matters one iota what I think, but I very much love Rust and have immense respect/envy for the language team. I hope my comments have not offended/upset you (or anyone else); but if so, I apologize. Any frustration I have is at myself for the difficulty I am having in gaining an intuition of what should likely be a pretty easy concept. I realize that always returning is also a trivial implementation, but I did not mention it since it "feels" more useful than one that always returns . As a type theorist, I am sure this absurdly informal terminology is painful; but it is the best way I can convey what I mean in English. As I said above, I realize that one can easily implement pretty much any trait they want for almost any type; but for some reason, my stupid brain has an intuition as to why one would not want to implement for something like but is having difficulty in justifying why one would define a type that does not implement (because it could simply always have always return ). I think we have come to a point where I just need to reflect more because I understand what you mean from a technical perspective that having implement a trivial version of does give it more "structure" than if it were to not implement it at all (i.e., you go from a "set" to a "set with a partial equivalence relation"). I cannot think of a concrete problem for "real consumers" of . It seems as though I should have exhibited more patience with myself in ruminating the differences, so I apologize for wasting your time. The subtlety of the additional structure that a trivial implementation of provides is just not as "obvious" as the rather "obvious" amount of additional structure one gets from a trivial implementation of a trait like .
No offense was taken, I enjoyed this fun little exchange. :) But I agree that there's not much to go on with here, since sadly we don't have the tech for me to meet you in your brain space where you "feel" why things make sense on way but not the other. I know very well that expressing such intuition in words that make sense to other humans can be hard; I hope in pondering these issues you reach a better understanding that either resolves this concern or leaves you in a better way to express it. :)
I often wish Rust used more things. For example, it makes sense to me that and , but in Rust it's also true that either or -- and I can never remember which of them. (Is there a good justification for which? Is it really just completely arbitrary? Do people every really use s as keys to care? How ) Admittedly that's a bit of a tangent, but maybe it'll help give you another scenario on which to reflect, Zack.
Wow, I had no idea that ... looks like it is a , so I assume this is some kind of lexicographic order based on enum variants or so. But I agree just keeping unrelated variants unordered wrt each other would have been a better default... of course then it couldn't implement though.
Yup, that's right. Same as how the only place where the order of the fields in a struct matters is in how it impacts the derive.
All arguments aside, has been stable in its current form for a long time. I'm inclined to say that changes to it have to pass a very high bar, and it seems like there isn't much consensus around this at all. I'd be inclined to close it.
My brain decided to just not work for a little bit. Now that I've gotten more sleep, I'm embarrassed by my confusion above. I think there would be some use for a "true equality" trait. I feel like is too extreme where effectively the "raw bits" must be the same as opposed to indiscernibility based only on the public API of a type, but that is orthogonal to this.
So you mean, like but so that one can properly rely on its axioms? , so to speak? I don't know how to make sense of "indiscernibility based only on the public API", that seems hard to pin down.
Either way, I think this particular issue can be closed.
I think there is a lot of valuable information buried in this issue, like . Sadly, the work of actually turning this into new docs for was never done. The intention, I think, is less to change and more to figure out what its true contract is and relate it to well-known mathematical concepts.
OK, perhaps we can modify the issue title. I'm a bit reluctant to "add new contracts" to (who knows what impls are out there?). At the same time, I think if we can say "what requirements already exist for things to behave properly" and document those, then this is great.
Yeah, this issue has gone a long way since it was created, and title / description have not kept up. FWIW our conclusion was that we basically already require to be irreflexive, since that is the only way the following equivalences can be upheld: iff iff iff EDIT: and moreover, is a pure function (always returning the same result for the same inputs) The docs are not explicitly stating that these equivalences must hold, but it seems very much against the spirit of this trait to allow violations of these equivalences. The fact that is very useful here as it makes the 2nd axiom well-defined.
I find it useful to think of structures of things on a continuum where as one progresses along this continuum, additional properties must be upheld. So in this case, I'll call it the "continuum of equality" where towards one end you have notions like equivalence relations where you don't care about all the properties of equality but only those of reflexivity, symmetry, and transitivity. As you progress further, you then encounter notions of isomorphisms—or whatever the term is in that particular discipline (e.g., homeomorphisms in topology)—which have more properties associated with them than just equivalence. Since math doesn't typically have notions of "public API" or "internals", this is normally enough to model "equality"; however in set theory, one can still progress further and differentiate isomorphisms (i.e., bijections) from equality (i.e., where both sets are subsets of one another). So where along this continuum does "indiscernibility based only on the public API" lie? Maybe I am mistaken here, but I feel like in Rust the properties one must uphold in relation to a are restricted to the public API of that type (unless otherwise stated). Because of this, I find too restrictive since it requires the internals to be the same. It is certainly possible for one to achieve this "indiscernibility" without requiring the actual internals to be the same though at least from this "public API" perspective. As an explicit example: There is no way downstream code can differentiate something like 1/2 from 2/4 using the public API of . The only way one can is via pointer shenanigans which under this perspective would not constitute as a proof since you're in strict violation of this "public API" notion. Now if one decides to expose a function like as part of the public API of , then they must either construct the canonical representation of that rational number inside of —in doing so, they'd now satisfy structural equality too—or do so as part of —and hopefully cache this reduction since it is a rather "expensive" process. Maybe this is too "niche" though. I just know that people tend to attach more properties associated with equivalence than they should since that equivalence relation really only says something about that type under that specific relation. For example, if ones knows and are both "equal" (technically equivalent), it is easy to treat and as the same regardless of what you plan to do with them; but that is simply untrue. This in turn can of course lead to invalid programs. I think some people would say that "the side effects" of using may be different than despite the two being equivalent. My proposal for a like would be that terms that are equal have the same observable "side effects" from the perspective of the entire public API of that type. For completeness sake, I'd argue that one can continue along this "continuum of equality" and incorporate something like spacetime and have stricter forms of equality than even structural equality where the "raw bits" are still not enough; but we are getting rather "absurd" at this point. Edit A cursory Google search led to admittedly old Reddit discussion. As the type theorist, you likely are better equipped at formulating what drb226 and philipjf are talking about (warning: this concerns Haskell which I know is a different language with different goals than Rust).
As discussed, I'd hope terms like "irreflexive" would not be used in the documentation since it makes no sense in general; unless you explicitly qualify it with "when , …". I do like explicitly stating those bullet points though.
I think "irreflexive" is still a useful term, but we should probably say explicitly that it only makes sense when . Regarding "indiscernibility based only on the public API", I think I got a rough idea of what you mean, and indeed I think I have seen ways to make that more precise -- but in the interest of not further derailing this thread, I won't reply in any more detail here. :)
I created a PR to update the docs:

Discussion:
/// Trait for equality comparisons which are [partial equivalence /// relations](https://en.wikipedia.org/wiki/Partial_equivalence_relation). /// <ins> /// `x.eq(y)` can also be written `x == y`, and `x.ne(y)` can be written `x != y`. /// We use the easier-to-read infix notation in the remainder of this documentation. /// </ins> /// This trait allows for partial equality, for types that do not have a full /// equivalence relation. For example, in floating point numbers `NaN != NaN`, /// so floating point types implement `PartialEq` but not [`trait@Eq`]. /// <del> /// Formally, the equality must be (for all `a`, `b`, `c` of type `A`, `B`, /// `C`): </del> <ins> /// Implementations must ensure that `eq` and `ne` are consistent with each other: /// /// - `a != b` if and only if `!(a == b)` ///   (ensured by the default implementation). /// /// If [`PartialOrd`] or [`Ord`] are also implemented for `Self` and `Rhs`, their methods must also /// be consistent with `PartialEq` (see the documentation of those traits for the exact /// requirememts). It's easy to accidentally make them disagree by deriving some of the traits and /// manually implementing others. /// /// The equality relation `==` must satisfy the following conditions /// (for all `a`, `b`, `c` of type `A`, `B`, `C`): </ins> /// /// - **Symmetric**: if `A: PartialEq<B>` and `B: PartialEq<A>`, then **`a == b` ///   implies `b == a`**; and

/// /// ## How can I implement `PartialEq`? /// <del> /// `PartialEq` only requires the [`eq`] method to be implemented; [`ne`] is defined /// in terms of it by default. Any manual implementation of [`ne`] *must* respect /// the rule that [`eq`] is a strict inverse of [`ne`]; that is, `!(a == b)` if and /// only if `a != b`. /// /// Implementations of `PartialEq`, [`PartialOrd`], and [`Ord`] *must* agree with /// each other. It's easy to accidentally make them disagree by deriving some /// of the traits and manually implementing others. /// </del> /// An example implementation for a domain in which two books are considered /// the same book if their ISBN matches, even if the formats differ: ///

/// Trait for types that form a [total order](https://en.wikipedia.org/wiki/Total_order). /// <del> /// An order is a total order if it is (for all `a`, `b` and `c`): </del> <ins> /// Implementations must be consistent with the [`PartialOrd`] implementation, and ensure /// `max`, `min`, and `clamp` are consistent with `cmp`: /// /// - `partial_cmp(a, b) == Some(cmp(a, b))`. /// - `max(a, b) == max_by(a, b, cmp)` (ensured by the default implementation). /// - `min(a, b) == min_by(a, b, cmp)` (ensured by the default implementation). /// - For `a.clamp(min, max)`, see the [method docs](#method.clamp) ///   (ensured by the default implementation). /// /// It's easy to accidentally make `cmp` and `partial_cmp` disagree by /// deriving some of the traits and manually implementing others. /// /// ## Corollaries /// /// From the above and the requirements of `PartialOrd`, it follows that `<` defines a strict total order. /// This means that for all `a`, `b` and `c`: </ins> /// <del> /// - total and asymmetric: exactly one of `a < b`, `a == b` or `a > b` is true; and /// - transitive, `a < b` and `b < c` implies `a < c`. The same must hold for both `==` and `>`. </del> <ins> /// - exactly one of `a < b`, `a == b` or `a > b` is true; and /// - `<` is transitive: `a < b` and `b < c` implies `a < c`. The same must hold for both `==` and `>`. </ins> /// /// ## Derivable ///

/// Then you must define an implementation for [`cmp`]. You may find it useful to use /// [`cmp`] on your type's fields. /// <del> /// Implementations of [`PartialEq`], [`PartialOrd`], and `Ord` *must* /// agree with each other. That is, `a.cmp(b) == Ordering::Equal` if /// and only if `a == b` and `Some(a.cmp(b)) == a.partial_cmp(b)` for /// all `a` and `b`. It's easy to accidentally make them disagree by /// deriving some of the traits and manually implementing others. /// </del> /// Here's an example where you want to sort people by height only, disregarding `id` /// and `name`: ///

/// Trait for values that can be compared for a sort-order. /// <ins> /// The `lt`, `le`, `gt`, and `ge` methods of this trait can be called using /// the `<`, `<=`, `>`, and `>=` operators, respectively. /// /// The methods of this trait must be consistent with each other and with those of `PartialEq` in /// the following sense: /// /// - `a == b` if and only if `partial_cmp(a, b) == Some(Equal)`. /// - `a < b` if and only if `partial_cmp(a, b) == Some(Less)` ///   (ensured by the default implementation). /// - `a > b` if and only if `partial_cmp(a, b) == Some(Greater)` ///   (ensured by the default implementation). /// - `a <= b` if and only if `a < b || a == b` ///   (ensured by the default implementation). /// - `a >= b` if and only if `a > b || a == b` ///   (ensured by the default implementation). /// - `a != b` if and only if `!(a == b)` (already part of `PartialEq`). /// /// If [`Ord`] is also implemented for `Self` and `Rhs`, it must also be consistent with /// `partial_cmp` (see the documentation of that trait for the exact requirements). It's /// easy to accidentally make them disagree by deriving some of the traits and manually /// implementing others. /// </ins> /// The comparison must satisfy, for all `a`, `b` and `c`: /// <del> /// - asymmetry: if `a < b` then `!(a > b)`, as well as `a > b` implying `!(a < b)`; and </del> /// - transitivity: `a < b` and `b < c` implies `a < c`. The same must hold for both `==` and `>`. <ins> /// - duality: `a < b` if and only if `b > a`. </ins> /// /// Note that these requirements mean that the trait itself must be implemented symmetrically and /// transitively: if `T: PartialOrd<U>` and `U: PartialOrd<V>` then `U: PartialOrd<T>` and `T: /// PartialOrd<V>`. /// <ins> /// ## Corollaries /// /// The following corollaries follow from the above requirements: /// /// - irreflexivity of `<` and `>`: `!(a < a)`, `!(a > a)` /// - transitivity of `>`: if `a > b` and `b > c` then `a > c` /// - duality of `partial_cmp`: `partial_cmp(a, b) == partial_cmp(b, a).map(Ordering::reverse)` /// </ins> /// ## Derivable /// /// This trait can be used with `#[derive]`. When `derive`d on structs, it will produce a

/// /// `PartialOrd` requires your type to be [`PartialEq`]. /// <del> /// Implementations of [`PartialEq`], `PartialOrd`, and [`Ord`] *must* agree with each other. It's /// easy to accidentally make them disagree by deriving some of the traits and manually /// implementing others. /// </del> /// If your type is [`Ord`], you can implement [`partial_cmp`] by using [`cmp`]: /// /// ```