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     /// #![feature(ordering_chaining)]
 259     ///
 260     /// use std::cmp::Ordering;
 261     ///
 262     /// let result = Ordering::Equal.then(Ordering::Less);
 263     /// assert_eq!(result, Ordering::Less);
 264     ///
 265     /// let result = Ordering::Less.then(Ordering::Equal);
 266     /// assert_eq!(result, Ordering::Less);
 267     ///
 268     /// let result = Ordering::Less.then(Ordering::Greater);
 269     /// assert_eq!(result, Ordering::Less);
 270     ///
 271     /// let result = Ordering::Equal.then(Ordering::Equal);
 272     /// assert_eq!(result, Ordering::Equal);
 273     ///
 274     /// let x: (i64, i64, i64) = (1, 2, 7);
 275     /// let y: (i64, i64, i64) = (1, 5, 3);
 276     /// let result = x.0.cmp(&y.0).then(x.1.cmp(&y.1)).then(x.2.cmp(&y.2));
 277     ///
 278     /// assert_eq!(result, Ordering::Less);
 279     /// ```
 280     #[unstable(feature = "ordering_chaining", issue = "37053")]
 281     pub fn then(self, other: Ordering) -> Ordering {
 282         match self {
 283             Equal => other,
 284             _ => self,
 285         }
 286     }
 287
 288     /// Chains the ordering with the given function.
 289     ///
 290     /// Returns `self` when it's not `Equal`. Otherwise calls `f` and returns
 291     /// the result.
 292     ///
 293     /// # Examples
 294     ///
 295     /// ```
 296     /// #![feature(ordering_chaining)]
 297     ///
 298     /// use std::cmp::Ordering;
 299     ///
 300     /// let result = Ordering::Equal.then_with(|| Ordering::Less);
 301     /// assert_eq!(result, Ordering::Less);
 302     ///
 303     /// let result = Ordering::Less.then_with(|| Ordering::Equal);
 304     /// assert_eq!(result, Ordering::Less);
 305     ///
 306     /// let result = Ordering::Less.then_with(|| Ordering::Greater);
 307     /// assert_eq!(result, Ordering::Less);
 308     ///
 309     /// let result = Ordering::Equal.then_with(|| Ordering::Equal);
 310     /// assert_eq!(result, Ordering::Equal);
 311     ///
 312     /// let x: (i64, i64, i64) = (1, 2, 7);
 313     /// let y: (i64, i64, i64)  = (1, 5, 3);
 314     /// let result = x.0.cmp(&y.0).then_with(|| x.1.cmp(&y.1)).then_with(|| x.2.cmp(&y.2));
 315     ///
 316     /// assert_eq!(result, Ordering::Less);
 317     /// ```
 318     #[unstable(feature = "ordering_chaining", issue = "37053")]
 319     pub fn then_with<F: FnOnce() -> Ordering>(self, f: F) -> Ordering {
 320         match self {
 321             Equal => f(),
 322             _ => self,
 323         }
 324     }
 325 }
 326
 327 /// Trait for types that form a [total order](https://en.wikipedia.org/wiki/Total_order).
 328 ///
 329 /// An order is a total order if it is (for all `a`, `b` and `c`):
 330 ///
 331 /// - total and antisymmetric: exactly one of `a < b`, `a == b` or `a > b` is true; and
 332 /// - transitive, `a < b` and `b < c` implies `a < c`. The same must hold for both `==` and `>`.
 333 ///
 334 /// ## Derivable
 335 ///
 336 /// This trait can be used with `#[derive]`. When `derive`d, it will produce a lexicographic
 337 /// ordering based on the top-to-bottom declaration order of the struct's members.
 338 ///
 339 /// ## How can I implement `Ord`?
 340 ///
 341 /// `Ord` requires that the type also be `PartialOrd` and `Eq` (which requires `PartialEq`).
 342 ///
 343 /// Then you must define an implementation for `cmp()`. You may find it useful to use
 344 /// `cmp()` on your type's fields.
 345 ///
 346 /// Here's an example where you want to sort people by height only, disregarding `id`
 347 /// and `name`:
 348 ///
 349 /// ```
 350 /// use std::cmp::Ordering;
 351 ///
 352 /// #[derive(Eq)]
 353 /// struct Person {
 354 ///     id: u32,
 355 ///     name: String,
 356 ///     height: u32,
 357 /// }
 358 ///
 359 /// impl Ord for Person {
 360 ///     fn cmp(&self, other: &Person) -> Ordering {
 361 ///         self.height.cmp(&other.height)
 362 ///     }
 363 /// }
 364 ///
 365 /// impl PartialOrd for Person {
 366 ///     fn partial_cmp(&self, other: &Person) -> Option<Ordering> {
 367 ///         Some(self.cmp(other))
 368 ///     }
 369 /// }
 370 ///
 371 /// impl PartialEq for Person {
 372 ///     fn eq(&self, other: &Person) -> bool {
 373 ///         self.height == other.height
 374 ///     }
 375 /// }
 376 /// ```
 377 #[stable(feature = "rust1", since = "1.0.0")]
 378 pub trait Ord: Eq + PartialOrd<Self> {
 379     /// This method returns an `Ordering` between `self` and `other`.
 380     ///
 381     /// By convention, `self.cmp(&other)` returns the ordering matching the expression
 382     /// `self <operator> other` if true.
 383     ///
 384     /// # Examples
 385     ///
 386     /// ```
 387     /// use std::cmp::Ordering;
 388     ///
 389     /// assert_eq!(5.cmp(&10), Ordering::Less);
 390     /// assert_eq!(10.cmp(&5), Ordering::Greater);
 391     /// assert_eq!(5.cmp(&5), Ordering::Equal);
 392     /// ```
 393     #[stable(feature = "rust1", since = "1.0.0")]
 394     fn cmp(&self, other: &Self) -> Ordering;
 395 }
 396
 397 #[stable(feature = "rust1", since = "1.0.0")]
 398 impl Eq for Ordering {}
 399
 400 #[stable(feature = "rust1", since = "1.0.0")]
 401 impl Ord for Ordering {
 402     #[inline]
 403     fn cmp(&self, other: &Ordering) -> Ordering {
 404         (*self as i32).cmp(&(*other as i32))
 405     }
 406 }
 407
 408 #[stable(feature = "rust1", since = "1.0.0")]
 409 impl PartialOrd for Ordering {
 410     #[inline]
 411     fn partial_cmp(&self, other: &Ordering) -> Option<Ordering> {
 412         (*self as i32).partial_cmp(&(*other as i32))
 413     }
 414 }
 415
 416 /// Trait for values that can be compared for a sort-order.
 417 ///
 418 /// The comparison must satisfy, for all `a`, `b` and `c`:
 419 ///
 420 /// - antisymmetry: if `a < b` then `!(a > b)`, as well as `a > b` implying `!(a < b)`; and
 421 /// - transitivity: `a < b` and `b < c` implies `a < c`. The same must hold for both `==` and `>`.
 422 ///
 423 /// Note that these requirements mean that the trait itself must be implemented symmetrically and
 424 /// transitively: if `T: PartialOrd<U>` and `U: PartialOrd<V>` then `U: PartialOrd<T>` and `T:
 425 /// PartialOrd<V>`.
 426 ///
 427 /// ## Derivable
 428 ///
 429 /// This trait can be used with `#[derive]`. When `derive`d, it will produce a lexicographic
 430 /// ordering based on the top-to-bottom declaration order of the struct's members.
 431 ///
 432 /// ## How can I implement `PartialOrd`?
 433 ///
 434 /// PartialOrd only requires implementation of the `partial_cmp` method, with the others generated
 435 /// from default implementations.
 436 ///
 437 /// However it remains possible to implement the others separately for types which do not have a
 438 /// total order. For example, for floating point numbers, `NaN < 0 == false` and `NaN >= 0 ==
 439 /// false` (cf. IEEE 754-2008 section 5.11).
 440 ///
 441 /// `PartialOrd` requires your type to be `PartialEq`.
 442 ///
 443 /// If your type is `Ord`, you can implement `partial_cmp()` by using `cmp()`:
 444 ///
 445 /// ```
 446 /// use std::cmp::Ordering;
 447 ///
 448 /// #[derive(Eq)]
 449 /// struct Person {
 450 ///     id: u32,
 451 ///     name: String,
 452 ///     height: u32,
 453 /// }
 454 ///
 455 /// impl PartialOrd for Person {
 456 ///     fn partial_cmp(&self, other: &Person) -> Option<Ordering> {
 457 ///         Some(self.cmp(other))
 458 ///     }
 459 /// }
 460 ///
 461 /// impl Ord for Person {
 462 ///     fn cmp(&self, other: &Person) -> Ordering {
 463 ///         self.height.cmp(&other.height)
 464 ///     }
 465 /// }
 466 ///
 467 /// impl PartialEq for Person {
 468 ///     fn eq(&self, other: &Person) -> bool {
 469 ///         self.height == other.height
 470 ///     }
 471 /// }
 472 /// ```
 473 ///
 474 /// You may also find it useful to use `partial_cmp()` on your type's fields. Here
 475 /// is an example of `Person` types who have a floating-point `height` field that
 476 /// is the only field to be used for sorting:
 477 ///
 478 /// ```
 479 /// use std::cmp::Ordering;
 480 ///
 481 /// struct Person {
 482 ///     id: u32,
 483 ///     name: String,
 484 ///     height: f64,
 485 /// }
 486 ///
 487 /// impl PartialOrd for Person {
 488 ///     fn partial_cmp(&self, other: &Person) -> Option<Ordering> {
 489 ///         self.height.partial_cmp(&other.height)
 490 ///     }
 491 /// }
 492 ///
 493 /// impl PartialEq for Person {
 494 ///     fn eq(&self, other: &Person) -> bool {
 495 ///         self.height == other.height
 496 ///     }
 497 /// }
 498 /// ```
 499 ///
 500 /// # Examples
 501 ///
 502 /// ```
 503 /// let x : u32 = 0;
 504 /// let y : u32 = 1;
 505 ///
 506 /// assert_eq!(x < y, true);
 507 /// assert_eq!(x.lt(&y), true);
 508 /// ```
 509 #[lang = "ord"]
 510 #[stable(feature = "rust1", since = "1.0.0")]
 511 pub trait PartialOrd<Rhs: ?Sized = Self>: PartialEq<Rhs> {
 512     /// This method returns an ordering between `self` and `other` values if one exists.
 513     ///
 514     /// # Examples
 515     ///
 516     /// ```
 517     /// use std::cmp::Ordering;
 518     ///
 519     /// let result = 1.0.partial_cmp(&2.0);
 520     /// assert_eq!(result, Some(Ordering::Less));
 521     ///
 522     /// let result = 1.0.partial_cmp(&1.0);
 523     /// assert_eq!(result, Some(Ordering::Equal));
 524     ///
 525     /// let result = 2.0.partial_cmp(&1.0);
 526     /// assert_eq!(result, Some(Ordering::Greater));
 527     /// ```
 528     ///
 529     /// When comparison is impossible:
 530     ///
 531     /// ```
 532     /// let result = std::f64::NAN.partial_cmp(&1.0);
 533     /// assert_eq!(result, None);
 534     /// ```
 535     #[stable(feature = "rust1", since = "1.0.0")]
 536     fn partial_cmp(&self, other: &Rhs) -> Option<Ordering>;
 537
 538     /// This method tests less than (for `self` and `other`) and is used by the `<` operator.
 539     ///
 540     /// # Examples
 541     ///
 542     /// ```
 543     /// let result = 1.0 < 2.0;
 544     /// assert_eq!(result, true);
 545     ///
 546     /// let result = 2.0 < 1.0;
 547     /// assert_eq!(result, false);
 548     /// ```
 549     #[inline]
 550     #[stable(feature = "rust1", since = "1.0.0")]
 551     fn lt(&self, other: &Rhs) -> bool {
 552         match self.partial_cmp(other) {
 553             Some(Less) => true,
 554             _ => false,
 555         }
 556     }
 557
 558     /// This method tests less than or equal to (for `self` and `other`) and is used by the `<=`
 559     /// operator.
 560     ///
 561     /// # Examples
 562     ///
 563     /// ```
 564     /// let result = 1.0 <= 2.0;
 565     /// assert_eq!(result, true);
 566     ///
 567     /// let result = 2.0 <= 2.0;
 568     /// assert_eq!(result, true);
 569     /// ```
 570     #[inline]
 571     #[stable(feature = "rust1", since = "1.0.0")]
 572     fn le(&self, other: &Rhs) -> bool {
 573         match self.partial_cmp(other) {
 574             Some(Less) | Some(Equal) => true,
 575             _ => false,
 576         }
 577     }
 578
 579     /// This method tests greater than (for `self` and `other`) and is used by the `>` operator.
 580     ///
 581     /// # Examples
 582     ///
 583     /// ```
 584     /// let result = 1.0 > 2.0;
 585     /// assert_eq!(result, false);
 586     ///
 587     /// let result = 2.0 > 2.0;
 588     /// assert_eq!(result, false);
 589     /// ```
 590     #[inline]
 591     #[stable(feature = "rust1", since = "1.0.0")]
 592     fn gt(&self, other: &Rhs) -> bool {
 593         match self.partial_cmp(other) {
 594             Some(Greater) => true,
 595             _ => false,
 596         }
 597     }
 598
 599     /// This method tests greater than or equal to (for `self` and `other`) and is used by the `>=`
 600     /// operator.
 601     ///
 602     /// # Examples
 603     ///
 604     /// ```
 605     /// let result = 2.0 >= 1.0;
 606     /// assert_eq!(result, true);
 607     ///
 608     /// let result = 2.0 >= 2.0;
 609     /// assert_eq!(result, true);
 610     /// ```
 611     #[inline]
 612     #[stable(feature = "rust1", since = "1.0.0")]
 613     fn ge(&self, other: &Rhs) -> bool {
 614         match self.partial_cmp(other) {
 615             Some(Greater) | Some(Equal) => true,
 616             _ => false,
 617         }
 618     }
 619 }
 620
 621 /// Compare and return the minimum of two values.
 622 ///
 623 /// Returns the first argument if the comparison determines them to be equal.
 624 ///
 625 /// # Examples
 626 ///
 627 /// ```
 628 /// use std::cmp;
 629 ///
 630 /// assert_eq!(1, cmp::min(1, 2));
 631 /// assert_eq!(2, cmp::min(2, 2));
 632 /// ```
 633 #[inline]
 634 #[stable(feature = "rust1", since = "1.0.0")]
 635 pub fn min<T: Ord>(v1: T, v2: T) -> T {
 636     if v1 <= v2 { v1 } else { v2 }
 637 }
 638
 639 /// Compare and return the maximum of two values.
 640 ///
 641 /// Returns the second argument if the comparison determines them to be equal.
 642 ///
 643 /// # Examples
 644 ///
 645 /// ```
 646 /// use std::cmp;
 647 ///
 648 /// assert_eq!(2, cmp::max(1, 2));
 649 /// assert_eq!(2, cmp::max(2, 2));
 650 /// ```
 651 #[inline]
 652 #[stable(feature = "rust1", since = "1.0.0")]
 653 pub fn max<T: Ord>(v1: T, v2: T) -> T {
 654     if v2 >= v1 { v2 } else { v1 }
 655 }
 656
 657 // Implementation of PartialEq, Eq, PartialOrd and Ord for primitive types
 658 mod impls {
 659     use cmp::Ordering::{self, Less, Greater, Equal};
 660
 661     macro_rules! partial_eq_impl {
 662         ($($t:ty)*) => ($(
 663             #[stable(feature = "rust1", since = "1.0.0")]
 664             impl PartialEq for $t {
 665                 #[inline]
 666                 fn eq(&self, other: &$t) -> bool { (*self) == (*other) }
 667                 #[inline]
 668                 fn ne(&self, other: &$t) -> bool { (*self) != (*other) }
 669             }
 670         )*)
 671     }
 672
 673     #[stable(feature = "rust1", since = "1.0.0")]
 674     impl PartialEq for () {
 675         #[inline]
 676         fn eq(&self, _other: &()) -> bool { true }
 677         #[inline]
 678         fn ne(&self, _other: &()) -> bool { false }
 679     }
 680
 681     partial_eq_impl! {
 682         bool char usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f32 f64
 683     }
 684
 685     macro_rules! eq_impl {
 686         ($($t:ty)*) => ($(
 687             #[stable(feature = "rust1", since = "1.0.0")]
 688             impl Eq for $t {}
 689         )*)
 690     }
 691
 692     eq_impl! { () bool char usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 }
 693
 694     macro_rules! partial_ord_impl {
 695         ($($t:ty)*) => ($(
 696             #[stable(feature = "rust1", since = "1.0.0")]
 697             impl PartialOrd for $t {
 698                 #[inline]
 699                 fn partial_cmp(&self, other: &$t) -> Option<Ordering> {
 700                     match (self <= other, self >= other) {
 701                         (false, false) => None,
 702                         (false, true) => Some(Greater),
 703                         (true, false) => Some(Less),
 704                         (true, true) => Some(Equal),
 705                     }
 706                 }
 707                 #[inline]
 708                 fn lt(&self, other: &$t) -> bool { (*self) < (*other) }
 709                 #[inline]
 710                 fn le(&self, other: &$t) -> bool { (*self) <= (*other) }
 711                 #[inline]
 712                 fn ge(&self, other: &$t) -> bool { (*self) >= (*other) }
 713                 #[inline]
 714                 fn gt(&self, other: &$t) -> bool { (*self) > (*other) }
 715             }
 716         )*)
 717     }
 718
 719     #[stable(feature = "rust1", since = "1.0.0")]
 720     impl PartialOrd for () {
 721         #[inline]
 722         fn partial_cmp(&self, _: &()) -> Option<Ordering> {
 723             Some(Equal)
 724         }
 725     }
 726
 727     #[stable(feature = "rust1", since = "1.0.0")]
 728     impl PartialOrd for bool {
 729         #[inline]
 730         fn partial_cmp(&self, other: &bool) -> Option<Ordering> {
 731             (*self as u8).partial_cmp(&(*other as u8))
 732         }
 733     }
 734
 735     partial_ord_impl! { f32 f64 }
 736
 737     macro_rules! ord_impl {
 738         ($($t:ty)*) => ($(
 739             #[stable(feature = "rust1", since = "1.0.0")]
 740             impl PartialOrd for $t {
 741                 #[inline]
 742                 fn partial_cmp(&self, other: &$t) -> Option<Ordering> {
 743                     Some(self.cmp(other))
 744                 }
 745                 #[inline]
 746                 fn lt(&self, other: &$t) -> bool { (*self) < (*other) }
 747                 #[inline]
 748                 fn le(&self, other: &$t) -> bool { (*self) <= (*other) }
 749                 #[inline]
 750                 fn ge(&self, other: &$t) -> bool { (*self) >= (*other) }
 751                 #[inline]
 752                 fn gt(&self, other: &$t) -> bool { (*self) > (*other) }
 753             }
 754
 755             #[stable(feature = "rust1", since = "1.0.0")]
 756             impl Ord for $t {
 757                 #[inline]
 758                 fn cmp(&self, other: &$t) -> Ordering {
 759                     if *self == *other { Equal }
 760                     else if *self < *other { Less }
 761                     else { Greater }
 762                 }
 763             }
 764         )*)
 765     }
 766
 767     #[stable(feature = "rust1", since = "1.0.0")]
 768     impl Ord for () {
 769         #[inline]
 770         fn cmp(&self, _other: &()) -> Ordering { Equal }
 771     }
 772
 773     #[stable(feature = "rust1", since = "1.0.0")]
 774     impl Ord for bool {
 775         #[inline]
 776         fn cmp(&self, other: &bool) -> Ordering {
 777             (*self as u8).cmp(&(*other as u8))
 778         }
 779     }
 780
 781     ord_impl! { char usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 }
 782
 783     #[unstable(feature = "never_type_impls", issue = "35121")]
 784     impl PartialEq for ! {
 785         fn eq(&self, _: &!) -> bool {
 786             *self
 787         }
 788     }
 789
 790     #[unstable(feature = "never_type_impls", issue = "35121")]
 791     impl Eq for ! {}
 792
 793     #[unstable(feature = "never_type_impls", issue = "35121")]
 794     impl PartialOrd for ! {
 795         fn partial_cmp(&self, _: &!) -> Option<Ordering> {
 796             *self
 797         }
 798     }
 799
 800     #[unstable(feature = "never_type_impls", issue = "35121")]
 801     impl Ord for ! {
 802         fn cmp(&self, _: &!) -> Ordering {
 803             *self
 804         }
 805     }
 806
 807     // & pointers
 808
 809     #[stable(feature = "rust1", since = "1.0.0")]
 810     impl<'a, 'b, A: ?Sized, B: ?Sized> PartialEq<&'b B> for &'a A where A: PartialEq<B> {
 811         #[inline]
 812         fn eq(&self, other: & &'b B) -> bool { PartialEq::eq(*self, *other) }
 813         #[inline]
 814         fn ne(&self, other: & &'b B) -> bool { PartialEq::ne(*self, *other) }
 815     }
 816     #[stable(feature = "rust1", since = "1.0.0")]
 817     impl<'a, 'b, A: ?Sized, B: ?Sized> PartialOrd<&'b B> for &'a A where A: PartialOrd<B> {
 818         #[inline]
 819         fn partial_cmp(&self, other: &&'b B) -> Option<Ordering> {
 820             PartialOrd::partial_cmp(*self, *other)
 821         }
 822         #[inline]
 823         fn lt(&self, other: & &'b B) -> bool { PartialOrd::lt(*self, *other) }
 824         #[inline]
 825         fn le(&self, other: & &'b B) -> bool { PartialOrd::le(*self, *other) }
 826         #[inline]
 827         fn ge(&self, other: & &'b B) -> bool { PartialOrd::ge(*self, *other) }
 828         #[inline]
 829         fn gt(&self, other: & &'b B) -> bool { PartialOrd::gt(*self, *other) }
 830     }
 831     #[stable(feature = "rust1", since = "1.0.0")]
 832     impl<'a, A: ?Sized> Ord for &'a A where A: Ord {
 833         #[inline]
 834         fn cmp(&self, other: & &'a A) -> Ordering { Ord::cmp(*self, *other) }
 835     }
 836     #[stable(feature = "rust1", since = "1.0.0")]
 837     impl<'a, A: ?Sized> Eq for &'a A where A: Eq {}
 838
 839     // &mut pointers
 840
 841     #[stable(feature = "rust1", since = "1.0.0")]
 842     impl<'a, 'b, A: ?Sized, B: ?Sized> PartialEq<&'b mut B> for &'a mut A where A: PartialEq<B> {
 843         #[inline]
 844         fn eq(&self, other: &&'b mut B) -> bool { PartialEq::eq(*self, *other) }
 845         #[inline]
 846         fn ne(&self, other: &&'b mut B) -> bool { PartialEq::ne(*self, *other) }
 847     }
 848     #[stable(feature = "rust1", since = "1.0.0")]
 849     impl<'a, 'b, A: ?Sized, B: ?Sized> PartialOrd<&'b mut B> for &'a mut A where A: PartialOrd<B> {
 850         #[inline]
 851         fn partial_cmp(&self, other: &&'b mut B) -> Option<Ordering> {
 852             PartialOrd::partial_cmp(*self, *other)
 853         }
 854         #[inline]
 855         fn lt(&self, other: &&'b mut B) -> bool { PartialOrd::lt(*self, *other) }
 856         #[inline]
 857         fn le(&self, other: &&'b mut B) -> bool { PartialOrd::le(*self, *other) }
 858         #[inline]
 859         fn ge(&self, other: &&'b mut B) -> bool { PartialOrd::ge(*self, *other) }
 860         #[inline]
 861         fn gt(&self, other: &&'b mut B) -> bool { PartialOrd::gt(*self, *other) }
 862     }
 863     #[stable(feature = "rust1", since = "1.0.0")]
 864     impl<'a, A: ?Sized> Ord for &'a mut A where A: Ord {
 865         #[inline]
 866         fn cmp(&self, other: &&'a mut A) -> Ordering { Ord::cmp(*self, *other) }
 867     }
 868     #[stable(feature = "rust1", since = "1.0.0")]
 869     impl<'a, A: ?Sized> Eq for &'a mut A where A: Eq {}
 870
 871     #[stable(feature = "rust1", since = "1.0.0")]
 872     impl<'a, 'b, A: ?Sized, B: ?Sized> PartialEq<&'b mut B> for &'a A where A: PartialEq<B> {
 873         #[inline]
 874         fn eq(&self, other: &&'b mut B) -> bool { PartialEq::eq(*self, *other) }
 875         #[inline]
 876         fn ne(&self, other: &&'b mut B) -> bool { PartialEq::ne(*self, *other) }
 877     }
 878
 879     #[stable(feature = "rust1", since = "1.0.0")]
 880     impl<'a, 'b, A: ?Sized, B: ?Sized> PartialEq<&'b B> for &'a mut A where A: PartialEq<B> {
 881         #[inline]
 882         fn eq(&self, other: &&'b B) -> bool { PartialEq::eq(*self, *other) }
 883         #[inline]
 884         fn ne(&self, other: &&'b B) -> bool { PartialEq::ne(*self, *other) }
 885     }
 886 }