///
/// This trait allows for partial equality, for types that do not have a full
/// equivalence relation. For example, in floating point numbers `NaN != NaN`,
-/// so floating point types implement `PartialEq` but not `Eq`.
+/// so floating point types implement `PartialEq` but not [`Eq`].
///
/// Formally, the equality must be (for all `a`, `b` and `c`):
///
///
/// ## How can I implement `PartialEq`?
///
-/// PartialEq only requires the `eq` method to be implemented; `ne` is defined
-/// in terms of it by default. Any manual implementation of `ne` *must* respect
-/// the rule that `eq` is a strict inverse of `ne`; that is, `!(a == b)` if and
+/// `PartialEq` only requires the [`eq`] method to be implemented; [`ne`] is defined
+/// in terms of it by default. Any manual implementation of [`ne`] *must* respect
+/// the rule that [`eq`] is a strict inverse of [`ne`]; that is, `!(a == b)` if and
/// only if `a != b`.
///
-/// Implementations of `PartialEq`, `PartialOrd`, and `Ord` *must* agree with
+/// Implementations of `PartialEq`, [`PartialOrd`], and [`Ord`] *must* agree with
/// each other. It's easy to accidentally make them disagree by deriving some
/// of the traits and manually implementing others.
///
/// assert_eq!(x == y, false);
/// assert_eq!(x.eq(&y), false);
/// ```
+///
+/// [`eq`]: PartialEq::eq
+/// [`ne`]: PartialEq::ne
#[lang = "eq"]
#[stable(feature = "rust1", since = "1.0.0")]
#[doc(alias = "==")]
/// - transitive: `a == b` and `b == c` implies `a == c`.
///
/// This property cannot be checked by the compiler, and therefore `Eq` implies
-/// `PartialEq`, and has no extra methods.
+/// [`PartialEq`], and has no extra methods.
///
/// ## Derivable
///
/// assert!(data == b);
/// ```
#[inline]
+ #[must_use]
#[stable(feature = "rust1", since = "1.0.0")]
pub fn reverse(self) -> Ordering {
match self {
/// Chains two orderings.
///
/// Returns `self` when it's not `Equal`. Otherwise returns `other`.
+ ///
/// # Examples
///
/// ```
/// assert_eq!(result, Ordering::Less);
/// ```
#[inline]
+ #[must_use]
#[stable(feature = "ordering_chaining", since = "1.17.0")]
pub fn then(self, other: Ordering) -> Ordering {
match self {
/// assert_eq!(result, Ordering::Less);
/// ```
#[inline]
+ #[must_use]
#[stable(feature = "ordering_chaining", since = "1.17.0")]
pub fn then_with<F: FnOnce() -> Ordering>(self, f: F) -> Ordering {
match self {
/// A helper struct for reverse ordering.
///
-/// This struct is a helper to be used with functions like `Vec::sort_by_key` and
+/// This struct is a helper to be used with functions like [`Vec::sort_by_key`] and
/// can be used to reverse order a part of a key.
///
-/// Example usage:
+/// [`Vec::sort_by_key`]: ../../std/vec/struct.Vec.html#method.sort_by_key
+///
+/// # Examples
///
/// ```
/// use std::cmp::Reverse;
///
/// ## How can I implement `Ord`?
///
-/// `Ord` requires that the type also be `PartialOrd` and `Eq` (which requires `PartialEq`).
+/// `Ord` requires that the type also be [`PartialOrd`] and [`Eq`] (which requires [`PartialEq`]).
///
-/// Then you must define an implementation for `cmp()`. You may find it useful to use
-/// `cmp()` on your type's fields.
+/// Then you must define an implementation for [`cmp`]. You may find it useful to use
+/// [`cmp`] on your type's fields.
///
-/// Implementations of `PartialEq`, `PartialOrd`, and `Ord` *must*
+/// Implementations of [`PartialEq`], [`PartialOrd`], and `Ord` *must*
/// agree with each other. That is, `a.cmp(b) == Ordering::Equal` if
/// and only if `a == b` and `Some(a.cmp(b)) == a.partial_cmp(b)` for
/// all `a` and `b`. It's easy to accidentally make them disagree by
/// }
/// }
/// ```
+///
+/// [`cmp`]: Ord::cmp
#[doc(alias = "<")]
#[doc(alias = ">")]
#[doc(alias = "<=")]
#[doc(alias = ">=")]
#[stable(feature = "rust1", since = "1.0.0")]
pub trait Ord: Eq + PartialOrd<Self> {
- /// This method returns an `Ordering` between `self` and `other`.
+ /// This method returns an [`Ordering`] between `self` and `other`.
///
/// By convention, `self.cmp(&other)` returns the ordering matching the expression
/// `self <operator> other` if true.
/// assert_eq!(10.cmp(&5), Ordering::Greater);
/// assert_eq!(5.cmp(&5), Ordering::Equal);
/// ```
+ #[must_use]
#[stable(feature = "rust1", since = "1.0.0")]
fn cmp(&self, other: &Self) -> Ordering;
/// ```
#[stable(feature = "ord_max_min", since = "1.21.0")]
#[inline]
+ #[must_use]
fn max(self, other: Self) -> Self
where
Self: Sized,
/// ```
#[stable(feature = "ord_max_min", since = "1.21.0")]
#[inline]
+ #[must_use]
fn min(self, other: Self) -> Self
where
Self: Sized,
/// assert!(0.clamp(-2, 1) == 0);
/// assert!(2.clamp(-2, 1) == 1);
/// ```
+ #[must_use]
#[unstable(feature = "clamp", issue = "44095")]
fn clamp(self, min: Self, max: Self) -> Self
where
///
/// ## How can I implement `PartialOrd`?
///
-/// `PartialOrd` only requires implementation of the `partial_cmp` method, with the others
+/// `PartialOrd` only requires implementation of the [`partial_cmp`] method, with the others
/// generated from default implementations.
///
/// However it remains possible to implement the others separately for types which do not have a
/// total order. For example, for floating point numbers, `NaN < 0 == false` and `NaN >= 0 ==
/// false` (cf. IEEE 754-2008 section 5.11).
///
-/// `PartialOrd` requires your type to be `PartialEq`.
+/// `PartialOrd` requires your type to be [`PartialEq`].
///
-/// Implementations of `PartialEq`, `PartialOrd`, and `Ord` *must* agree with each other. It's
+/// Implementations of [`PartialEq`], `PartialOrd`, and [`Ord`] *must* agree with each other. It's
/// easy to accidentally make them disagree by deriving some of the traits and manually
/// implementing others.
///
-/// If your type is `Ord`, you can implement `partial_cmp()` by using `cmp()`:
+/// If your type is [`Ord`], you can implement [`partial_cmp`] by using [`cmp`]:
///
/// ```
/// use std::cmp::Ordering;
/// }
/// ```
///
-/// You may also find it useful to use `partial_cmp()` on your type's fields. Here
+/// You may also find it useful to use [`partial_cmp`] on your type's fields. Here
/// is an example of `Person` types who have a floating-point `height` field that
/// is the only field to be used for sorting:
///
/// assert_eq!(x < y, true);
/// assert_eq!(x.lt(&y), true);
/// ```
+///
+/// [`partial_cmp`]: PartialOrd::partial_cmp
+/// [`cmp`]: Ord::cmp
#[lang = "partial_ord"]
#[stable(feature = "rust1", since = "1.0.0")]
#[doc(alias = ">")]
///
/// Returns the first argument if the comparison determines them to be equal.
///
-/// Internally uses an alias to `Ord::min`.
+/// Internally uses an alias to [`Ord::min`].
///
/// # Examples
///
/// assert_eq!(2, cmp::min(2, 2));
/// ```
#[inline]
+#[must_use]
#[stable(feature = "rust1", since = "1.0.0")]
pub fn min<T: Ord>(v1: T, v2: T) -> T {
v1.min(v2)
/// assert_eq!(cmp::min_by(-2, 2, |x: &i32, y: &i32| x.abs().cmp(&y.abs())), -2);
/// ```
#[inline]
+#[must_use]
#[unstable(feature = "cmp_min_max_by", issue = "64460")]
pub fn min_by<T, F: FnOnce(&T, &T) -> Ordering>(v1: T, v2: T, compare: F) -> T {
match compare(&v1, &v2) {
/// assert_eq!(cmp::min_by_key(-2, 2, |x: &i32| x.abs()), -2);
/// ```
#[inline]
+#[must_use]
#[unstable(feature = "cmp_min_max_by", issue = "64460")]
pub fn min_by_key<T, F: FnMut(&T) -> K, K: Ord>(v1: T, v2: T, mut f: F) -> T {
min_by(v1, v2, |v1, v2| f(v1).cmp(&f(v2)))
///
/// Returns the second argument if the comparison determines them to be equal.
///
-/// Internally uses an alias to `Ord::max`.
+/// Internally uses an alias to [`Ord::max`].
///
/// # Examples
///
/// assert_eq!(2, cmp::max(2, 2));
/// ```
#[inline]
+#[must_use]
#[stable(feature = "rust1", since = "1.0.0")]
pub fn max<T: Ord>(v1: T, v2: T) -> T {
v1.max(v2)
/// assert_eq!(cmp::max_by(-2, 2, |x: &i32, y: &i32| x.abs().cmp(&y.abs())), 2);
/// ```
#[inline]
+#[must_use]
#[unstable(feature = "cmp_min_max_by", issue = "64460")]
pub fn max_by<T, F: FnOnce(&T, &T) -> Ordering>(v1: T, v2: T, compare: F) -> T {
match compare(&v1, &v2) {
/// assert_eq!(cmp::max_by_key(-2, 2, |x: &i32| x.abs()), 2);
/// ```
#[inline]
+#[must_use]
#[unstable(feature = "cmp_min_max_by", issue = "64460")]
pub fn max_by_key<T, F: FnMut(&T) -> K, K: Ord>(v1: T, v2: T, mut f: F) -> T {
max_by(v1, v2, |v1, v2| f(v1).cmp(&f(v2)))
projects / rust.git / blobdiff