From 169c59ff0fcbd606c6f639c2318f71b51f6c9207 Mon Sep 17 00:00:00 2001
From: Lyndon Brown <jnqnfe@gmail.com>
Date: Thu, 10 Dec 2020 07:00:17 +0000
Subject: [PATCH] Add some core::cmp::Ordering helpers

...to allow easier greater-than-or-equal-to and less-than-or-equal-to
comparisons, and variant checking without needing to import the enum,
similar to `Option::is_none()` / `Option::is_some()`, in situations where
you are dealing with an `Ordering` value. (Simple `PartialOrd` / `Ord`
based evaluation may not be suitable for all situations).

Prior to Rust 1.42 a greater-than-or-equal-to comparison might be written
either as a match block, or a traditional conditional check like this:

```rust
if cmp == Ordering::Equal || cmp == Ordering::Greater {
    // Do something
}
```

Which requires two instances of `cmp`. Don't forget that while `cmp` here
is very short, it could be something much longer in real use cases.

From Rust 1.42 a nicer alternative is possible:

```rust
if matches!(cmp, Ordering::Equal | Ordering::Greater) {
    // Do something
}
```

The commit adds another alternative which may be even better in some cases:

```rust
if cmp.is_ge() {
    // Do something
}
```

The earlier examples could be cleaner than they are if the variants of
`Ordering` are imported such that `Equal`, `Greater` and `Less` can be
referred to directly, but not everyone will want to do that.

The new solution can shorten lines, help avoid logic mistakes, and avoids
having to import `Ordering` / `Ordering::*`.
---
 library/core/src/cmp.rs | 114 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 114 insertions(+)

diff --git a/library/core/src/cmp.rs b/library/core/src/cmp.rs
index 47ae1a64190ed..f752472c3ba80 100644
--- a/library/core/src/cmp.rs
+++ b/library/core/src/cmp.rs
@@ -325,6 +325,120 @@ pub enum Ordering {
 }
 
 impl Ordering {
+    /// Returns `true` if the ordering is the `Equal` variant.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(ordering_helpers)]
+    /// use std::cmp::Ordering;
+    ///
+    /// assert_eq!(Ordering::Less.is_eq(), false);
+    /// assert_eq!(Ordering::Equal.is_eq(), true);
+    /// assert_eq!(Ordering::Greater.is_eq(), false);
+    /// ```
+    #[inline]
+    #[must_use]
+    #[unstable(feature = "ordering_helpers", issue = "79885")]
+    pub const fn is_eq(self) -> bool {
+        matches!(self, Equal)
+    }
+
+    /// Returns `true` if the ordering is not the `Equal` variant.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(ordering_helpers)]
+    /// use std::cmp::Ordering;
+    ///
+    /// assert_eq!(Ordering::Less.is_ne(), true);
+    /// assert_eq!(Ordering::Equal.is_ne(), false);
+    /// assert_eq!(Ordering::Greater.is_ne(), true);
+    /// ```
+    #[inline]
+    #[must_use]
+    #[unstable(feature = "ordering_helpers", issue = "79885")]
+    pub const fn is_ne(self) -> bool {
+        !matches!(self, Equal)
+    }
+
+    /// Returns `true` if the ordering is the `Less` variant.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(ordering_helpers)]
+    /// use std::cmp::Ordering;
+    ///
+    /// assert_eq!(Ordering::Less.is_lt(), true);
+    /// assert_eq!(Ordering::Equal.is_lt(), false);
+    /// assert_eq!(Ordering::Greater.is_lt(), false);
+    /// ```
+    #[inline]
+    #[must_use]
+    #[unstable(feature = "ordering_helpers", issue = "79885")]
+    pub const fn is_lt(self) -> bool {
+        matches!(self, Less)
+    }
+
+    /// Returns `true` if the ordering is the `Greater` variant.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(ordering_helpers)]
+    /// use std::cmp::Ordering;
+    ///
+    /// assert_eq!(Ordering::Less.is_gt(), false);
+    /// assert_eq!(Ordering::Equal.is_gt(), false);
+    /// assert_eq!(Ordering::Greater.is_gt(), true);
+    /// ```
+    #[inline]
+    #[must_use]
+    #[unstable(feature = "ordering_helpers", issue = "79885")]
+    pub const fn is_gt(self) -> bool {
+        matches!(self, Greater)
+    }
+
+    /// Returns `true` if the ordering is either the `Less` or `Equal` variant.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(ordering_helpers)]
+    /// use std::cmp::Ordering;
+    ///
+    /// assert_eq!(Ordering::Less.is_le(), true);
+    /// assert_eq!(Ordering::Equal.is_le(), true);
+    /// assert_eq!(Ordering::Greater.is_le(), false);
+    /// ```
+    #[inline]
+    #[must_use]
+    #[unstable(feature = "ordering_helpers", issue = "79885")]
+    pub const fn is_le(self) -> bool {
+        !matches!(self, Greater)
+    }
+
+    /// Returns `true` if the ordering is either the `Greater` or `Equal` variant.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(ordering_helpers)]
+    /// use std::cmp::Ordering;
+    ///
+    /// assert_eq!(Ordering::Less.is_ge(), false);
+    /// assert_eq!(Ordering::Equal.is_ge(), true);
+    /// assert_eq!(Ordering::Greater.is_ge(), true);
+    /// ```
+    #[inline]
+    #[must_use]
+    #[unstable(feature = "ordering_helpers", issue = "79885")]
+    pub const fn is_ge(self) -> bool {
+        !matches!(self, Less)
+    }
+
     /// Reverses the `Ordering`.
     ///
     /// * `Less` becomes `Greater`.