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.
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.
11 //! Functionality for ordering and comparison.
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.
18 #![stable(feature = "rust1", since = "1.0.0")]
20 use self::Ordering::*;
23 use option::Option::{self, Some};
25 /// Trait for equality comparisons which are [partial equivalence
26 /// relations](http://en.wikipedia.org/wiki/Partial_equivalence_relation).
28 /// This trait allows for partial equality, for types that do not have a full
29 /// equivalence relation. For example, in floating point numbers `NaN != NaN`,
30 /// so floating point types implement `PartialEq` but not `Eq`.
32 /// Formally, the equality must be (for all `a`, `b` and `c`):
34 /// - symmetric: `a == b` implies `b == a`; and
35 /// - transitive: `a == b` and `b == c` implies `a == c`.
37 /// Note that these requirements mean that the trait itself must be implemented
38 /// symmetrically and transitively: if `T: PartialEq<U>` and `U: PartialEq<V>`
39 /// then `U: PartialEq<T>` and `T: PartialEq<V>`.
41 /// PartialEq only requires the `eq` method to be implemented; `ne` is defined
42 /// in terms of it by default. Any manual implementation of `ne` *must* respect
43 /// the rule that `eq` is a strict inverse of `ne`; that is, `!(a == b)` if and
46 /// This trait can be used with `#[derive]`.
48 #[stable(feature = "rust1", since = "1.0.0")]
49 pub trait PartialEq<Rhs: ?Sized = Self> {
50 /// This method tests for `self` and `other` values to be equal, and is used
52 #[stable(feature = "rust1", since = "1.0.0")]
53 fn eq(&self, other: &Rhs) -> bool;
55 /// This method tests for `!=`.
57 #[stable(feature = "rust1", since = "1.0.0")]
58 fn ne(&self, other: &Rhs) -> bool { !self.eq(other) }
61 /// Trait for equality comparisons which are [equivalence relations](
62 /// https://en.wikipedia.org/wiki/Equivalence_relation).
64 /// This means, that in addition to `a == b` and `a != b` being strict inverses, the equality must
65 /// be (for all `a`, `b` and `c`):
67 /// - reflexive: `a == a`;
68 /// - symmetric: `a == b` implies `b == a`; and
69 /// - transitive: `a == b` and `b == c` implies `a == c`.
71 /// This property cannot be checked by the compiler, and therefore `Eq` implies
72 /// `PartialEq`, and has no extra methods.
74 /// This trait can be used with `#[derive]`.
75 #[stable(feature = "rust1", since = "1.0.0")]
76 pub trait Eq: PartialEq<Self> {
77 // FIXME #13101: this method is used solely by #[deriving] to
78 // assert that every component of a type implements #[deriving]
79 // itself, the current deriving infrastructure means doing this
80 // assertion without using a method on this trait is nearly
83 // This should never be implemented by hand.
86 #[stable(feature = "rust1", since = "1.0.0")]
87 fn assert_receiver_is_total_eq(&self) {}
90 /// An `Ordering` is the result of a comparison between two values.
95 /// use std::cmp::Ordering;
97 /// let result = 1.cmp(&2);
98 /// assert_eq!(Ordering::Less, result);
100 /// let result = 1.cmp(&1);
101 /// assert_eq!(Ordering::Equal, result);
103 /// let result = 2.cmp(&1);
104 /// assert_eq!(Ordering::Greater, result);
106 #[derive(Clone, Copy, PartialEq, Debug)]
107 #[stable(feature = "rust1", since = "1.0.0")]
109 /// An ordering where a compared value is less [than another].
110 #[stable(feature = "rust1", since = "1.0.0")]
112 /// An ordering where a compared value is equal [to another].
113 #[stable(feature = "rust1", since = "1.0.0")]
115 /// An ordering where a compared value is greater [than another].
116 #[stable(feature = "rust1", since = "1.0.0")]
121 /// Reverse the `Ordering`.
123 /// * `Less` becomes `Greater`.
124 /// * `Greater` becomes `Less`.
125 /// * `Equal` becomes `Equal`.
132 /// use std::cmp::Ordering;
134 /// assert_eq!(Ordering::Less.reverse(), Ordering::Greater);
135 /// assert_eq!(Ordering::Equal.reverse(), Ordering::Equal);
136 /// assert_eq!(Ordering::Greater.reverse(), Ordering::Less);
139 /// This method can be used to reverse a comparison:
142 /// let mut data: &mut [_] = &mut [2, 10, 5, 8];
144 /// // sort the array from largest to smallest.
145 /// data.sort_by(|a, b| a.cmp(b).reverse());
147 /// let b: &mut [_] = &mut [10, 8, 5, 2];
148 /// assert!(data == b);
151 #[stable(feature = "rust1", since = "1.0.0")]
152 pub fn reverse(self) -> Ordering {
161 /// Trait for types that form a [total order](https://en.wikipedia.org/wiki/Total_order).
163 /// An order is a total order if it is (for all `a`, `b` and `c`):
165 /// - total and antisymmetric: exactly one of `a < b`, `a == b` or `a > b` is true; and
166 /// - transitive, `a < b` and `b < c` implies `a < c`. The same must hold for both `==` and `>`.
168 /// This trait can be used with `#[derive]`. When `derive`d, it will produce a lexicographic
169 /// ordering based on the top-to-bottom declaration order of the struct's members.
170 #[stable(feature = "rust1", since = "1.0.0")]
171 pub trait Ord: Eq + PartialOrd<Self> {
172 /// This method returns an `Ordering` between `self` and `other`.
174 /// By convention, `self.cmp(&other)` returns the ordering matching the expression
175 /// `self <operator> other` if true.
180 /// use std::cmp::Ordering;
182 /// assert_eq!(5.cmp(&10), Ordering::Less);
183 /// assert_eq!(10.cmp(&5), Ordering::Greater);
184 /// assert_eq!(5.cmp(&5), Ordering::Equal);
186 #[stable(feature = "rust1", since = "1.0.0")]
187 fn cmp(&self, other: &Self) -> Ordering;
190 #[stable(feature = "rust1", since = "1.0.0")]
191 impl Eq for Ordering {}
193 #[stable(feature = "rust1", since = "1.0.0")]
194 impl Ord for Ordering {
196 fn cmp(&self, other: &Ordering) -> Ordering {
197 (*self as i32).cmp(&(*other as i32))
201 #[stable(feature = "rust1", since = "1.0.0")]
202 impl PartialOrd for Ordering {
204 fn partial_cmp(&self, other: &Ordering) -> Option<Ordering> {
205 (*self as i32).partial_cmp(&(*other as i32))
209 /// Trait for values that can be compared for a sort-order.
211 /// The comparison must satisfy, for all `a`, `b` and `c`:
213 /// - antisymmetry: if `a < b` then `!(a > b)`, as well as `a > b` implying `!(a < b)`; and
214 /// - transitivity: `a < b` and `b < c` implies `a < c`. The same must hold for both `==` and `>`.
216 /// Note that these requirements mean that the trait itself must be implemented symmetrically and
217 /// transitively: if `T: PartialOrd<U>` and `U: PartialOrd<V>` then `U: PartialOrd<T>` and `T:
220 /// PartialOrd only requires implementation of the `partial_cmp` method, with the others generated
221 /// from default implementations.
223 /// However it remains possible to implement the others separately for types which do not have a
224 /// total order. For example, for floating point numbers, `NaN < 0 == false` and `NaN >= 0 ==
225 /// false` (cf. IEEE 754-2008 section 5.11).
227 /// This trait can be used with `#[derive]`. When `derive`d, it will produce an ordering
228 /// based on the top-to-bottom declaration order of the struct's members.
230 #[stable(feature = "rust1", since = "1.0.0")]
231 pub trait PartialOrd<Rhs: ?Sized = Self>: PartialEq<Rhs> {
232 /// This method returns an ordering between `self` and `other` values if one exists.
237 /// use std::cmp::Ordering;
239 /// let result = 1.0.partial_cmp(&2.0);
240 /// assert_eq!(result, Some(Ordering::Less));
242 /// let result = 1.0.partial_cmp(&1.0);
243 /// assert_eq!(result, Some(Ordering::Equal));
245 /// let result = 2.0.partial_cmp(&1.0);
246 /// assert_eq!(result, Some(Ordering::Greater));
249 /// When comparison is impossible:
252 /// let result = std::f64::NAN.partial_cmp(&1.0);
253 /// assert_eq!(result, None);
255 #[stable(feature = "rust1", since = "1.0.0")]
256 fn partial_cmp(&self, other: &Rhs) -> Option<Ordering>;
258 /// This method tests less than (for `self` and `other`) and is used by the `<` operator.
263 /// let result = 1.0 < 2.0;
264 /// assert_eq!(result, true);
266 /// let result = 2.0 < 1.0;
267 /// assert_eq!(result, false);
270 #[stable(feature = "rust1", since = "1.0.0")]
271 fn lt(&self, other: &Rhs) -> bool {
272 match self.partial_cmp(other) {
278 /// This method tests less than or equal to (for `self` and `other`) and is used by the `<=`
284 /// let result = 1.0 <= 2.0;
285 /// assert_eq!(result, true);
287 /// let result = 2.0 <= 2.0;
288 /// assert_eq!(result, true);
291 #[stable(feature = "rust1", since = "1.0.0")]
292 fn le(&self, other: &Rhs) -> bool {
293 match self.partial_cmp(other) {
294 Some(Less) | Some(Equal) => true,
299 /// This method tests greater than (for `self` and `other`) and is used by the `>` operator.
304 /// let result = 1.0 > 2.0;
305 /// assert_eq!(result, false);
307 /// let result = 2.0 > 2.0;
308 /// assert_eq!(result, false);
311 #[stable(feature = "rust1", since = "1.0.0")]
312 fn gt(&self, other: &Rhs) -> bool {
313 match self.partial_cmp(other) {
314 Some(Greater) => true,
319 /// This method tests greater than or equal to (for `self` and `other`) and is used by the `>=`
325 /// let result = 2.0 >= 1.0;
326 /// assert_eq!(result, true);
328 /// let result = 2.0 >= 2.0;
329 /// assert_eq!(result, true);
332 #[stable(feature = "rust1", since = "1.0.0")]
333 fn ge(&self, other: &Rhs) -> bool {
334 match self.partial_cmp(other) {
335 Some(Greater) | Some(Equal) => true,
341 /// Compare and return the minimum of two values.
343 /// Returns the first argument if the comparison determines them to be equal.
350 /// assert_eq!(1, cmp::min(1, 2));
351 /// assert_eq!(2, cmp::min(2, 2));
354 #[stable(feature = "rust1", since = "1.0.0")]
355 pub fn min<T: Ord>(v1: T, v2: T) -> T {
356 if v1 <= v2 { v1 } else { v2 }
359 /// Compare and return the maximum of two values.
361 /// Returns the second argument if the comparison determines them to be equal.
368 /// assert_eq!(2, cmp::max(1, 2));
369 /// assert_eq!(2, cmp::max(2, 2));
372 #[stable(feature = "rust1", since = "1.0.0")]
373 pub fn max<T: Ord>(v1: T, v2: T) -> T {
374 if v2 >= v1 { v2 } else { v1 }
377 // Implementation of PartialEq, Eq, PartialOrd and Ord for primitive types
379 use cmp::{PartialOrd, Ord, PartialEq, Eq, Ordering};
380 use cmp::Ordering::{Less, Greater, Equal};
383 use option::Option::{Some, None};
385 macro_rules! partial_eq_impl {
387 #[stable(feature = "rust1", since = "1.0.0")]
388 impl PartialEq for $t {
390 fn eq(&self, other: &$t) -> bool { (*self) == (*other) }
392 fn ne(&self, other: &$t) -> bool { (*self) != (*other) }
397 #[stable(feature = "rust1", since = "1.0.0")]
398 impl PartialEq for () {
400 fn eq(&self, _other: &()) -> bool { true }
402 fn ne(&self, _other: &()) -> bool { false }
406 bool char usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64
409 macro_rules! eq_impl {
411 #[stable(feature = "rust1", since = "1.0.0")]
416 eq_impl! { () bool char usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
418 macro_rules! partial_ord_impl {
420 #[stable(feature = "rust1", since = "1.0.0")]
421 impl PartialOrd for $t {
423 fn partial_cmp(&self, other: &$t) -> Option<Ordering> {
424 match (self <= other, self >= other) {
425 (false, false) => None,
426 (false, true) => Some(Greater),
427 (true, false) => Some(Less),
428 (true, true) => Some(Equal),
432 fn lt(&self, other: &$t) -> bool { (*self) < (*other) }
434 fn le(&self, other: &$t) -> bool { (*self) <= (*other) }
436 fn ge(&self, other: &$t) -> bool { (*self) >= (*other) }
438 fn gt(&self, other: &$t) -> bool { (*self) > (*other) }
443 #[stable(feature = "rust1", since = "1.0.0")]
444 impl PartialOrd for () {
446 fn partial_cmp(&self, _: &()) -> Option<Ordering> {
451 #[stable(feature = "rust1", since = "1.0.0")]
452 impl PartialOrd for bool {
454 fn partial_cmp(&self, other: &bool) -> Option<Ordering> {
455 (*self as u8).partial_cmp(&(*other as u8))
459 partial_ord_impl! { f32 f64 }
461 macro_rules! ord_impl {
463 #[stable(feature = "rust1", since = "1.0.0")]
464 impl PartialOrd for $t {
466 fn partial_cmp(&self, other: &$t) -> Option<Ordering> {
467 Some(self.cmp(other))
470 fn lt(&self, other: &$t) -> bool { (*self) < (*other) }
472 fn le(&self, other: &$t) -> bool { (*self) <= (*other) }
474 fn ge(&self, other: &$t) -> bool { (*self) >= (*other) }
476 fn gt(&self, other: &$t) -> bool { (*self) > (*other) }
479 #[stable(feature = "rust1", since = "1.0.0")]
482 fn cmp(&self, other: &$t) -> Ordering {
483 if *self == *other { Equal }
484 else if *self < *other { Less }
491 #[stable(feature = "rust1", since = "1.0.0")]
494 fn cmp(&self, _other: &()) -> Ordering { Equal }
497 #[stable(feature = "rust1", since = "1.0.0")]
500 fn cmp(&self, other: &bool) -> Ordering {
501 (*self as u8).cmp(&(*other as u8))
505 ord_impl! { char usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
509 #[stable(feature = "rust1", since = "1.0.0")]
510 impl<'a, 'b, A: ?Sized, B: ?Sized> PartialEq<&'b B> for &'a A where A: PartialEq<B> {
512 fn eq(&self, other: & &'b B) -> bool { PartialEq::eq(*self, *other) }
514 fn ne(&self, other: & &'b B) -> bool { PartialEq::ne(*self, *other) }
516 #[stable(feature = "rust1", since = "1.0.0")]
517 impl<'a, 'b, A: ?Sized, B: ?Sized> PartialOrd<&'b B> for &'a A where A: PartialOrd<B> {
519 fn partial_cmp(&self, other: &&'b B) -> Option<Ordering> {
520 PartialOrd::partial_cmp(*self, *other)
523 fn lt(&self, other: & &'b B) -> bool { PartialOrd::lt(*self, *other) }
525 fn le(&self, other: & &'b B) -> bool { PartialOrd::le(*self, *other) }
527 fn ge(&self, other: & &'b B) -> bool { PartialOrd::ge(*self, *other) }
529 fn gt(&self, other: & &'b B) -> bool { PartialOrd::gt(*self, *other) }
531 #[stable(feature = "rust1", since = "1.0.0")]
532 impl<'a, A: ?Sized> Ord for &'a A where A: Ord {
534 fn cmp(&self, other: & &'a A) -> Ordering { Ord::cmp(*self, *other) }
536 #[stable(feature = "rust1", since = "1.0.0")]
537 impl<'a, A: ?Sized> Eq for &'a A where A: Eq {}
541 #[stable(feature = "rust1", since = "1.0.0")]
542 impl<'a, 'b, A: ?Sized, B: ?Sized> PartialEq<&'b mut B> for &'a mut A where A: PartialEq<B> {
544 fn eq(&self, other: &&'b mut B) -> bool { PartialEq::eq(*self, *other) }
546 fn ne(&self, other: &&'b mut B) -> bool { PartialEq::ne(*self, *other) }
548 #[stable(feature = "rust1", since = "1.0.0")]
549 impl<'a, 'b, A: ?Sized, B: ?Sized> PartialOrd<&'b mut B> for &'a mut A where A: PartialOrd<B> {
551 fn partial_cmp(&self, other: &&'b mut B) -> Option<Ordering> {
552 PartialOrd::partial_cmp(*self, *other)
555 fn lt(&self, other: &&'b mut B) -> bool { PartialOrd::lt(*self, *other) }
557 fn le(&self, other: &&'b mut B) -> bool { PartialOrd::le(*self, *other) }
559 fn ge(&self, other: &&'b mut B) -> bool { PartialOrd::ge(*self, *other) }
561 fn gt(&self, other: &&'b mut B) -> bool { PartialOrd::gt(*self, *other) }
563 #[stable(feature = "rust1", since = "1.0.0")]
564 impl<'a, A: ?Sized> Ord for &'a mut A where A: Ord {
566 fn cmp(&self, other: &&'a mut A) -> Ordering { Ord::cmp(*self, *other) }
568 #[stable(feature = "rust1", since = "1.0.0")]
569 impl<'a, A: ?Sized> Eq for &'a mut A where A: Eq {}
571 #[stable(feature = "rust1", since = "1.0.0")]
572 impl<'a, 'b, A: ?Sized, B: ?Sized> PartialEq<&'b mut B> for &'a A where A: PartialEq<B> {
574 fn eq(&self, other: &&'b mut B) -> bool { PartialEq::eq(*self, *other) }
576 fn ne(&self, other: &&'b mut B) -> bool { PartialEq::ne(*self, *other) }
579 #[stable(feature = "rust1", since = "1.0.0")]
580 impl<'a, 'b, A: ?Sized, B: ?Sized> PartialEq<&'b B> for &'a mut A where A: PartialEq<B> {
582 fn eq(&self, other: &&'b B) -> bool { PartialEq::eq(*self, *other) }
584 fn ne(&self, other: &&'b B) -> bool { PartialEq::ne(*self, *other) }