library/core/src/cmp.rs

   1 //! Functionality for ordering and comparison.
   2 //!
   3 //! This module contains various tools for ordering and comparing values. In
   4 //! summary:
   5 //!
   6 //! * [`Eq`] and [`PartialEq`] are traits that allow you to define total and
   7 //!   partial equality between values, respectively. Implementing them overloads
   8 //!   the `==` and `!=` operators.
   9 //! * [`Ord`] and [`PartialOrd`] are traits that allow you to define total and
  10 //!   partial orderings between values, respectively. Implementing them overloads
  11 //!   the `<`, `<=`, `>`, and `>=` operators.
  12 //! * [`Ordering`] is an enum returned by the main functions of [`Ord`] and
  13 //!   [`PartialOrd`], and describes an ordering.
  14 //! * [`Reverse`] is a struct that allows you to easily reverse an ordering.
  15 //! * [`max`] and [`min`] are functions that build off of [`Ord`] and allow you
  16 //!   to find the maximum or minimum of two values.
  17 //!
  18 //! For more details, see the respective documentation of each item in the list.
  19 //!
  20 //! [`max`]: Ord::max
  21 //! [`min`]: Ord::min
  22
  23 #![stable(feature = "rust1", since = "1.0.0")]
  24
  25 use self::Ordering::*;
  26
  27 /// Trait for equality comparisons which are [partial equivalence
  28 /// relations](https://en.wikipedia.org/wiki/Partial_equivalence_relation).
  29 ///
  30 /// This trait allows for partial equality, for types that do not have a full
  31 /// equivalence relation. For example, in floating point numbers `NaN != NaN`,
  32 /// so floating point types implement `PartialEq` but not [`Eq`](Eq).
  33 ///
  34 /// Formally, the equality must be (for all `a`, `b` and `c`):
  35 ///
  36 /// - symmetric: `a == b` implies `b == a`; and
  37 /// - transitive: `a == b` and `b == c` implies `a == c`.
  38 ///
  39 /// Note that these requirements mean that the trait itself must be implemented
  40 /// symmetrically and transitively: if `T: PartialEq<U>` and `U: PartialEq<V>`
  41 /// then `U: PartialEq<T>` and `T: PartialEq<V>`.
  42 ///
  43 /// ## Derivable
  44 ///
  45 /// This trait can be used with `#[derive]`. When `derive`d on structs, two
  46 /// instances are equal if all fields are equal, and not equal if any fields
  47 /// are not equal. When `derive`d on enums, each variant is equal to itself
  48 /// and not equal to the other variants.
  49 ///
  50 /// ## How can I implement `PartialEq`?
  51 ///
  52 /// `PartialEq` only requires the [`eq`] method to be implemented; [`ne`] is defined
  53 /// in terms of it by default. Any manual implementation of [`ne`] *must* respect
  54 /// the rule that [`eq`] is a strict inverse of [`ne`]; that is, `!(a == b)` if and
  55 /// only if `a != b`.
  56 ///
  57 /// Implementations of `PartialEq`, [`PartialOrd`], and [`Ord`] *must* agree with
  58 /// each other. It's easy to accidentally make them disagree by deriving some
  59 /// of the traits and manually implementing others.
  60 ///
  61 /// An example implementation for a domain in which two books are considered
  62 /// the same book if their ISBN matches, even if the formats differ:
  63 ///
  64 /// ```
  65 /// enum BookFormat {
  66 ///     Paperback,
  67 ///     Hardback,
  68 ///     Ebook,
  69 /// }
  70 ///
  71 /// struct Book {
  72 ///     isbn: i32,
  73 ///     format: BookFormat,
  74 /// }
  75 ///
  76 /// impl PartialEq for Book {
  77 ///     fn eq(&self, other: &Self) -> bool {
  78 ///         self.isbn == other.isbn
  79 ///     }
  80 /// }
  81 ///
  82 /// let b1 = Book { isbn: 3, format: BookFormat::Paperback };
  83 /// let b2 = Book { isbn: 3, format: BookFormat::Ebook };
  84 /// let b3 = Book { isbn: 10, format: BookFormat::Paperback };
  85 ///
  86 /// assert!(b1 == b2);
  87 /// assert!(b1 != b3);
  88 /// ```
  89 ///
  90 /// ## How can I compare two different types?
  91 ///
  92 /// The type you can compare with is controlled by `PartialEq`'s type parameter.
  93 /// For example, let's tweak our previous code a bit:
  94 ///
  95 /// ```
  96 /// // The derive implements <BookFormat> == <BookFormat> comparisons
  97 /// #[derive(PartialEq)]
  98 /// enum BookFormat {
  99 ///     Paperback,
 100 ///     Hardback,
 101 ///     Ebook,
 102 /// }
 103 ///
 104 /// struct Book {
 105 ///     isbn: i32,
 106 ///     format: BookFormat,
 107 /// }
 108 ///
 109 /// // Implement <Book> == <BookFormat> comparisons
 110 /// impl PartialEq<BookFormat> for Book {
 111 ///     fn eq(&self, other: &BookFormat) -> bool {
 112 ///         self.format == *other
 113 ///     }
 114 /// }
 115 ///
 116 /// // Implement <BookFormat> == <Book> comparisons
 117 /// impl PartialEq<Book> for BookFormat {
 118 ///     fn eq(&self, other: &Book) -> bool {
 119 ///         *self == other.format
 120 ///     }
 121 /// }
 122 ///
 123 /// let b1 = Book { isbn: 3, format: BookFormat::Paperback };
 124 ///
 125 /// assert!(b1 == BookFormat::Paperback);
 126 /// assert!(BookFormat::Ebook != b1);
 127 /// ```
 128 ///
 129 /// By changing `impl PartialEq for Book` to `impl PartialEq<BookFormat> for Book`,
 130 /// we allow `BookFormat`s to be compared with `Book`s.
 131 ///
 132 /// A comparison like the one above, which ignores some fields of the struct,
 133 /// can be dangerous. It can easily lead to an unintended violation of the
 134 /// requirements for a partial equivalence relation. For example, if we kept
 135 /// the above implementation of `PartialEq<Book>` for `BookFormat` and added an
 136 /// implementation of `PartialEq<Book>` for `Book` (either via a `#[derive]` or
 137 /// via the manual implementation from the first example) then the result would
 138 /// violate transitivity:
 139 ///
 140 /// ```should_panic
 141 /// #[derive(PartialEq)]
 142 /// enum BookFormat {
 143 ///     Paperback,
 144 ///     Hardback,
 145 ///     Ebook,
 146 /// }
 147 ///
 148 /// #[derive(PartialEq)]
 149 /// struct Book {
 150 ///     isbn: i32,
 151 ///     format: BookFormat,
 152 /// }
 153 ///
 154 /// impl PartialEq<BookFormat> for Book {
 155 ///     fn eq(&self, other: &BookFormat) -> bool {
 156 ///         self.format == *other
 157 ///     }
 158 /// }
 159 ///
 160 /// impl PartialEq<Book> for BookFormat {
 161 ///     fn eq(&self, other: &Book) -> bool {
 162 ///         *self == other.format
 163 ///     }
 164 /// }
 165 ///
 166 /// fn main() {
 167 ///     let b1 = Book { isbn: 1, format: BookFormat::Paperback };
 168 ///     let b2 = Book { isbn: 2, format: BookFormat::Paperback };
 169 ///
 170 ///     assert!(b1 == BookFormat::Paperback);
 171 ///     assert!(BookFormat::Paperback == b2);
 172 ///
 173 ///     // The following should hold by transitivity but doesn't.
 174 ///     assert!(b1 == b2); // <-- PANICS
 175 /// }
 176 /// ```
 177 ///
 178 /// # Examples
 179 ///
 180 /// ```
 181 /// let x: u32 = 0;
 182 /// let y: u32 = 1;
 183 ///
 184 /// assert_eq!(x == y, false);
 185 /// assert_eq!(x.eq(&y), false);
 186 /// ```
 187 ///
 188 /// [`eq`]: PartialEq::eq
 189 /// [`ne`]: PartialEq::ne
 190 #[lang = "eq"]
 191 #[stable(feature = "rust1", since = "1.0.0")]
 192 #[doc(alias = "==")]
 193 #[doc(alias = "!=")]
 194 #[rustc_on_unimplemented(
 195     message = "can't compare `{Self}` with `{Rhs}`",
 196     label = "no implementation for `{Self} == {Rhs}`"
 197 )]
 198 pub trait PartialEq<Rhs: ?Sized = Self> {
 199     /// This method tests for `self` and `other` values to be equal, and is used
 200     /// by `==`.
 201     #[must_use]
 202     #[stable(feature = "rust1", since = "1.0.0")]
 203     fn eq(&self, other: &Rhs) -> bool;
 204
 205     /// This method tests for `!=`.
 206     #[inline]
 207     #[must_use]
 208     #[stable(feature = "rust1", since = "1.0.0")]
 209     fn ne(&self, other: &Rhs) -> bool {
 210         !self.eq(other)
 211     }
 212 }
 213
 214 /// Derive macro generating an impl of the trait `PartialEq`.
 215 #[rustc_builtin_macro]
 216 #[stable(feature = "builtin_macro_prelude", since = "1.38.0")]
 217 #[allow_internal_unstable(core_intrinsics, structural_match)]
 218 pub macro PartialEq($item:item) {
 219     /* compiler built-in */
 220 }
 221
 222 /// Trait for equality comparisons which are [equivalence relations](
 223 /// https://en.wikipedia.org/wiki/Equivalence_relation).
 224 ///
 225 /// This means, that in addition to `a == b` and `a != b` being strict inverses, the equality must
 226 /// be (for all `a`, `b` and `c`):
 227 ///
 228 /// - reflexive: `a == a`;
 229 /// - symmetric: `a == b` implies `b == a`; and
 230 /// - transitive: `a == b` and `b == c` implies `a == c`.
 231 ///
 232 /// This property cannot be checked by the compiler, and therefore `Eq` implies
 233 /// [`PartialEq`], and has no extra methods.
 234 ///
 235 /// ## Derivable
 236 ///
 237 /// This trait can be used with `#[derive]`. When `derive`d, because `Eq` has
 238 /// no extra methods, it is only informing the compiler that this is an
 239 /// equivalence relation rather than a partial equivalence relation. Note that
 240 /// the `derive` strategy requires all fields are `Eq`, which isn't
 241 /// always desired.
 242 ///
 243 /// ## How can I implement `Eq`?
 244 ///
 245 /// If you cannot use the `derive` strategy, specify that your type implements
 246 /// `Eq`, which has no methods:
 247 ///
 248 /// ```
 249 /// enum BookFormat { Paperback, Hardback, Ebook }
 250 /// struct Book {
 251 ///     isbn: i32,
 252 ///     format: BookFormat,
 253 /// }
 254 /// impl PartialEq for Book {
 255 ///     fn eq(&self, other: &Self) -> bool {
 256 ///         self.isbn == other.isbn
 257 ///     }
 258 /// }
 259 /// impl Eq for Book {}
 260 /// ```
 261 #[doc(alias = "==")]
 262 #[doc(alias = "!=")]
 263 #[stable(feature = "rust1", since = "1.0.0")]
 264 pub trait Eq: PartialEq<Self> {
 265     // this method is used solely by #[deriving] to assert
 266     // that every component of a type implements #[deriving]
 267     // itself, the current deriving infrastructure means doing this
 268     // assertion without using a method on this trait is nearly
 269     // impossible.
 270     //
 271     // This should never be implemented by hand.
 272     #[doc(hidden)]
 273     #[inline]
 274     #[stable(feature = "rust1", since = "1.0.0")]
 275     fn assert_receiver_is_total_eq(&self) {}
 276 }
 277
 278 /// Derive macro generating an impl of the trait `Eq`.
 279 #[rustc_builtin_macro]
 280 #[stable(feature = "builtin_macro_prelude", since = "1.38.0")]
 281 #[allow_internal_unstable(core_intrinsics, derive_eq, structural_match)]
 282 pub macro Eq($item:item) {
 283     /* compiler built-in */
 284 }
 285
 286 // FIXME: this struct is used solely by #[derive] to
 287 // assert that every component of a type implements Eq.
 288 //
 289 // This struct should never appear in user code.
 290 #[doc(hidden)]
 291 #[allow(missing_debug_implementations)]
 292 #[unstable(feature = "derive_eq", reason = "deriving hack, should not be public", issue = "none")]
 293 pub struct AssertParamIsEq<T: Eq + ?Sized> {
 294     _field: crate::marker::PhantomData<T>,
 295 }
 296
 297 /// An `Ordering` is the result of a comparison between two values.
 298 ///
 299 /// # Examples
 300 ///
 301 /// ```
 302 /// use std::cmp::Ordering;
 303 ///
 304 /// let result = 1.cmp(&2);
 305 /// assert_eq!(Ordering::Less, result);
 306 ///
 307 /// let result = 1.cmp(&1);
 308 /// assert_eq!(Ordering::Equal, result);
 309 ///
 310 /// let result = 2.cmp(&1);
 311 /// assert_eq!(Ordering::Greater, result);
 312 /// ```
 313 #[derive(Clone, Copy, PartialEq, Debug, Hash)]
 314 #[stable(feature = "rust1", since = "1.0.0")]
 315 pub enum Ordering {
 316     /// An ordering where a compared value is less than another.
 317     #[stable(feature = "rust1", since = "1.0.0")]
 318     Less = -1,
 319     /// An ordering where a compared value is equal to another.
 320     #[stable(feature = "rust1", since = "1.0.0")]
 321     Equal = 0,
 322     /// An ordering where a compared value is greater than another.
 323     #[stable(feature = "rust1", since = "1.0.0")]
 324     Greater = 1,
 325 }
 326
 327 impl Ordering {
 328     /// Reverses the `Ordering`.
 329     ///
 330     /// * `Less` becomes `Greater`.
 331     /// * `Greater` becomes `Less`.
 332     /// * `Equal` becomes `Equal`.
 333     ///
 334     /// # Examples
 335     ///
 336     /// Basic behavior:
 337     ///
 338     /// ```
 339     /// use std::cmp::Ordering;
 340     ///
 341     /// assert_eq!(Ordering::Less.reverse(), Ordering::Greater);
 342     /// assert_eq!(Ordering::Equal.reverse(), Ordering::Equal);
 343     /// assert_eq!(Ordering::Greater.reverse(), Ordering::Less);
 344     /// ```
 345     ///
 346     /// This method can be used to reverse a comparison:
 347     ///
 348     /// ```
 349     /// let data: &mut [_] = &mut [2, 10, 5, 8];
 350     ///
 351     /// // sort the array from largest to smallest.
 352     /// data.sort_by(|a, b| a.cmp(b).reverse());
 353     ///
 354     /// let b: &mut [_] = &mut [10, 8, 5, 2];
 355     /// assert!(data == b);
 356     /// ```
 357     #[inline]
 358     #[must_use]
 359     #[stable(feature = "rust1", since = "1.0.0")]
 360     pub fn reverse(self) -> Ordering {
 361         match self {
 362             Less => Greater,
 363             Equal => Equal,
 364             Greater => Less,
 365         }
 366     }
 367
 368     /// Chains two orderings.
 369     ///
 370     /// Returns `self` when it's not `Equal`. Otherwise returns `other`.
 371     ///
 372     /// # Examples
 373     ///
 374     /// ```
 375     /// use std::cmp::Ordering;
 376     ///
 377     /// let result = Ordering::Equal.then(Ordering::Less);
 378     /// assert_eq!(result, Ordering::Less);
 379     ///
 380     /// let result = Ordering::Less.then(Ordering::Equal);
 381     /// assert_eq!(result, Ordering::Less);
 382     ///
 383     /// let result = Ordering::Less.then(Ordering::Greater);
 384     /// assert_eq!(result, Ordering::Less);
 385     ///
 386     /// let result = Ordering::Equal.then(Ordering::Equal);
 387     /// assert_eq!(result, Ordering::Equal);
 388     ///
 389     /// let x: (i64, i64, i64) = (1, 2, 7);
 390     /// let y: (i64, i64, i64) = (1, 5, 3);
 391     /// let result = x.0.cmp(&y.0).then(x.1.cmp(&y.1)).then(x.2.cmp(&y.2));
 392     ///
 393     /// assert_eq!(result, Ordering::Less);
 394     /// ```
 395     #[inline]
 396     #[must_use]
 397     #[stable(feature = "ordering_chaining", since = "1.17.0")]
 398     pub fn then(self, other: Ordering) -> Ordering {
 399         match self {
 400             Equal => other,
 401             _ => self,
 402         }
 403     }
 404
 405     /// Chains the ordering with the given function.
 406     ///
 407     /// Returns `self` when it's not `Equal`. Otherwise calls `f` and returns
 408     /// the result.
 409     ///
 410     /// # Examples
 411     ///
 412     /// ```
 413     /// use std::cmp::Ordering;
 414     ///
 415     /// let result = Ordering::Equal.then_with(|| Ordering::Less);
 416     /// assert_eq!(result, Ordering::Less);
 417     ///
 418     /// let result = Ordering::Less.then_with(|| Ordering::Equal);
 419     /// assert_eq!(result, Ordering::Less);
 420     ///
 421     /// let result = Ordering::Less.then_with(|| Ordering::Greater);
 422     /// assert_eq!(result, Ordering::Less);
 423     ///
 424     /// let result = Ordering::Equal.then_with(|| Ordering::Equal);
 425     /// assert_eq!(result, Ordering::Equal);
 426     ///
 427     /// let x: (i64, i64, i64) = (1, 2, 7);
 428     /// let y: (i64, i64, i64)  = (1, 5, 3);
 429     /// let result = x.0.cmp(&y.0).then_with(|| x.1.cmp(&y.1)).then_with(|| x.2.cmp(&y.2));
 430     ///
 431     /// assert_eq!(result, Ordering::Less);
 432     /// ```
 433     #[inline]
 434     #[must_use]
 435     #[stable(feature = "ordering_chaining", since = "1.17.0")]
 436     pub fn then_with<F: FnOnce() -> Ordering>(self, f: F) -> Ordering {
 437         match self {
 438             Equal => f(),
 439             _ => self,
 440         }
 441     }
 442 }
 443
 444 /// A helper struct for reverse ordering.
 445 ///
 446 /// This struct is a helper to be used with functions like [`Vec::sort_by_key`] and
 447 /// can be used to reverse order a part of a key.
 448 ///
 449 /// [`Vec::sort_by_key`]: ../../std/vec/struct.Vec.html#method.sort_by_key
 450 ///
 451 /// # Examples
 452 ///
 453 /// ```
 454 /// use std::cmp::Reverse;
 455 ///
 456 /// let mut v = vec![1, 2, 3, 4, 5, 6];
 457 /// v.sort_by_key(|&num| (num > 3, Reverse(num)));
 458 /// assert_eq!(v, vec![3, 2, 1, 6, 5, 4]);
 459 /// ```
 460 #[derive(PartialEq, Eq, Debug, Copy, Clone, Default, Hash)]
 461 #[stable(feature = "reverse_cmp_key", since = "1.19.0")]
 462 pub struct Reverse<T>(#[stable(feature = "reverse_cmp_key", since = "1.19.0")] pub T);
 463
 464 #[stable(feature = "reverse_cmp_key", since = "1.19.0")]
 465 impl<T: PartialOrd> PartialOrd for Reverse<T> {
 466     #[inline]
 467     fn partial_cmp(&self, other: &Reverse<T>) -> Option<Ordering> {
 468         other.0.partial_cmp(&self.0)
 469     }
 470
 471     #[inline]
 472     fn lt(&self, other: &Self) -> bool {
 473         other.0 < self.0
 474     }
 475     #[inline]
 476     fn le(&self, other: &Self) -> bool {
 477         other.0 <= self.0
 478     }
 479     #[inline]
 480     fn gt(&self, other: &Self) -> bool {
 481         other.0 > self.0
 482     }
 483     #[inline]
 484     fn ge(&self, other: &Self) -> bool {
 485         other.0 >= self.0
 486     }
 487 }
 488
 489 #[stable(feature = "reverse_cmp_key", since = "1.19.0")]
 490 impl<T: Ord> Ord for Reverse<T> {
 491     #[inline]
 492     fn cmp(&self, other: &Reverse<T>) -> Ordering {
 493         other.0.cmp(&self.0)
 494     }
 495 }
 496
 497 /// Trait for types that form a [total order](https://en.wikipedia.org/wiki/Total_order).
 498 ///
 499 /// An order is a total order if it is (for all `a`, `b` and `c`):
 500 ///
 501 /// - total and asymmetric: exactly one of `a < b`, `a == b` or `a > b` is true; and
 502 /// - transitive, `a < b` and `b < c` implies `a < c`. The same must hold for both `==` and `>`.
 503 ///
 504 /// ## Derivable
 505 ///
 506 /// This trait can be used with `#[derive]`. When `derive`d on structs, it will produce a
 507 /// lexicographic ordering based on the top-to-bottom declaration order of the struct's members.
 508 /// When `derive`d on enums, variants are ordered by their top-to-bottom discriminant order.
 509 ///
 510 /// ## How can I implement `Ord`?
 511 ///
 512 /// `Ord` requires that the type also be [`PartialOrd`] and [`Eq`] (which requires [`PartialEq`]).
 513 ///
 514 /// Then you must define an implementation for [`cmp`]. You may find it useful to use
 515 /// [`cmp`] on your type's fields.
 516 ///
 517 /// Implementations of [`PartialEq`], [`PartialOrd`], and `Ord` *must*
 518 /// agree with each other. That is, `a.cmp(b) == Ordering::Equal` if
 519 /// and only if `a == b` and `Some(a.cmp(b)) == a.partial_cmp(b)` for
 520 /// all `a` and `b`. It's easy to accidentally make them disagree by
 521 /// deriving some of the traits and manually implementing others.
 522 ///
 523 /// Here's an example where you want to sort people by height only, disregarding `id`
 524 /// and `name`:
 525 ///
 526 /// ```
 527 /// use std::cmp::Ordering;
 528 ///
 529 /// #[derive(Eq)]
 530 /// struct Person {
 531 ///     id: u32,
 532 ///     name: String,
 533 ///     height: u32,
 534 /// }
 535 ///
 536 /// impl Ord for Person {
 537 ///     fn cmp(&self, other: &Self) -> Ordering {
 538 ///         self.height.cmp(&other.height)
 539 ///     }
 540 /// }
 541 ///
 542 /// impl PartialOrd for Person {
 543 ///     fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
 544 ///         Some(self.cmp(other))
 545 ///     }
 546 /// }
 547 ///
 548 /// impl PartialEq for Person {
 549 ///     fn eq(&self, other: &Self) -> bool {
 550 ///         self.height == other.height
 551 ///     }
 552 /// }
 553 /// ```
 554 ///
 555 /// [`cmp`]: Ord::cmp
 556 #[doc(alias = "<")]
 557 #[doc(alias = ">")]
 558 #[doc(alias = "<=")]
 559 #[doc(alias = ">=")]
 560 #[stable(feature = "rust1", since = "1.0.0")]
 561 pub trait Ord: Eq + PartialOrd<Self> {
 562     /// This method returns an [`Ordering`] between `self` and `other`.
 563     ///
 564     /// By convention, `self.cmp(&other)` returns the ordering matching the expression
 565     /// `self <operator> other` if true.
 566     ///
 567     /// # Examples
 568     ///
 569     /// ```
 570     /// use std::cmp::Ordering;
 571     ///
 572     /// assert_eq!(5.cmp(&10), Ordering::Less);
 573     /// assert_eq!(10.cmp(&5), Ordering::Greater);
 574     /// assert_eq!(5.cmp(&5), Ordering::Equal);
 575     /// ```
 576     #[must_use]
 577     #[stable(feature = "rust1", since = "1.0.0")]
 578     fn cmp(&self, other: &Self) -> Ordering;
 579
 580     /// Compares and returns the maximum of two values.
 581     ///
 582     /// Returns the second argument if the comparison determines them to be equal.
 583     ///
 584     /// # Examples
 585     ///
 586     /// ```
 587     /// assert_eq!(2, 1.max(2));
 588     /// assert_eq!(2, 2.max(2));
 589     /// ```
 590     #[stable(feature = "ord_max_min", since = "1.21.0")]
 591     #[inline]
 592     #[must_use]
 593     fn max(self, other: Self) -> Self
 594     where
 595         Self: Sized,
 596     {
 597         max_by(self, other, Ord::cmp)
 598     }
 599
 600     /// Compares and returns the minimum of two values.
 601     ///
 602     /// Returns the first argument if the comparison determines them to be equal.
 603     ///
 604     /// # Examples
 605     ///
 606     /// ```
 607     /// assert_eq!(1, 1.min(2));
 608     /// assert_eq!(2, 2.min(2));
 609     /// ```
 610     #[stable(feature = "ord_max_min", since = "1.21.0")]
 611     #[inline]
 612     #[must_use]
 613     fn min(self, other: Self) -> Self
 614     where
 615         Self: Sized,
 616     {
 617         min_by(self, other, Ord::cmp)
 618     }
 619
 620     /// Restrict a value to a certain interval.
 621     ///
 622     /// Returns `max` if `self` is greater than `max`, and `min` if `self` is
 623     /// less than `min`. Otherwise this returns `self`.
 624     ///
 625     /// # Panics
 626     ///
 627     /// Panics if `min > max`.
 628     ///
 629     /// # Examples
 630     ///
 631     /// ```
 632     /// #![feature(clamp)]
 633     ///
 634     /// assert!((-3).clamp(-2, 1) == -2);
 635     /// assert!(0.clamp(-2, 1) == 0);
 636     /// assert!(2.clamp(-2, 1) == 1);
 637     /// ```
 638     #[must_use]
 639     #[unstable(feature = "clamp", issue = "44095")]
 640     fn clamp(self, min: Self, max: Self) -> Self
 641     where
 642         Self: Sized,
 643     {
 644         assert!(min <= max);
 645         if self < min {
 646             min
 647         } else if self > max {
 648             max
 649         } else {
 650             self
 651         }
 652     }
 653 }
 654
 655 /// Derive macro generating an impl of the trait `Ord`.
 656 #[rustc_builtin_macro]
 657 #[stable(feature = "builtin_macro_prelude", since = "1.38.0")]
 658 #[allow_internal_unstable(core_intrinsics)]
 659 pub macro Ord($item:item) {
 660     /* compiler built-in */
 661 }
 662
 663 #[stable(feature = "rust1", since = "1.0.0")]
 664 impl Eq for Ordering {}
 665
 666 #[stable(feature = "rust1", since = "1.0.0")]
 667 impl Ord for Ordering {
 668     #[inline]
 669     fn cmp(&self, other: &Ordering) -> Ordering {
 670         (*self as i32).cmp(&(*other as i32))
 671     }
 672 }
 673
 674 #[stable(feature = "rust1", since = "1.0.0")]
 675 impl PartialOrd for Ordering {
 676     #[inline]
 677     fn partial_cmp(&self, other: &Ordering) -> Option<Ordering> {
 678         (*self as i32).partial_cmp(&(*other as i32))
 679     }
 680 }
 681
 682 /// Trait for values that can be compared for a sort-order.
 683 ///
 684 /// The comparison must satisfy, for all `a`, `b` and `c`:
 685 ///
 686 /// - asymmetry: if `a < b` then `!(a > b)`, as well as `a > b` implying `!(a < b)`; and
 687 /// - transitivity: `a < b` and `b < c` implies `a < c`. The same must hold for both `==` and `>`.
 688 ///
 689 /// Note that these requirements mean that the trait itself must be implemented symmetrically and
 690 /// transitively: if `T: PartialOrd<U>` and `U: PartialOrd<V>` then `U: PartialOrd<T>` and `T:
 691 /// PartialOrd<V>`.
 692 ///
 693 /// ## Derivable
 694 ///
 695 /// This trait can be used with `#[derive]`. When `derive`d on structs, it will produce a
 696 /// lexicographic ordering based on the top-to-bottom declaration order of the struct's members.
 697 /// When `derive`d on enums, variants are ordered by their top-to-bottom discriminant order.
 698 ///
 699 /// ## How can I implement `PartialOrd`?
 700 ///
 701 /// `PartialOrd` only requires implementation of the [`partial_cmp`] method, with the others
 702 /// generated from default implementations.
 703 ///
 704 /// However it remains possible to implement the others separately for types which do not have a
 705 /// total order. For example, for floating point numbers, `NaN < 0 == false` and `NaN >= 0 ==
 706 /// false` (cf. IEEE 754-2008 section 5.11).
 707 ///
 708 /// `PartialOrd` requires your type to be [`PartialEq`].
 709 ///
 710 /// Implementations of [`PartialEq`], `PartialOrd`, and [`Ord`] *must* agree with each other. It's
 711 /// easy to accidentally make them disagree by deriving some of the traits and manually
 712 /// implementing others.
 713 ///
 714 /// If your type is [`Ord`], you can implement [`partial_cmp`] by using [`cmp`]:
 715 ///
 716 /// ```
 717 /// use std::cmp::Ordering;
 718 ///
 719 /// #[derive(Eq)]
 720 /// struct Person {
 721 ///     id: u32,
 722 ///     name: String,
 723 ///     height: u32,
 724 /// }
 725 ///
 726 /// impl PartialOrd for Person {
 727 ///     fn partial_cmp(&self, other: &Person) -> Option<Ordering> {
 728 ///         Some(self.cmp(other))
 729 ///     }
 730 /// }
 731 ///
 732 /// impl Ord for Person {
 733 ///     fn cmp(&self, other: &Person) -> Ordering {
 734 ///         self.height.cmp(&other.height)
 735 ///     }
 736 /// }
 737 ///
 738 /// impl PartialEq for Person {
 739 ///     fn eq(&self, other: &Person) -> bool {
 740 ///         self.height == other.height
 741 ///     }
 742 /// }
 743 /// ```
 744 ///
 745 /// You may also find it useful to use [`partial_cmp`] on your type's fields. Here
 746 /// is an example of `Person` types who have a floating-point `height` field that
 747 /// is the only field to be used for sorting:
 748 ///
 749 /// ```
 750 /// use std::cmp::Ordering;
 751 ///
 752 /// struct Person {
 753 ///     id: u32,
 754 ///     name: String,
 755 ///     height: f64,
 756 /// }
 757 ///
 758 /// impl PartialOrd for Person {
 759 ///     fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
 760 ///         self.height.partial_cmp(&other.height)
 761 ///     }
 762 /// }
 763 ///
 764 /// impl PartialEq for Person {
 765 ///     fn eq(&self, other: &Self) -> bool {
 766 ///         self.height == other.height
 767 ///     }
 768 /// }
 769 /// ```
 770 ///
 771 /// # Examples
 772 ///
 773 /// ```
 774 /// let x : u32 = 0;
 775 /// let y : u32 = 1;
 776 ///
 777 /// assert_eq!(x < y, true);
 778 /// assert_eq!(x.lt(&y), true);
 779 /// ```
 780 ///
 781 /// [`partial_cmp`]: PartialOrd::partial_cmp
 782 /// [`cmp`]: Ord::cmp
 783 #[lang = "partial_ord"]
 784 #[stable(feature = "rust1", since = "1.0.0")]
 785 #[doc(alias = ">")]
 786 #[doc(alias = "<")]
 787 #[doc(alias = "<=")]
 788 #[doc(alias = ">=")]
 789 #[rustc_on_unimplemented(
 790     message = "can't compare `{Self}` with `{Rhs}`",
 791     label = "no implementation for `{Self} < {Rhs}` and `{Self} > {Rhs}`"
 792 )]
 793 pub trait PartialOrd<Rhs: ?Sized = Self>: PartialEq<Rhs> {
 794     /// This method returns an ordering between `self` and `other` values if one exists.
 795     ///
 796     /// # Examples
 797     ///
 798     /// ```
 799     /// use std::cmp::Ordering;
 800     ///
 801     /// let result = 1.0.partial_cmp(&2.0);
 802     /// assert_eq!(result, Some(Ordering::Less));
 803     ///
 804     /// let result = 1.0.partial_cmp(&1.0);
 805     /// assert_eq!(result, Some(Ordering::Equal));
 806     ///
 807     /// let result = 2.0.partial_cmp(&1.0);
 808     /// assert_eq!(result, Some(Ordering::Greater));
 809     /// ```
 810     ///
 811     /// When comparison is impossible:
 812     ///
 813     /// ```
 814     /// let result = f64::NAN.partial_cmp(&1.0);
 815     /// assert_eq!(result, None);
 816     /// ```
 817     #[must_use]
 818     #[stable(feature = "rust1", since = "1.0.0")]
 819     fn partial_cmp(&self, other: &Rhs) -> Option<Ordering>;
 820
 821     /// This method tests less than (for `self` and `other`) and is used by the `<` operator.
 822     ///
 823     /// # Examples
 824     ///
 825     /// ```
 826     /// let result = 1.0 < 2.0;
 827     /// assert_eq!(result, true);
 828     ///
 829     /// let result = 2.0 < 1.0;
 830     /// assert_eq!(result, false);
 831     /// ```
 832     #[inline]
 833     #[must_use]
 834     #[stable(feature = "rust1", since = "1.0.0")]
 835     fn lt(&self, other: &Rhs) -> bool {
 836         matches!(self.partial_cmp(other), Some(Less))
 837     }
 838
 839     /// This method tests less than or equal to (for `self` and `other`) and is used by the `<=`
 840     /// operator.
 841     ///
 842     /// # Examples
 843     ///
 844     /// ```
 845     /// let result = 1.0 <= 2.0;
 846     /// assert_eq!(result, true);
 847     ///
 848     /// let result = 2.0 <= 2.0;
 849     /// assert_eq!(result, true);
 850     /// ```
 851     #[inline]
 852     #[must_use]
 853     #[stable(feature = "rust1", since = "1.0.0")]
 854     fn le(&self, other: &Rhs) -> bool {
 855         matches!(self.partial_cmp(other), Some(Less | Equal))
 856     }
 857
 858     /// This method tests greater than (for `self` and `other`) and is used by the `>` operator.
 859     ///
 860     /// # Examples
 861     ///
 862     /// ```
 863     /// let result = 1.0 > 2.0;
 864     /// assert_eq!(result, false);
 865     ///
 866     /// let result = 2.0 > 2.0;
 867     /// assert_eq!(result, false);
 868     /// ```
 869     #[inline]
 870     #[must_use]
 871     #[stable(feature = "rust1", since = "1.0.0")]
 872     fn gt(&self, other: &Rhs) -> bool {
 873         matches!(self.partial_cmp(other), Some(Greater))
 874     }
 875
 876     /// This method tests greater than or equal to (for `self` and `other`) and is used by the `>=`
 877     /// operator.
 878     ///
 879     /// # Examples
 880     ///
 881     /// ```
 882     /// let result = 2.0 >= 1.0;
 883     /// assert_eq!(result, true);
 884     ///
 885     /// let result = 2.0 >= 2.0;
 886     /// assert_eq!(result, true);
 887     /// ```
 888     #[inline]
 889     #[must_use]
 890     #[stable(feature = "rust1", since = "1.0.0")]
 891     fn ge(&self, other: &Rhs) -> bool {
 892         matches!(self.partial_cmp(other), Some(Greater | Equal))
 893     }
 894 }
 895
 896 /// Derive macro generating an impl of the trait `PartialOrd`.
 897 #[rustc_builtin_macro]
 898 #[stable(feature = "builtin_macro_prelude", since = "1.38.0")]
 899 #[allow_internal_unstable(core_intrinsics)]
 900 pub macro PartialOrd($item:item) {
 901     /* compiler built-in */
 902 }
 903
 904 /// Compares and returns the minimum of two values.
 905 ///
 906 /// Returns the first argument if the comparison determines them to be equal.
 907 ///
 908 /// Internally uses an alias to [`Ord::min`].
 909 ///
 910 /// # Examples
 911 ///
 912 /// ```
 913 /// use std::cmp;
 914 ///
 915 /// assert_eq!(1, cmp::min(1, 2));
 916 /// assert_eq!(2, cmp::min(2, 2));
 917 /// ```
 918 #[inline]
 919 #[must_use]
 920 #[stable(feature = "rust1", since = "1.0.0")]
 921 pub fn min<T: Ord>(v1: T, v2: T) -> T {
 922     v1.min(v2)
 923 }
 924
 925 /// Returns the minimum of two values with respect to the specified comparison function.
 926 ///
 927 /// Returns the first argument if the comparison determines them to be equal.
 928 ///
 929 /// # Examples
 930 ///
 931 /// ```
 932 /// #![feature(cmp_min_max_by)]
 933 ///
 934 /// use std::cmp;
 935 ///
 936 /// assert_eq!(cmp::min_by(-2, 1, |x: &i32, y: &i32| x.abs().cmp(&y.abs())), 1);
 937 /// assert_eq!(cmp::min_by(-2, 2, |x: &i32, y: &i32| x.abs().cmp(&y.abs())), -2);
 938 /// ```
 939 #[inline]
 940 #[must_use]
 941 #[unstable(feature = "cmp_min_max_by", issue = "64460")]
 942 pub fn min_by<T, F: FnOnce(&T, &T) -> Ordering>(v1: T, v2: T, compare: F) -> T {
 943     match compare(&v1, &v2) {
 944         Ordering::Less | Ordering::Equal => v1,
 945         Ordering::Greater => v2,
 946     }
 947 }
 948
 949 /// Returns the element that gives the minimum value from the specified function.
 950 ///
 951 /// Returns the first argument if the comparison determines them to be equal.
 952 ///
 953 /// # Examples
 954 ///
 955 /// ```
 956 /// #![feature(cmp_min_max_by)]
 957 ///
 958 /// use std::cmp;
 959 ///
 960 /// assert_eq!(cmp::min_by_key(-2, 1, |x: &i32| x.abs()), 1);
 961 /// assert_eq!(cmp::min_by_key(-2, 2, |x: &i32| x.abs()), -2);
 962 /// ```
 963 #[inline]
 964 #[must_use]
 965 #[unstable(feature = "cmp_min_max_by", issue = "64460")]
 966 pub fn min_by_key<T, F: FnMut(&T) -> K, K: Ord>(v1: T, v2: T, mut f: F) -> T {
 967     min_by(v1, v2, |v1, v2| f(v1).cmp(&f(v2)))
 968 }
 969
 970 /// Compares and returns the maximum of two values.
 971 ///
 972 /// Returns the second argument if the comparison determines them to be equal.
 973 ///
 974 /// Internally uses an alias to [`Ord::max`].
 975 ///
 976 /// # Examples
 977 ///
 978 /// ```
 979 /// use std::cmp;
 980 ///
 981 /// assert_eq!(2, cmp::max(1, 2));
 982 /// assert_eq!(2, cmp::max(2, 2));
 983 /// ```
 984 #[inline]
 985 #[must_use]
 986 #[stable(feature = "rust1", since = "1.0.0")]
 987 pub fn max<T: Ord>(v1: T, v2: T) -> T {
 988     v1.max(v2)
 989 }
 990
 991 /// Returns the maximum of two values with respect to the specified comparison function.
 992 ///
 993 /// Returns the second argument if the comparison determines them to be equal.
 994 ///
 995 /// # Examples
 996 ///
 997 /// ```
 998 /// #![feature(cmp_min_max_by)]
 999 ///
