diff options
| -rw-r--r-- | library/core/src/cmp.rs | 29 |
1 files changed, 16 insertions, 13 deletions
diff --git a/library/core/src/cmp.rs b/library/core/src/cmp.rs index 185b0fb9de7..7a3f40fdf1e 100644 --- a/library/core/src/cmp.rs +++ b/library/core/src/cmp.rs @@ -278,7 +278,7 @@ pub macro PartialEq($item:item) { /// The primary difference to [`PartialEq`] is the additional requirement for reflexivity. A type /// that implements [`PartialEq`] guarantees that for all `a`, `b` and `c`: /// -/// - symmetric: `a == b` implies `b == a` +/// - symmetric: `a == b` implies `b == a` and `a != b` implies `!(a == b)` /// - transitive: `a == b` and `b == c` implies `a == c` /// /// `Eq`, which builds on top of [`PartialEq`] also implies: @@ -332,11 +332,9 @@ pub macro PartialEq($item:item) { #[stable(feature = "rust1", since = "1.0.0")] #[rustc_diagnostic_item = "Eq"] pub trait Eq: PartialEq<Self> { - // this method is used solely by #[derive(Eq)] to assert - // that every component of a type implements `Eq` - // itself. The current deriving infrastructure means doing this - // assertion without using a method on this trait is nearly - // impossible. + // this method is used solely by `impl Eq or #[derive(Eq)]` to assert that every component of a + // type implements `Eq` itself. The current deriving infrastructure means doing this assertion + // without using a method on this trait is nearly impossible. // // This should never be implemented by hand. #[doc(hidden)] @@ -789,11 +787,13 @@ impl<T: Clone> Clone for Reverse<T> { /// fashion `Ord` builds on top of [`PartialOrd`] and adds further properties, such as totality, /// which means all values must be comparable. /// -/// Because of different signatures, `Ord` cannot be a simple marker trait like `Eq`. So it can't be -/// `derive`d automatically when `PartialOrd` is implemented. The recommended best practice for a -/// type that manually implements `Ord` is to implement the equality comparison logic in `PartialEq` -/// and implement the ordering comparison logic in `Ord`. From there one should implement -/// `PartialOrd` as `Some(self.cmp(other))`. +/// `Ord` requires that the type also be PartialOrd, PartialEq, and Eq. +/// +/// Because `Ord` implies a stronger ordering relationship than [`PartialOrd`], and both `Ord` and +/// [`PartialOrd`] must agree, you must choose how to implement `Ord` **first**. You can choose to +/// derive it, or implement it manually. If you derive it, you should derive all four traits. If you +/// implement it manually, you should manually implement all four traits, based on the +/// implementation of `Ord`. /// /// Here's an example where you want to define the `Character` comparison by `health` and /// `experience` only, disregarding the field `mana`: @@ -888,7 +888,7 @@ impl<T: Clone> Clone for Reverse<T> { /// ``` /// use std::cmp::Ordering; /// -/// #[derive(Eq, Debug)] +/// #[derive(Debug)] /// struct Character { /// health: u32, /// experience: u32, @@ -918,6 +918,8 @@ impl<T: Clone> Clone for Reverse<T> { /// } /// } /// +/// impl Eq for Character {} +/// /// let a = Character { /// health: 3, /// experience: 5, @@ -1191,7 +1193,6 @@ pub macro Ord($item:item) { /// ``` /// use std::cmp::Ordering; /// -/// #[derive(Eq)] /// struct Person { /// id: u32, /// name: String, @@ -1215,6 +1216,8 @@ pub macro Ord($item:item) { /// self.height == other.height /// } /// } +/// +/// impl Eq for Person {} /// ``` /// /// You may also find it useful to use [`partial_cmp`] on your type's fields. Here is an example of |