src/libcore/cmp.rs

   1 // Copyright 2012-2014 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11 //! Functionality for ordering and comparison.
  12 //!
  13 //! This module defines both [`PartialOrd`] and [`PartialEq`] traits which are used
  14 //! by the compiler to implement comparison operators. Rust programs may
  15 //! implement [`PartialOrd`] to overload the `<`, `<=`, `>`, and `>=` operators,
  16 //! and may implement [`PartialEq`] to overload the `==` and `!=` operators.
  17 //!
  18 //! [`PartialOrd`]: trait.PartialOrd.html
  19 //! [`PartialEq`]: trait.PartialEq.html
  20 //!
  21 //! # Examples
  22 //!
  23 //! ```
  24 //! let x: u32 = 0;
  25 //! let y: u32 = 1;
  26 //!
  27 //! // these two lines are equivalent
  28 //! assert_eq!(x < y, true);
  29 //! assert_eq!(x.lt(&y), true);
  30 //!
  31 //! // these two lines are also equivalent
  32 //! assert_eq!(x == y, false);
  33 //! assert_eq!(x.eq(&y), false);
  34 //! ```
  35
  36 #![stable(feature = "rust1", since = "1.0.0")]
  37
  38 use self::Ordering::*;
  39
  40 /// Trait for equality comparisons which are [partial equivalence
  41 /// relations](http://en.wikipedia.org/wiki/Partial_equivalence_relation).
  42 ///
  43 /// This trait allows for partial equality, for types that do not have a full
  44 /// equivalence relation.  For example, in floating point numbers `NaN != NaN`,
  45 /// so floating point types implement `PartialEq` but not `Eq`.
  46 ///
  47 /// Formally, the equality must be (for all `a`, `b` and `c`):
  48 ///
  49 /// - symmetric: `a == b` implies `b == a`; and
  50 /// - transitive: `a == b` and `b == c` implies `a == c`.
  51 ///
  52 /// Note that these requirements mean that the trait itself must be implemented
  53 /// symmetrically and transitively: if `T: PartialEq<U>` and `U: PartialEq<V>`
  54 /// then `U: PartialEq<T>` and `T: PartialEq<V>`.
  55 ///
  56 /// ## Derivable
  57 ///
  58 /// This trait can be used with `#[derive]`. When `derive`d on structs, two
  59 /// instances are equal if all fields are equal, and not equal if any fields
  60 /// are not equal. When `derive`d on enums, each variant is equal to itself
  61 /// and not equal to the other variants.
  62 ///
  63 /// ## How can I implement `PartialEq`?
  64 ///
  65 /// PartialEq only requires the `eq` method to be implemented; `ne` is defined
  66 /// in terms of it by default. Any manual implementation of `ne` *must* respect
  67 /// the rule that `eq` is a strict inverse of `ne`; that is, `!(a == b)` if and
  68 /// only if `a != b`.
  69 ///
  70 /// An example implementation for a domain in which two books are considered
  71 /// the same book if their ISBN matches, even if the formats differ:
  72 ///
  73 /// ```
  74 /// enum BookFormat { Paperback, Hardback, Ebook }
  75 /// struct Book {
  76 ///     isbn: i32,
  77 ///     format: BookFormat,
  78 /// }
  79 ///
  80 /// impl PartialEq for Book {
  81 ///     fn eq(&self, other: &Book) -> bool {
  82 ///         self.isbn == other.isbn
  83 ///     }
  84 /// }
  85 ///
  86 /// let b1 = Book { isbn: 3, format: BookFormat::Paperback };
  87 /// let b2 = Book { isbn: 3, format: BookFormat::Ebook };
  88 /// let b3 = Book { isbn: 10, format: BookFormat::Paperback };
  89 ///
  90 /// assert!(b1 == b2);
  91 /// assert!(b1 != b3);
  92 /// ```
  93 ///
  94 /// # Examples
  95 ///
  96 /// ```
  97 /// let x: u32 = 0;
  98 /// let y: u32 = 1;
  99 ///
 100 /// assert_eq!(x == y, false);
 101 /// assert_eq!(x.eq(&y), false);
 102 /// ```
 103 #[lang = "eq"]
 104 #[stable(feature = "rust1", since = "1.0.0")]
 105 pub trait PartialEq<Rhs: ?Sized = Self> {
 106     /// This method tests for `self` and `other` values to be equal, and is used
 107     /// by `==`.
 108     #[stable(feature = "rust1", since = "1.0.0")]
 109     fn eq(&self, other: &Rhs) -> bool;
 110
 111     /// This method tests for `!=`.
 112     #[inline]
 113     #[stable(feature = "rust1", since = "1.0.0")]
 114     fn ne(&self, other: &Rhs) -> bool { !self.eq(other) }
 115 }
 116
 117 /// Trait for equality comparisons which are [equivalence relations](
 118 /// https://en.wikipedia.org/wiki/Equivalence_relation).
 119 ///
 120 /// This means, that in addition to `a == b` and `a != b` being strict inverses, the equality must
 121 /// be (for all `a`, `b` and `c`):
 122 ///
 123 /// - reflexive: `a == a`;
 124 /// - symmetric: `a == b` implies `b == a`; and
 125 /// - transitive: `a == b` and `b == c` implies `a == c`.
 126 ///
 127 /// This property cannot be checked by the compiler, and therefore `Eq` implies
 128 /// `PartialEq`, and has no extra methods.
 129 ///
 130 /// ## Derivable
 131 ///
 132 /// This trait can be used with `#[derive]`. When `derive`d, because `Eq` has
 133 /// no extra methods, it is only informing the compiler that this is an
 134 /// equivalence relation rather than a partial equivalence relation. Note that
 135 /// the `derive` strategy requires all fields are `Eq`, which isn't
 136 /// always desired.
 137 ///
 138 /// ## How can I implement `Eq`?
 139 ///
 140 /// If you cannot use the `derive` strategy, specify that your type implements
 141 /// `Eq`, which has no methods:
 142 ///
 143 /// ```
 144 /// enum BookFormat { Paperback, Hardback, Ebook }
 145 /// struct Book {
 146 ///     isbn: i32,
 147 ///     format: BookFormat,
 148 /// }
 149 /// impl PartialEq for Book {
 150 ///     fn eq(&self, other: &Book) -> bool {
 151 ///         self.isbn == other.isbn
 152 ///     }
 153 /// }
 154 /// impl Eq for Book {}
 155 /// ```
 156 #[stable(feature = "rust1", since = "1.0.0")]
 157 pub trait Eq: PartialEq<Self> {
 158     // FIXME #13101: this method is used solely by #[deriving] to
 159     // assert that every component of a type implements #[deriving]
 160     // itself, the current deriving infrastructure means doing this
 161     // assertion without using a method on this trait is nearly
 162     // impossible.
 163     //
 164     // This should never be implemented by hand.
 165     #[doc(hidden)]
 166     #[inline(always)]
 167     #[stable(feature = "rust1", since = "1.0.0")]
 168     fn assert_receiver_is_total_eq(&self) {}
 169 }
 170
 171 // FIXME: this struct is used solely by #[derive] to
 172 // assert that every component of a type implements Eq.
 173 //
 174 // This struct should never appear in user code.
 175 #[doc(hidden)]
 176 #[allow(missing_debug_implementations)]
 177 #[unstable(feature = "derive_eq",
 178            reason = "deriving hack, should not be public",
 179            issue = "0")]
 180 pub struct AssertParamIsEq<T: Eq + ?Sized> { _field: ::marker::PhantomData<T> }
 181
 182 /// An `Ordering` is the result of a comparison between two values.
 183 ///
 184 /// # Examples
 185 ///
 186 /// ```
 187 /// use std::cmp::Ordering;
 188 ///
 189 /// let result = 1.cmp(&2);
 190 /// assert_eq!(Ordering::Less, result);
 191 ///
 192 /// let result = 1.cmp(&1);
 193 /// assert_eq!(Ordering::Equal, result);
 194 ///
 195 /// let result = 2.cmp(&1);
 196 /// assert_eq!(Ordering::Greater, result);
 197 /// ```
 198 #[derive(Clone, Copy, PartialEq, Debug, Hash)]
 199 #[stable(feature = "rust1", since = "1.0.0")]
 200 pub enum Ordering {
 201     /// An ordering where a compared value is less [than another].
 202     #[stable(feature = "rust1", since = "1.0.0")]
 203     Less = -1,
 204     /// An ordering where a compared value is equal [to another].
 205     #[stable(feature = "rust1", since = "1.0.0")]
 206     Equal = 0,
 207     /// An ordering where a compared value is greater [than another].
 208     #[stable(feature = "rust1", since = "1.0.0")]
 209     Greater = 1,
 210 }
 211
 212 impl Ordering {
 213     /// Reverse the `Ordering`.
 214     ///
 215     /// * `Less` becomes `Greater`.
 216     /// * `Greater` becomes `Less`.
 217     /// * `Equal` becomes `Equal`.
 218     ///
 219     /// # Examples
 220     ///
 221     /// Basic behavior:
 222     ///
 223     /// ```
 224     /// use std::cmp::Ordering;
 225     ///
 226     /// assert_eq!(Ordering::Less.reverse(), Ordering::Greater);
 227     /// assert_eq!(Ordering::Equal.reverse(), Ordering::Equal);
 228     /// assert_eq!(Ordering::Greater.reverse(), Ordering::Less);
 229     /// ```
 230     ///
 231     /// This method can be used to reverse a comparison:
 232     ///
 233     /// ```
 234     /// let mut data: &mut [_] = &mut [2, 10, 5, 8];
 235     ///
 236     /// // sort the array from largest to smallest.
 237     /// data.sort_by(|a, b| a.cmp(b).reverse());
 238     ///
 239     /// let b: &mut [_] = &mut [10, 8, 5, 2];
 240     /// assert!(data == b);
 241     /// ```
 242     #[inline]
 243     #[stable(feature = "rust1", since = "1.0.0")]
 244     pub fn reverse(self) -> Ordering {
 245         match self {
 246             Less => Greater,
 247             Equal => Equal,
 248             Greater => Less,
 249         }
 250     }
 251
 252     /// Chains two orderings.
 253     ///
 254     /// Returns `self` when it's not `Equal`. Otherwise returns `other`.
 255     /// # Examples
 256     ///
 257     /// ```
 258     /// use std::cmp::Ordering;
 259     ///
 260     /// let result = Ordering::Equal.then(Ordering::Less);
 261     /// assert_eq!(result, Ordering::Less);
 262     ///
 263     /// let result = Ordering::Less.then(Ordering::Equal);
 264     /// assert_eq!(result, Ordering::Less);
 265     ///
 266     /// let result = Ordering::Less.then(Ordering::Greater);
 267     /// assert_eq!(result, Ordering::Less);
 268     ///
 269     /// let result = Ordering::Equal.then(Ordering::Equal);
 270     /// assert_eq!(result, Ordering::Equal);
 271     ///
 272     /// let x: (i64, i64, i64) = (1, 2, 7);
 273     /// let y: (i64, i64, i64) = (1, 5, 3);
 274     /// let result = x.0.cmp(&y.0).then(x.1.cmp(&y.1)).then(x.2.cmp(&y.2));
 275     ///
 276     /// assert_eq!(result, Ordering::Less);
 277     /// ```
 278     #[inline]
 279     #[stable(feature = "ordering_chaining", since = "1.17.0")]
 280     pub fn then(self, other: Ordering) -> Ordering {
 281         match self {
 282             Equal => other,
 283             _ => self,
 284         }
 285     }
 286
 287     /// Chains the ordering with the given function.
 288     ///
 289     /// Returns `self` when it's not `Equal`. Otherwise calls `f` and returns
 290     /// the result.
 291     ///
 292     /// # Examples
 293     ///
 294     /// ```
 295     /// use std::cmp::Ordering;
 296     ///
 297     /// let result = Ordering::Equal.then_with(|| Ordering::Less);
 298     /// assert_eq!(result, Ordering::Less);
 299     ///
 300     /// let result = Ordering::Less.then_with(|| Ordering::Equal);
 301     /// assert_eq!(result, Ordering::Less);
 302     ///
 303     /// let result = Ordering::Less.then_with(|| Ordering::Greater);
 304     /// assert_eq!(result, Ordering::Less);
 305     ///
 306     /// let result = Ordering::Equal.then_with(|| Ordering::Equal);
 307     /// assert_eq!(result, Ordering::Equal);
 308     ///
 309     /// let x: (i64, i64, i64) = (1, 2, 7);
 310     /// let y: (i64, i64, i64)  = (1, 5, 3);
 311     /// let result = x.0.cmp(&y.0).then_with(|| x.1.cmp(&y.1)).then_with(|| x.2.cmp(&y.2));
 312     ///
 313     /// assert_eq!(result, Ordering::Less);
 314     /// ```
 315     #[inline]
 316     #[stable(feature = "ordering_chaining", since = "1.17.0")]
 317     pub fn then_with<F: FnOnce() -> Ordering>(self, f: F) -> Ordering {
 318         match self {
 319             Equal => f(),
 320             _ => self,
 321         }
 322     }
 323 }
 324
 325 /// Trait for types that form a [total order](https://en.wikipedia.org/wiki/Total_order).
 326 ///
 327 /// An order is a total order if it is (for all `a`, `b` and `c`):
 328 ///
 329 /// - total and antisymmetric: exactly one of `a < b`, `a == b` or `a > b` is true; and
 330 /// - transitive, `a < b` and `b < c` implies `a < c`. The same must hold for both `==` and `>`.
 331 ///
 332 /// ## Derivable
 333 ///
 334 /// This trait can be used with `#[derive]`. When `derive`d, it will produce a lexicographic
 335 /// ordering based on the top-to-bottom declaration order of the struct's members.
 336 ///
 337 /// ## How can I implement `Ord`?
 338 ///
 339 /// `Ord` requires that the type also be `PartialOrd` and `Eq` (which requires `PartialEq`).
 340 ///
 341 /// Then you must define an implementation for `cmp()`. You may find it useful to use
 342 /// `cmp()` on your type's fields.
 343 ///
 344 /// Here's an example where you want to sort people by height only, disregarding `id`
 345 /// and `name`:
 346 ///
 347 /// ```
 348 /// use std::cmp::Ordering;
 349 ///
 350 /// #[derive(Eq)]
 351 /// struct Person {
 352 ///     id: u32,
 353 ///     name: String,
 354 ///     height: u32,
 355 /// }
 356 ///
 357 /// impl Ord for Person {
 358 ///     fn cmp(&self, other: &Person) -> Ordering {
 359 ///         self.height.cmp(&other.height)
 360 ///     }
 361 /// }
 362 ///
 363 /// impl PartialOrd for Person {
 364 ///     fn partial_cmp(&self, other: &Person) -> Option<Ordering> {
 365 ///         Some(self.cmp(other))
 366 ///     }
 367 /// }
 368 ///
 369 /// impl PartialEq for Person {
 370 ///     fn eq(&self, other: &Person) -> bool {
 371 ///         self.height == other.height
 372 ///     }
 373 /// }
 374 /// ```
 375 #[stable(feature = "rust1", since = "1.0.0")]
 376 pub trait Ord: Eq + PartialOrd<Self> {
 377     /// This method returns an `Ordering` between `self` and `other`.
 378     ///
 379     /// By convention, `self.cmp(&other)` returns the ordering matching the expression
 380     /// `self <operator> other` if true.
 381     ///
 382     /// # Examples
 383     ///
 384     /// ```
 385     /// use std::cmp::Ordering;
 386     ///
 387     /// assert_eq!(5.cmp(&10), Ordering::Less);
 388     /// assert_eq!(10.cmp(&5), Ordering::Greater);
 389     /// assert_eq!(5.cmp(&5), Ordering::Equal);
 390     /// ```
 391     #[stable(feature = "rust1", since = "1.0.0")]
 392     fn cmp(&self, other: &Self) -> Ordering;
 393 }
 394
 395 #[stable(feature = "rust1", since = "1.0.0")]
 396 impl Eq for Ordering {}
 397
 398 #[stable(feature = "rust1", since = "1.0.0")]
 399 impl Ord for Ordering {
 400     #[inline]
 401     fn cmp(&self, other: &Ordering) -> Ordering {
 402         (*self as i32).cmp(&(*other as i32))
 403     }
 404 }
 405
 406 #[stable(feature = "rust1", since = "1.0.0")]
 407 impl PartialOrd for Ordering {
 408     #[inline]
 409     fn partial_cmp(&self, other: &Ordering) -> Option<Ordering> {
 410         (*self as i32).partial_cmp(&(*other as i32))
 411     }
 412 }
 413
 414 /// Trait for values that can be compared for a sort-order.
 415 ///
 416 /// The comparison must satisfy, for all `a`, `b` and `c`:
 417 ///
 418 /// - antisymmetry: if `a < b` then `!(a > b)`, as well as `a > b` implying `!(a < b)`; and
 419 /// - transitivity: `a < b` and `b < c` implies `a < c`. The same must hold for both `==` and `>`.
 420 ///
 421 /// Note that these requirements mean that the trait itself must be implemented symmetrically and
 422 /// transitively: if `T: PartialOrd<U>` and `U: PartialOrd<V>` then `U: PartialOrd<T>` and `T:
 423 /// PartialOrd<V>`.
 424 ///
 425 /// ## Derivable
 426 ///
 427 /// This trait can be used with `#[derive]`. When `derive`d, it will produce a lexicographic
 428 /// ordering based on the top-to-bottom declaration order of the struct's members.
 429 ///
 430 /// ## How can I implement `PartialOrd`?
 431 ///
 432 /// PartialOrd only requires implementation of the `partial_cmp` method, with the others generated
 433 /// from default implementations.
 434 ///
 435 /// However it remains possible to implement the others separately for types which do not have a
 436 /// total order. For example, for floating point numbers, `NaN < 0 == false` and `NaN >= 0 ==
 437 /// false` (cf. IEEE 754-2008 section 5.11).
 438 ///
 439 /// `PartialOrd` requires your type to be `PartialEq`.
 440 ///
 441 /// If your type is `Ord`, you can implement `partial_cmp()` by using `cmp()`:
 442 ///
 443 /// ```
 444 /// use std::cmp::Ordering;
 445 ///
 446 /// #[derive(Eq)]
 447 /// struct Person {
 448 ///     id: u32,
 449 ///     name: String,
 450 ///     height: u32,
 451 /// }
 452 ///
 453 /// impl PartialOrd for Person {
 454 ///     fn partial_cmp(&self, other: &Person) -> Option<Ordering> {
 455 ///         Some(self.cmp(other))
 456 ///     }
 457 /// }
 458 ///
 459 /// impl Ord for Person {
 460 ///     fn cmp(&self, other: &Person) -> Ordering {
 461 ///         self.height.cmp(&other.height)
 462 ///     }
 463 /// }
 464 ///
 465 /// impl PartialEq for Person {
 466 ///     fn eq(&self, other: &Person) -> bool {
 467 ///         self.height == other.height
 468 ///     }
 469 /// }
 470 /// ```
 471 ///
 472 /// You may also find it useful to use `partial_cmp()` on your type's fields. Here
 473 /// is an example of `Person` types who have a floating-point `height` field that
 474 /// is the only field to be used for sorting:
 475 ///
 476 /// ```
 477 /// use std::cmp::Ordering;
 478 ///
 479 /// struct Person {
 480 ///     id: u32,
 481 ///     name: String,
 482 ///     height: f64,
 483 /// }
 484 ///
 485 /// impl PartialOrd for Person {
 486 ///     fn partial_cmp(&self, other: &Person) -> Option<Ordering> {
 487 ///         self.height.partial_cmp(&other.height)
 488 ///     }
 489 /// }
 490 ///
 491 /// impl PartialEq for Person {
 492 ///     fn eq(&self, other: &Person) -> bool {
 493 ///         self.height == other.height
 494 ///     }
 495 /// }
 496 /// ```
 497 ///
 498 /// # Examples
 499 ///
 500 /// ```
 501 /// let x : u32 = 0;
 502 /// let y : u32 = 1;
 503 ///
 504 /// assert_eq!(x < y, true);
 505 /// assert_eq!(x.lt(&y), true);
 506 /// ```
 507 #[lang = "ord"]
 508 #[stable(feature = "rust1", since = "1.0.0")]
 509 pub trait PartialOrd<Rhs: ?Sized = Self>: PartialEq<Rhs> {
 510     /// This method returns an ordering between `self` and `other` values if one exists.
 511     ///
 512     /// # Examples
 513     ///
 514     /// ```
 515     /// use std::cmp::Ordering;
 516     ///
 517     /// let result = 1.0.partial_cmp(&2.0);
 518     /// assert_eq!(result, Some(Ordering::Less));
 519     ///
 520     /// let result = 1.0.partial_cmp(&1.0);
 521     /// assert_eq!(result, Some(Ordering::Equal));
 522     ///
 523     /// let result = 2.0.partial_cmp(&1.0);
 524     /// assert_eq!(result, Some(Ordering::Greater));
 525     /// ```
 526     ///
 527     /// When comparison is impossible:
 528     ///
 529     /// ```
 530     /// let result = std::f64::NAN.partial_cmp(&1.0);
 531     /// assert_eq!(result, None);
 532     /// ```
 533     #[stable(feature = "rust1", since = "1.0.0")]
 534     fn partial_cmp(&self, other: &Rhs) -> Option<Ordering>;
 535
 536     /// This method tests less than (for `self` and `other`) and is used by the `<` operator.
 537     ///
 538     /// # Examples
 539     ///
 540     /// ```
 541     /// let result = 1.0 < 2.0;
 542     /// assert_eq!(result, true);
 543     ///
 544     /// let result = 2.0 < 1.0;
 545     /// assert_eq!(result, false);
 546     /// ```
 547     #[inline]
 548     #[stable(feature = "rust1", since = "1.0.0")]
 549     fn lt(&self, other: &Rhs) -> bool {
 550         match self.partial_cmp(other) {
 551             Some(Less) => true,
 552             _ => false,
 553         }
 554     }
 555
 556     /// This method tests less than or equal to (for `self` and `other`) and is used by the `<=`
 557     /// operator.
 558     ///
 559     /// # Examples
 560     ///
 561     /// ```
 562     /// let result = 1.0 <= 2.0;
 563     /// assert_eq!(result, true);
 564     ///
 565     /// let result = 2.0 <= 2.0;
 566     /// assert_eq!(result, true);
 567     /// ```
 568     #[inline]
 569     #[stable(feature = "rust1", since = "1.0.0")]
 570     fn le(&self, other: &Rhs) -> bool {
 571         match self.partial_cmp(other) {
 572             Some(Less) | Some(Equal) => true,
 573             _ => false,
 574         }
 575     }
 576
 577     /// This method tests greater than (for `self` and `other`) and is used by the `>` operator.
 578     ///
 579     /// # Examples
 580     ///
 581     /// ```
 582     /// let result = 1.0 > 2.0;
 583     /// assert_eq!(result, false);
 584     ///
 585     /// let result = 2.0 > 2.0;
 586     /// assert_eq!(result, false);
 587     /// ```
 588     #[inline]
 589     #[stable(feature = "rust1", since = "1.0.0")]
 590     fn gt(&self, other: &Rhs) -> bool {
 591         match self.partial_cmp(other) {
 592             Some(Greater) => true,
 593             _ => false,
 594         }
 595     }
 596
 597     /// This method tests greater than or equal to (for `self` and `other`) and is used by the `>=`
 598     /// operator.
 599     ///
 600     /// # Examples
 601     ///
 602     /// ```
 603     /// let result = 2.0 >= 1.0;
 604     /// assert_eq!(result, true);
 605     ///
 606     /// let result = 2.0 >= 2.0;
 607     /// assert_eq!(result, true);
 608     /// ```
 609     #[inline]
 610     #[stable(feature = "rust1", since = "1.0.0")]
 611     fn ge(&self, other: &Rhs) -> bool {
 612         match self.partial_cmp(other) {
 613             Some(Greater) | Some(Equal) => true,
 614             _ => false,
 615         }
 616     }
 617 }
 618
 619 /// Compare and return the minimum of two values.
 620 ///
 621 /// Returns the first argument if the comparison determines them to be equal.
 622 ///
 623 /// # Examples
 624 ///
 625 /// ```
 626 /// use std::cmp;
 627 ///
 628 /// assert_eq!(1, cmp::min(1, 2));
 629 /// assert_eq!(2, cmp::min(2, 2));
 630 /// ```
 631 #[inline]
 632 #[stable(feature = "rust1", since = "1.0.0")]
 633 pub fn min<T: Ord>(v1: T, v2: T) -> T {
 634     if v1 <= v2 { v1 } else { v2 }
 635 }
 636
 637 /// Compare and return the maximum of two values.
 638 ///
 639 /// Returns the second argument if the comparison determines them to be equal.
 640 ///
 641 /// # Examples
 642 ///
 643 /// ```
 644 /// use std::cmp;
 645 ///
 646 /// assert_eq!(2, cmp::max(1, 2));
 647 /// assert_eq!(2, cmp::max(2, 2));
 648 /// ```
 649 #[inline]
 650 #[stable(feature = "rust1", since = "1.0.0")]
 651 pub fn max<T: Ord>(v1: T, v2: T) -> T {
 652     if v2 >= v1 { v2 } else { v1 }
 653 }
 654
 655 // Implementation of PartialEq, Eq, PartialOrd and Ord for primitive types
 656 mod impls {
 657     use cmp::Ordering::{self, Less, Greater, Equal};
 658
 659     macro_rules! partial_eq_impl {
 660         ($($t:ty)*) => ($(
 661             #[stable(feature = "rust1", since = "1.0.0")]
 662             impl PartialEq for $t {
 663                 #[inline]
 664                 fn eq(&self, other: &$t) -> bool { (*self) == (*other) }
 665                 #[inline]
 666                 fn ne(&self, other: &$t) -> bool { (*self) != (*other) }
 667             }
 668         )*)
 669     }
 670
 671     #[stable(feature = "rust1", since = "1.0.0")]
 672     impl PartialEq for () {
 673         #[inline]
 674         fn eq(&self, _other: &()) -> bool { true }
 675         #[inline]
 676         fn ne(&self, _other: &()) -> bool { false }
 677     }
 678
 679     partial_eq_impl! {
 680         bool char usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f32 f64
 681     }
 682
 683     macro_rules! eq_impl {
 684         ($($t:ty)*) => ($(
 685             #[stable(feature = "rust1", since = "1.0.0")]
 686             impl Eq for $t {}
 687         )*)
 688     }
 689
 690     eq_impl! { () bool char usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 }
 691
 692     macro_rules! partial_ord_impl {
 693         ($($t:ty)*) => ($(
 694             #[stable(feature = "rust1", since = "1.0.0")]
 695             impl PartialOrd for $t {
 696                 #[inline]
 697                 fn partial_cmp(&self, other: &$t) -> Option<Ordering> {
 698                     match (self <= other, self >= other) {
 699                         (false, false) => None,
 700                         (false, true) => Some(Greater),
 701                         (true, false) => Some(Less),
 702                         (true, true) => Some(Equal),
 703                     }
 704                 }
 705                 #[inline]
 706                 fn lt(&self, other: &$t) -> bool { (*self) < (*other) }
 707                 #[inline]
 708                 fn le(&self, other: &$t) -> bool { (*self) <= (*other) }
 709                 #[inline]
 710                 fn ge(&self, other: &$t) -> bool { (*self) >= (*other) }
 711                 #[inline]
 712                 fn gt(&self, other: &$t) -> bool { (*self) > (*other) }
 713             }
 714         )*)
 715     }
 716
 717     #[stable(feature = "rust1", since = "1.0.0")]
 718     impl PartialOrd for () {
 719         #[inline]
 720         fn partial_cmp(&self, _: &()) -> Option<Ordering> {
 721             Some(Equal)
 722         }
 723     }
 724
 725     #[stable(feature = "rust1", since = "1.0.0")]
 726     impl PartialOrd for bool {
 727         #[inline]
 728         fn partial_cmp(&self, other: &bool) -> Option<Ordering> {
 729             (*self as u8).partial_cmp(&(*other as u8))
 730         }
 731     }
 732
 733     partial_ord_impl! { f32 f64 }
 734
 735     macro_rules! ord_impl {
 736         ($($t:ty)*) => ($(
 737             #[stable(feature = "rust1", since = "1.0.0")]
 738             impl PartialOrd for $t {
 739                 #[inline]
 740                 fn partial_cmp(&self, other: &$t) -> Option<Ordering> {
 741                     Some(self.cmp(other))
 742                 }
 743                 #[inline]
 744                 fn lt(&self, other: &$t) -> bool { (*self) < (*other) }
 745                 #[inline]
 746                 fn le(&self, other: &$t) -> bool { (*self) <= (*other) }
 747                 #[inline]
 748                 fn ge(&self, other: &$t) -> bool { (*self) >= (*other) }
 749                 #[inline]
 750                 fn gt(&self, other: &$t) -> bool { (*self) > (*other) }
 751             }
 752
 753             #[stable(feature = "rust1", since = "1.0.0")]
 754             impl Ord for $t {
 755                 #[inline]
 756                 fn cmp(&self, other: &$t) -> Ordering {
 757                     if *self == *other { Equal }
 758                     else if *self < *other { Less }
 759                     else { Greater }
 760                 }
 761             }
 762         )*)
 763     }
 764
 765     #[stable(feature = "rust1", since = "1.0.0")]
 766     impl Ord for () {
 767         #[inline]
 768         fn cmp(&self, _other: &()) -> Ordering { Equal }
 769     }
 770
 771     #[stable(feature = "rust1", since = "1.0.0")]
 772     impl Ord for bool {
 773         #[inline]
 774         fn cmp(&self, other: &bool) -> Ordering {
 775             (*self as u8).cmp(&(*other as u8))
 776         }
 777     }
 778
 779     ord_impl! { char usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 }
 780
 781     #[unstable(feature = "never_type_impls", issue = "35121")]
 782     impl PartialEq for ! {
 783         fn eq(&self, _: &!) -> bool {
 784             *self
 785         }
 786     }
 787
 788     #[unstable(feature = "never_type_impls", issue = "35121")]
 789     impl Eq for ! {}
 790
 791     #[unstable(feature = "never_type_impls", issue = "35121")]
 792     impl PartialOrd for ! {
 793         fn partial_cmp(&self, _: &!) -> Option<Ordering> {
 794             *self
 795         }
 796     }
 797
 798     #[unstable(feature = "never_type_impls", issue = "35121")]
 799     impl Ord for ! {
 800         fn cmp(&self, _: &!) -> Ordering {
 801             *self
 802         }
 803     }
 804
 805     // & pointers
 806
 807     #[stable(feature = "rust1", since = "1.0.0")]
 808     impl<'a, 'b, A: ?Sized, B: ?Sized> PartialEq<&'b B> for &'a A where A: PartialEq<B> {
 809         #[inline]
 810         fn eq(&self, other: & &'b B) -> bool { PartialEq::eq(*self, *other) }
 811         #[inline]
 812         fn ne(&self, other: & &'b B) -> bool { PartialEq::ne(*self, *other) }
 813     }
 814     #[stable(feature = "rust1", since = "1.0.0")]
 815     impl<'a, 'b, A: ?Sized, B: ?Sized> PartialOrd<&'b B> for &'a A where A: PartialOrd<B> {
 816         #[inline]
 817         fn partial_cmp(&self, other: &&'b B) -> Option<Ordering> {
 818             PartialOrd::partial_cmp(*self, *other)
 819         }
 820         #[inline]
 821         fn lt(&self, other: & &'b B) -> bool { PartialOrd::lt(*self, *other) }
 822         #[inline]
 823         fn le(&self, other: & &'b B) -> bool { PartialOrd::le(*self, *other) }
 824         #[inline]
 825         fn ge(&self, other: & &'b B) -> bool { PartialOrd::ge(*self, *other) }
 826         #[inline]
 827         fn gt(&self, other: & &'b B) -> bool { PartialOrd::gt(*self, *other) }
 828     }
 829     #[stable(feature = "rust1", since = "1.0.0")]
 830     impl<'a, A: ?Sized> Ord for &'a A where A: Ord {
 831         #[inline]
 832         fn cmp(&self, other: & &'a A) -> Ordering { Ord::cmp(*self, *other) }
 833     }
 834     #[stable(feature = "rust1", since = "1.0.0")]
 835     impl<'a, A: ?Sized> Eq for &'a A where A: Eq {}
 836
 837     // &mut pointers
 838
 839     #[stable(feature = "rust1", since = "1.0.0")]
 840     impl<'a, 'b, A: ?Sized, B: ?Sized> PartialEq<&'b mut B> for &'a mut A where A: PartialEq<B> {
 841         #[inline]
 842         fn eq(&self, other: &&'b mut B) -> bool { PartialEq::eq(*self, *other) }
 843         #[inline]
 844         fn ne(&self, other: &&'b mut B) -> bool { PartialEq::ne(*self, *other) }
 845     }
 846     #[stable(feature = "rust1", since = "1.0.0")]
 847     impl<'a, 'b, A: ?Sized, B: ?Sized> PartialOrd<&'b mut B> for &'a mut A where A: PartialOrd<B> {
 848         #[inline]
 849         fn partial_cmp(&self, other: &&'b mut B) -> Option<Ordering> {
 850             PartialOrd::partial_cmp(*self, *other)
 851         }
 852         #[inline]
 853         fn lt(&self, other: &&'b mut B) -> bool { PartialOrd::lt(*self, *other) }
 854         #[inline]
 855         fn le(&self, other: &&'b mut B) -> bool { PartialOrd::le(*self, *other) }
 856         #[inline]
 857         fn ge(&self, other: &&'b mut B) -> bool { PartialOrd::ge(*self, *other) }
 858         #[inline]
 859         fn gt(&self, other: &&'b mut B) -> bool { PartialOrd::gt(*self, *other) }
 860     }
 861     #[stable(feature = "rust1", since = "1.0.0")]
 862     impl<'a, A: ?Sized> Ord for &'a mut A where A: Ord {
 863         #[inline]
 864         fn cmp(&self, other: &&'a mut A) -> Ordering { Ord::cmp(*self, *other) }
 865     }
 866     #[stable(feature = "rust1", since = "1.0.0")]
 867     impl<'a, A: ?Sized> Eq for &'a mut A where A: Eq {}
 868
 869     #[stable(feature = "rust1", since = "1.0.0")]
 870     impl<'a, 'b, A: ?Sized, B: ?Sized> PartialEq<&'b mut B> for &'a A where A: PartialEq<B> {
 871         #[inline]
 872         fn eq(&self, other: &&'b mut B) -> bool { PartialEq::eq(*self, *other) }
 873         #[inline]
 874         fn ne(&self, other: &&'b mut B) -> bool { PartialEq::ne(*self, *other) }
 875     }
 876
 877     #[stable(feature = "rust1", since = "1.0.0")]
 878     impl<'a, 'b, A: ?Sized, B: ?Sized> PartialEq<&'b B> for &'a mut A where A: PartialEq<B> {
 879         #[inline]
 880         fn eq(&self, other: &&'b B) -> bool { PartialEq::eq(*self, *other) }
 881         #[inline]
 882         fn ne(&self, other: &&'b B) -> bool { PartialEq::ne(*self, *other) }
 883     }
 884 }