1000 /// use std::cmp;
1001 ///
1002 /// assert_eq!(cmp::max_by(-2, 1, |x: &i32, y: &i32| x.abs().cmp(&y.abs())), -2);
1003 /// assert_eq!(cmp::max_by(-2, 2, |x: &i32, y: &i32| x.abs().cmp(&y.abs())), 2);
1004 /// ```
1005 #[inline]
1006 #[must_use]
1007 #[unstable(feature = "cmp_min_max_by", issue = "64460")]
1008 pub fn max_by<T, F: FnOnce(&T, &T) -> Ordering>(v1: T, v2: T, compare: F) -> T {
1009     match compare(&v1, &v2) {
1010         Ordering::Less | Ordering::Equal => v2,
1011         Ordering::Greater => v1,
1012     }
1013 }
1014
1015 /// Returns the element that gives the maximum value from the specified function.
1016 ///
1017 /// Returns the second argument if the comparison determines them to be equal.
1018 ///
1019 /// # Examples
1020 ///
1021 /// ```
1022 /// #![feature(cmp_min_max_by)]
1023 ///
1024 /// use std::cmp;
1025 ///
1026 /// assert_eq!(cmp::max_by_key(-2, 1, |x: &i32| x.abs()), -2);
1027 /// assert_eq!(cmp::max_by_key(-2, 2, |x: &i32| x.abs()), 2);
1028 /// ```
1029 #[inline]
1030 #[must_use]
1031 #[unstable(feature = "cmp_min_max_by", issue = "64460")]
1032 pub fn max_by_key<T, F: FnMut(&T) -> K, K: Ord>(v1: T, v2: T, mut f: F) -> T {
1033     max_by(v1, v2, |v1, v2| f(v1).cmp(&f(v2)))
1034 }
1035
1036 // Implementation of PartialEq, Eq, PartialOrd and Ord for primitive types
1037 mod impls {
1038     use crate::cmp::Ordering::{self, Equal, Greater, Less};
1039     use crate::hint::unreachable_unchecked;
1040
1041     macro_rules! partial_eq_impl {
1042         ($($t:ty)*) => ($(
1043             #[stable(feature = "rust1", since = "1.0.0")]
1044             impl PartialEq for $t {
1045                 #[inline]
1046                 fn eq(&self, other: &$t) -> bool { (*self) == (*other) }
1047                 #[inline]
1048                 fn ne(&self, other: &$t) -> bool { (*self) != (*other) }
1049             }
1050         )*)
1051     }
1052
1053     #[stable(feature = "rust1", since = "1.0.0")]
1054     impl PartialEq for () {
1055         #[inline]
1056         fn eq(&self, _other: &()) -> bool {
1057             true
1058         }
1059         #[inline]
1060         fn ne(&self, _other: &()) -> bool {
1061             false
1062         }
1063     }
1064
1065     partial_eq_impl! {
1066         bool char usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f32 f64
1067     }
1068
1069     macro_rules! eq_impl {
1070         ($($t:ty)*) => ($(
1071             #[stable(feature = "rust1", since = "1.0.0")]
1072             impl Eq for $t {}
1073         )*)
1074     }
1075
1076     eq_impl! { () bool char usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 }
1077
1078     macro_rules! partial_ord_impl {
1079         ($($t:ty)*) => ($(
1080             #[stable(feature = "rust1", since = "1.0.0")]
1081             impl PartialOrd for $t {
1082                 #[inline]
1083                 fn partial_cmp(&self, other: &$t) -> Option<Ordering> {
1084                     match (self <= other, self >= other) {
1085                         (false, false) => None,
1086                         (false, true) => Some(Greater),
1087                         (true, false) => Some(Less),
1088                         (true, true) => Some(Equal),
1089                     }
1090                 }
1091                 #[inline]
1092                 fn lt(&self, other: &$t) -> bool { (*self) < (*other) }
1093                 #[inline]
1094                 fn le(&self, other: &$t) -> bool { (*self) <= (*other) }
1095                 #[inline]
1096                 fn ge(&self, other: &$t) -> bool { (*self) >= (*other) }
1097                 #[inline]
1098                 fn gt(&self, other: &$t) -> bool { (*self) > (*other) }
1099             }
1100         )*)
1101     }
1102
1103     #[stable(feature = "rust1", since = "1.0.0")]
1104     impl PartialOrd for () {
1105         #[inline]
1106         fn partial_cmp(&self, _: &()) -> Option<Ordering> {
1107             Some(Equal)
1108         }
1109     }
1110
1111     #[stable(feature = "rust1", since = "1.0.0")]
1112     impl PartialOrd for bool {
1113         #[inline]
1114         fn partial_cmp(&self, other: &bool) -> Option<Ordering> {
1115             (*self as u8).partial_cmp(&(*other as u8))
1116         }
1117     }
1118
1119     partial_ord_impl! { f32 f64 }
1120
1121     macro_rules! ord_impl {
1122         ($($t:ty)*) => ($(
1123             #[stable(feature = "rust1", since = "1.0.0")]
1124             impl PartialOrd for $t {
1125                 #[inline]
1126                 fn partial_cmp(&self, other: &$t) -> Option<Ordering> {
1127                     Some(self.cmp(other))
1128                 }
1129                 #[inline]
1130                 fn lt(&self, other: &$t) -> bool { (*self) < (*other) }
1131                 #[inline]
1132                 fn le(&self, other: &$t) -> bool { (*self) <= (*other) }
1133                 #[inline]
1134                 fn ge(&self, other: &$t) -> bool { (*self) >= (*other) }
1135                 #[inline]
1136                 fn gt(&self, other: &$t) -> bool { (*self) > (*other) }
1137             }
1138
1139             #[stable(feature = "rust1", since = "1.0.0")]
1140             impl Ord for $t {
1141                 #[inline]
1142                 fn cmp(&self, other: &$t) -> Ordering {
1143                     // The order here is important to generate more optimal assembly.
1144                     // See <https://github.com/rust-lang/rust/issues/63758> for more info.
1145                     if *self < *other { Less }
1146                     else if *self == *other { Equal }
1147                     else { Greater }
1148                 }
1149             }
1150         )*)
1151     }
1152
1153     #[stable(feature = "rust1", since = "1.0.0")]
1154     impl Ord for () {
1155         #[inline]
1156         fn cmp(&self, _other: &()) -> Ordering {
1157             Equal
1158         }
1159     }
1160
1161     #[stable(feature = "rust1", since = "1.0.0")]
1162     impl Ord for bool {
1163         #[inline]
1164         fn cmp(&self, other: &bool) -> Ordering {
1165             // Casting to i8's and converting the difference to an Ordering generates
1166             // more optimal assembly.
1167             // See <https://github.com/rust-lang/rust/issues/66780> for more info.
1168             match (*self as i8) - (*other as i8) {
1169                 -1 => Less,
1170                 0 => Equal,
1171                 1 => Greater,
1172                 // SAFETY: bool as i8 returns 0 or 1, so the difference can't be anything else
1173                 _ => unsafe { unreachable_unchecked() },
1174             }
1175         }
1176     }
1177
1178     ord_impl! { char usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 }
1179
1180     #[unstable(feature = "never_type", issue = "35121")]
1181     impl PartialEq for ! {
1182         fn eq(&self, _: &!) -> bool {
1183             *self
1184         }
1185     }
1186
1187     #[unstable(feature = "never_type", issue = "35121")]
1188     impl Eq for ! {}
1189
1190     #[unstable(feature = "never_type", issue = "35121")]
1191     impl PartialOrd for ! {
1192         fn partial_cmp(&self, _: &!) -> Option<Ordering> {
1193             *self
1194         }
1195     }
1196
1197     #[unstable(feature = "never_type", issue = "35121")]
1198     impl Ord for ! {
1199         fn cmp(&self, _: &!) -> Ordering {
1200             *self
1201         }
1202     }
1203
1204     // & pointers
1205
1206     #[stable(feature = "rust1", since = "1.0.0")]
1207     impl<A: ?Sized, B: ?Sized> PartialEq<&B> for &A
1208     where
1209         A: PartialEq<B>,
1210     {
1211         #[inline]
1212         fn eq(&self, other: &&B) -> bool {
1213             PartialEq::eq(*self, *other)
1214         }
1215         #[inline]
1216         fn ne(&self, other: &&B) -> bool {
1217             PartialEq::ne(*self, *other)
1218         }
1219     }
1220     #[stable(feature = "rust1", since = "1.0.0")]
1221     impl<A: ?Sized, B: ?Sized> PartialOrd<&B> for &A
1222     where
1223         A: PartialOrd<B>,
1224     {
1225         #[inline]
1226         fn partial_cmp(&self, other: &&B) -> Option<Ordering> {
1227             PartialOrd::partial_cmp(*self, *other)
1228         }
1229         #[inline]
1230         fn lt(&self, other: &&B) -> bool {
1231             PartialOrd::lt(*self, *other)
1232         }
1233         #[inline]
1234         fn le(&self, other: &&B) -> bool {
1235             PartialOrd::le(*self, *other)
1236         }
1237         #[inline]
1238         fn gt(&self, other: &&B) -> bool {
1239             PartialOrd::gt(*self, *other)
1240         }
1241         #[inline]
1242         fn ge(&self, other: &&B) -> bool {
1243             PartialOrd::ge(*self, *other)
1244         }
1245     }
1246     #[stable(feature = "rust1", since = "1.0.0")]
1247     impl<A: ?Sized> Ord for &A
1248     where
1249         A: Ord,
1250     {
1251         #[inline]
1252         fn cmp(&self, other: &Self) -> Ordering {
1253             Ord::cmp(*self, *other)
1254         }
1255     }
1256     #[stable(feature = "rust1", since = "1.0.0")]
1257     impl<A: ?Sized> Eq for &A where A: Eq {}
1258
1259     // &mut pointers
1260
1261     #[stable(feature = "rust1", since = "1.0.0")]
1262     impl<A: ?Sized, B: ?Sized> PartialEq<&mut B> for &mut A
1263     where
1264         A: PartialEq<B>,
1265     {
1266         #[inline]
1267         fn eq(&self, other: &&mut B) -> bool {
1268             PartialEq::eq(*self, *other)
1269         }
1270         #[inline]
1271         fn ne(&self, other: &&mut B) -> bool {
1272             PartialEq::ne(*self, *other)
1273         }
1274     }
1275     #[stable(feature = "rust1", since = "1.0.0")]
1276     impl<A: ?Sized, B: ?Sized> PartialOrd<&mut B> for &mut A
1277     where
1278         A: PartialOrd<B>,
1279     {
1280         #[inline]
1281         fn partial_cmp(&self, other: &&mut B) -> Option<Ordering> {
1282             PartialOrd::partial_cmp(*self, *other)
1283         }
1284         #[inline]
1285         fn lt(&self, other: &&mut B) -> bool {
1286             PartialOrd::lt(*self, *other)
1287         }
1288         #[inline]
1289         fn le(&self, other: &&mut B) -> bool {
1290             PartialOrd::le(*self, *other)
1291         }
1292         #[inline]
1293         fn gt(&self, other: &&mut B) -> bool {
1294             PartialOrd::gt(*self, *other)
1295         }
1296         #[inline]
1297         fn ge(&self, other: &&mut B) -> bool {
1298             PartialOrd::ge(*self, *other)
1299         }
1300     }
1301     #[stable(feature = "rust1", since = "1.0.0")]
1302     impl<A: ?Sized> Ord for &mut A
1303     where
1304         A: Ord,
1305     {
1306         #[inline]
1307         fn cmp(&self, other: &Self) -> Ordering {
1308             Ord::cmp(*self, *other)
1309         }
1310     }
1311     #[stable(feature = "rust1", since = "1.0.0")]
1312     impl<A: ?Sized> Eq for &mut A where A: Eq {}
1313
1314     #[stable(feature = "rust1", since = "1.0.0")]
1315     impl<A: ?Sized, B: ?Sized> PartialEq<&mut B> for &A
1316     where
1317         A: PartialEq<B>,
1318     {
1319         #[inline]
1320         fn eq(&self, other: &&mut B) -> bool {
1321             PartialEq::eq(*self, *other)
1322         }
1323         #[inline]
1324         fn ne(&self, other: &&mut B) -> bool {
1325             PartialEq::ne(*self, *other)
1326         }
1327     }
1328
1329     #[stable(feature = "rust1", since = "1.0.0")]
1330     impl<A: ?Sized, B: ?Sized> PartialEq<&B> for &mut A
1331     where
1332         A: PartialEq<B>,
1333     {
1334         #[inline]
1335         fn eq(&self, other: &&B) -> bool {
1336             PartialEq::eq(*self, *other)
1337         }
1338         #[inline]
1339         fn ne(&self, other: &&B) -> bool {
1340             PartialEq::ne(*self, *other)
1341         }
1342     }
1343 }