16 Language support library [language.support]

16.11 Comparisons [cmp]

16.11.1 Header <compare> synopsis [compare.syn]

1
#
The header <compare> specifies types, objects, and functions for use primarily in connection with the three-way comparison operator.
namespace std {
  // [cmp.categories], comparison category types
  class weak_equality;
  class strong_equality;
  class partial_ordering;
  class weak_ordering;
  class strong_ordering;

  // named comparison functions
  constexpr bool is_eq  (weak_equality cmp) noexcept    { return cmp == 0; }
  constexpr bool is_neq (weak_equality cmp) noexcept    { return cmp != 0; }
  constexpr bool is_lt  (partial_ordering cmp) noexcept { return cmp < 0; }
  constexpr bool is_lteq(partial_ordering cmp) noexcept { return cmp <= 0; }
  constexpr bool is_gt  (partial_ordering cmp) noexcept { return cmp > 0; }
  constexpr bool is_gteq(partial_ordering cmp) noexcept { return cmp >= 0; }

  // [cmp.common], common comparison category type
  template<class... Ts>
  struct common_comparison_category {
    using type = see below;
  };
  template<class... Ts>
    using common_comparison_category_t = typename common_comparison_category<Ts...>::type;

  // [cmp.alg], comparison algorithms
  template<class T> constexpr strong_ordering strong_order(const T& a, const T& b);
  template<class T> constexpr weak_ordering weak_order(const T& a, const T& b);
  template<class T> constexpr partial_ordering partial_order(const T& a, const T& b);
  template<class T> constexpr strong_equality strong_equal(const T& a, const T& b);
  template<class T> constexpr weak_equality weak_equal(const T& a, const T& b);
}

16.11.2 Comparison category types [cmp.categories]

16.11.2.1 Preamble [cmp.categories.pre]

1
#
The types weak_­equality, strong_­equality, partial_­ordering, weak_­ordering, and strong_­ordering are collectively termed the comparison category types.
Each is specified in terms of an exposition-only data member named value whose value typically corresponds to that of an enumerator from one of the following exposition-only enumerations:
enum class eq { equal = 0, equivalent = equal,
                nonequal = 1, nonequivalent = nonequal };   // exposition only
enum class ord { less = -1, greater = 1 };                  // exposition only
enum class ncmp { unordered = -127 };                       // exposition only
2
#
[ Note
:
The types strong_­ordering and weak_­equality correspond, respectively, to the terms total ordering and equivalence in mathematics.
— end note
 ]
3
#
The relational and equality operators for the comparison category types are specified with an anonymous parameter of unspecified type.
This type shall be selected by the implementation such that these parameters can accept literal 0 as a corresponding argument.
[ Example
:
nullptr_­t satisfies this requirement.
— end example
 ]
In this context, the behavior of a program that supplies an argument other than a literal 0 is undefined.
4
#
For the purposes of this subclause, substitutability is the property that f(a) == f(b) is true whenever a == b is true, where f denotes a function that reads only comparison-salient state that is accessible via the argument's public const members.

16.11.2.2 Class weak_­equality [cmp.weakeq]

1
#
The weak_­equality type is typically used as the result type of a three-way comparison operator that (a) admits only equality and inequality comparisons, and (b) does not imply substitutability.
namespace std {
  class weak_equality {
    int value;  // exposition only

    // exposition-only constructor
    explicit constexpr weak_equality(eq v) noexcept : value(int(v)) {}  // exposition only

  public:
    // valid values
    static const weak_equality equivalent;
    static const weak_equality nonequivalent;

    // comparisons
    friend constexpr bool operator==(weak_equality v, unspecified) noexcept;
    friend constexpr bool operator!=(weak_equality v, unspecified) noexcept;
    friend constexpr bool operator==(unspecified, weak_equality v) noexcept;
    friend constexpr bool operator!=(unspecified, weak_equality v) noexcept;
    friend constexpr weak_equality operator<=>(weak_equality v, unspecified) noexcept;
    friend constexpr weak_equality operator<=>(unspecified, weak_equality v) noexcept;
  };

  // valid values' definitions
  inline constexpr weak_equality weak_equality::equivalent(eq::equivalent);
  inline constexpr weak_equality weak_equality::nonequivalent(eq::nonequivalent);
}
🔗
constexpr bool operator==(weak_equality v, unspecified) noexcept; constexpr bool operator==(unspecified, weak_equality v) noexcept;
2
#
Returns: v.value == 0.
🔗
constexpr bool operator!=(weak_equality v, unspecified) noexcept; constexpr bool operator!=(unspecified, weak_equality v) noexcept;
3
#
Returns: v.value != 0.
🔗
constexpr weak_equality operator<=>(weak_equality v, unspecified) noexcept; constexpr weak_equality operator<=>(unspecified, weak_equality v) noexcept;
4
#
Returns: v.

16.11.2.3 Class strong_­equality [cmp.strongeq]

1
#
The strong_­equality type is typically used as the result type of a three-way comparison operator that (a) admits only equality and inequality comparisons, and (b) does imply substitutability.
namespace std {
  class strong_equality {
    int value;  // exposition only

    // exposition-only constructor
    explicit constexpr strong_equality(eq v) noexcept : value(int(v)) {}    // exposition only

  public:
    // valid values
    static const strong_equality equal;
    static const strong_equality nonequal;
    static const strong_equality equivalent;
    static const strong_equality nonequivalent;

    // conversion
    constexpr operator weak_equality() const noexcept;

    // comparisons
    friend constexpr bool operator==(strong_equality v, unspecified) noexcept;
    friend constexpr bool operator!=(strong_equality v, unspecified) noexcept;
    friend constexpr bool operator==(unspecified, strong_equality v) noexcept;
    friend constexpr bool operator!=(unspecified, strong_equality v) noexcept;
    friend constexpr strong_equality operator<=>(strong_equality v, unspecified) noexcept;
    friend constexpr strong_equality operator<=>(unspecified, strong_equality v) noexcept;
  };

  // valid values' definitions
  inline constexpr strong_equality strong_equality::equal(eq::equal);
  inline constexpr strong_equality strong_equality::nonequal(eq::nonequal);
  inline constexpr strong_equality strong_equality::equivalent(eq::equivalent);
  inline constexpr strong_equality strong_equality::nonequivalent(eq::nonequivalent);
}
🔗
constexpr operator weak_equality() const noexcept;
2
#
Returns: value == 0 ? weak_­equality​::​equivalent : weak_­equality​::​nonequivalent.
🔗
constexpr bool operator==(strong_equality v, unspecified) noexcept; constexpr bool operator==(unspecified, strong_equality v) noexcept;
3
#
Returns: v.value == 0.
🔗
constexpr bool operator!=(strong_equality v, unspecified) noexcept; constexpr bool operator!=(unspecified, strong_equality v) noexcept;
4
#
Returns: v.value != 0.
🔗
constexpr strong_equality operator<=>(strong_equality v, unspecified) noexcept; constexpr strong_equality operator<=>(unspecified, strong_equality v) noexcept;
5
#
Returns: v.

16.11.2.4 Class partial_­ordering [cmp.partialord]

1
#
The partial_­ordering type is typically used as the result type of a three-way comparison operator that (a) admits all of the six two-way comparison operators ([expr.rel], [expr.eq]), (b) does not imply substitutability, and (c) permits two values to be incomparable.221
namespace std {
  class partial_ordering {
    int value;          // exposition only
    bool is_ordered;    // exposition only

    // exposition-only constructors
    explicit constexpr
      partial_ordering(eq v) noexcept : value(int(v)), is_ordered(true) {}      // exposition only
    explicit constexpr
      partial_ordering(ord v) noexcept : value(int(v)), is_ordered(true) {}     // exposition only
    explicit constexpr
      partial_ordering(ncmp v) noexcept : value(int(v)), is_ordered(false) {}   // exposition only

  public:
    // valid values
    static const partial_ordering less;
    static const partial_ordering equivalent;
    static const partial_ordering greater;
    static const partial_ordering unordered;

    // conversion
    constexpr operator weak_equality() const noexcept;

    // comparisons
    friend constexpr bool operator==(partial_ordering v, unspecified) noexcept;
    friend constexpr bool operator!=(partial_ordering v, unspecified) noexcept;
    friend constexpr bool operator< (partial_ordering v, unspecified) noexcept;
    friend constexpr bool operator> (partial_ordering v, unspecified) noexcept;
    friend constexpr bool operator<=(partial_ordering v, unspecified) noexcept;
    friend constexpr bool operator>=(partial_ordering v, unspecified) noexcept;
    friend constexpr bool operator==(unspecified, partial_ordering v) noexcept;
    friend constexpr bool operator!=(unspecified, partial_ordering v) noexcept;
    friend constexpr bool operator< (unspecified, partial_ordering v) noexcept;
    friend constexpr bool operator> (unspecified, partial_ordering v) noexcept;
    friend constexpr bool operator<=(unspecified, partial_ordering v) noexcept;
    friend constexpr bool operator>=(unspecified, partial_ordering v) noexcept;
    friend constexpr partial_ordering operator<=>(partial_ordering v, unspecified) noexcept;
    friend constexpr partial_ordering operator<=>(unspecified, partial_ordering v) noexcept;
  };

  // valid values' definitions
  inline constexpr partial_ordering partial_ordering::less(ord::less);
  inline constexpr partial_ordering partial_ordering::equivalent(eq::equivalent);
  inline constexpr partial_ordering partial_ordering::greater(ord::greater);
  inline constexpr partial_ordering partial_ordering::unordered(ncmp::unordered);
}
🔗
constexpr operator weak_equality() const noexcept;
2
#
Returns: value == 0 ? weak_­equality​::​equivalent : weak_­equality​::​nonequivalent.
[ Note
:
The result is independent of the is_­ordered member.
— end note
 ]
🔗
constexpr bool operator==(partial_ordering v, unspecified) noexcept; constexpr bool operator< (partial_ordering v, unspecified) noexcept; constexpr bool operator> (partial_ordering v, unspecified) noexcept; constexpr bool operator<=(partial_ordering v, unspecified) noexcept; constexpr bool operator>=(partial_ordering v, unspecified) noexcept;
3
#
Returns: For operator@, v.is_­ordered && v.value @ 0.
🔗
constexpr bool operator==(unspecified, partial_ordering v) noexcept; constexpr bool operator< (unspecified, partial_ordering v) noexcept; constexpr bool operator> (unspecified, partial_ordering v) noexcept; constexpr bool operator<=(unspecified, partial_ordering v) noexcept; constexpr bool operator>=(unspecified, partial_ordering v) noexcept;
4
#
Returns: For operator@, v.is_­ordered && 0 @ v.value.
🔗
constexpr bool operator!=(partial_ordering v, unspecified) noexcept; constexpr bool operator!=(unspecified, partial_ordering v) noexcept;
5
#
Returns: For operator@, !v.is_­ordered || v.value != 0.
🔗
constexpr partial_ordering operator<=>(partial_ordering v, unspecified) noexcept;
6
#
Returns: v.
🔗
constexpr partial_ordering operator<=>(unspecified, partial_ordering v) noexcept;
7
#
Returns: v < 0 ? partial_­ordering​::​greater : v > 0 ? partial_­ordering​::​less : v.
221)
That is, a < b, a == b, and a > b might all be false.

16.11.2.5 Class weak_­ordering [cmp.weakord]

1
#
The weak_­ordering type is typically used as the result type of a three-way comparison operator that (a) admits all of the six two-way comparison operators ([expr.rel], [expr.eq]), and (b) does not imply substitutability.
namespace std {
  class weak_ordering {
    int value;  // exposition only

    // exposition-only constructors
    explicit constexpr weak_ordering(eq v) noexcept : value(int(v)) {}  // exposition only
    explicit constexpr weak_ordering(ord v) noexcept : value(int(v)) {} // exposition only

  public:
    // valid values
    static const weak_ordering less;
    static const weak_ordering equivalent;
    static const weak_ordering greater;

    // conversions
    constexpr operator weak_equality() const noexcept;
    constexpr operator partial_ordering() const noexcept;

    // comparisons
    friend constexpr bool operator==(weak_ordering v, unspecified) noexcept;
    friend constexpr bool operator!=(weak_ordering v, unspecified) noexcept;
    friend constexpr bool operator< (weak_ordering v, unspecified) noexcept;
    friend constexpr bool operator> (weak_ordering v, unspecified) noexcept;
    friend constexpr bool operator<=(weak_ordering v, unspecified) noexcept;
    friend constexpr bool operator>=(weak_ordering v, unspecified) noexcept;
    friend constexpr bool operator==(unspecified, weak_ordering v) noexcept;
    friend constexpr bool operator!=(unspecified, weak_ordering v) noexcept;
    friend constexpr bool operator< (unspecified, weak_ordering v) noexcept;
    friend constexpr bool operator> (unspecified, weak_ordering v) noexcept;
    friend constexpr bool operator<=(unspecified, weak_ordering v) noexcept;
    friend constexpr bool operator>=(unspecified, weak_ordering v) noexcept;
    friend constexpr weak_ordering operator<=>(weak_ordering v, unspecified) noexcept;
    friend constexpr weak_ordering operator<=>(unspecified, weak_ordering v) noexcept;
  };

  // valid values' definitions
  inline constexpr weak_ordering weak_ordering::less(ord::less);
  inline constexpr weak_ordering weak_ordering::equivalent(eq::equivalent);
  inline constexpr weak_ordering weak_ordering::greater(ord::greater);
}
🔗
constexpr operator weak_equality() const noexcept;
2
#
Returns: value == 0 ? weak_­equality​::​equivalent : weak_­equality​::​nonequivalent.
🔗
constexpr operator partial_ordering() const noexcept;
3
#
Returns: 
value == 0 ? partial_ordering::equivalent :
value < 0  ? partial_ordering::less :
             partial_ordering::greater
🔗
constexpr bool operator==(weak_ordering v, unspecified) noexcept; constexpr bool operator!=(weak_ordering v, unspecified) noexcept; constexpr bool operator< (weak_ordering v, unspecified) noexcept; constexpr bool operator> (weak_ordering v, unspecified) noexcept; constexpr bool operator<=(weak_ordering v, unspecified) noexcept; constexpr bool operator>=(weak_ordering v, unspecified) noexcept;
4
#
Returns: v.value @ 0 for operator@.
🔗
constexpr bool operator==(unspecified, weak_ordering v) noexcept; constexpr bool operator!=(unspecified, weak_ordering v) noexcept; constexpr bool operator< (unspecified, weak_ordering v) noexcept; constexpr bool operator> (unspecified, weak_ordering v) noexcept; constexpr bool operator<=(unspecified, weak_ordering v) noexcept; constexpr bool operator>=(unspecified, weak_ordering v) noexcept;
5
#
Returns: 0 @ v.value for operator@.
🔗
constexpr weak_ordering operator<=>(weak_ordering v, unspecified) noexcept;
6
#
Returns: v.
🔗
constexpr weak_ordering operator<=>(unspecified, weak_ordering v) noexcept;
7
#
Returns: v < 0 ? weak_­ordering​::​greater : v > 0 ? weak_­ordering​::​less : v.

16.11.2.6 Class strong_­ordering [cmp.strongord]

1
#
The strong_­ordering type is typically used as the result type of a three-way comparison operator that (a) admits all of the six two-way comparison operators ([expr.rel], [expr.eq]), and (b) does imply substitutability.
namespace std {
  class strong_ordering {
    int value;  // exposition only

    // exposition-only constructors
    explicit constexpr strong_ordering(eq v) noexcept : value(int(v)) {}    // exposition only
    explicit constexpr strong_ordering(ord v) noexcept : value(int(v)) {}   // exposition only

  public:
    // valid values
    static const strong_ordering less;
    static const strong_ordering equal;
    static const strong_ordering equivalent;
    static const strong_ordering greater;

    // conversions
    constexpr operator weak_equality() const noexcept;
    constexpr operator strong_equality() const noexcept;
    constexpr operator partial_ordering() const noexcept;
    constexpr operator weak_ordering() const noexcept;

    // comparisons
    friend constexpr bool operator==(strong_ordering v, unspecified) noexcept;
    friend constexpr bool operator!=(strong_ordering v, unspecified) noexcept;
    friend constexpr bool operator< (strong_ordering v, unspecified) noexcept;
    friend constexpr bool operator> (strong_ordering v, unspecified) noexcept;
    friend constexpr bool operator<=(strong_ordering v, unspecified) noexcept;
    friend constexpr bool operator>=(strong_ordering v, unspecified) noexcept;
    friend constexpr bool operator==(unspecified, strong_ordering v) noexcept;
    friend constexpr bool operator!=(unspecified, strong_ordering v) noexcept;
    friend constexpr bool operator< (unspecified, strong_ordering v) noexcept;
    friend constexpr bool operator> (unspecified, strong_ordering v) noexcept;
    friend constexpr bool operator<=(unspecified, strong_ordering v) noexcept;
    friend constexpr bool operator>=(unspecified, strong_ordering v) noexcept;
    friend constexpr strong_ordering operator<=>(strong_ordering v, unspecified) noexcept;
    friend constexpr strong_ordering operator<=>(unspecified, strong_ordering v) noexcept;
  };

  // valid values' definitions
  inline constexpr strong_ordering strong_ordering::less(ord::less);
  inline constexpr strong_ordering strong_ordering::equal(eq::equal);
  inline constexpr strong_ordering strong_ordering::equivalent(eq::equivalent);
  inline constexpr strong_ordering strong_ordering::greater(ord::greater);
}
🔗
constexpr operator weak_equality() const noexcept;
2
#
Returns: value == 0 ? weak_­equality​::​equivalent : weak_­equality​::​nonequivalent.
🔗
constexpr operator strong_equality() const noexcept;
3
#
Returns: value == 0 ? strong_­equality​::​equal : strong_­equality​::​nonequal.
🔗
constexpr operator partial_ordering() const noexcept;
4
#
Returns: 
value == 0 ? partial_ordering::equivalent :
value < 0  ? partial_ordering::less :
             partial_ordering::greater
🔗
constexpr operator weak_ordering() const noexcept;
5
#
Returns: 
value == 0 ? weak_ordering::equivalent :
value < 0  ? weak_ordering::less :
             weak_ordering::greater
🔗
constexpr bool operator==(strong_ordering v, unspecified) noexcept; constexpr bool operator!=(strong_ordering v, unspecified) noexcept; constexpr bool operator< (strong_ordering v, unspecified) noexcept; constexpr bool operator> (strong_ordering v, unspecified) noexcept; constexpr bool operator<=(strong_ordering v, unspecified) noexcept; constexpr bool operator>=(strong_ordering v, unspecified) noexcept;
6
#
Returns: v.value @ 0 for operator@.
🔗
constexpr bool operator==(unspecified, strong_ordering v) noexcept; constexpr bool operator!=(unspecified, strong_ordering v) noexcept; constexpr bool operator< (unspecified, strong_ordering v) noexcept; constexpr bool operator> (unspecified, strong_ordering v) noexcept; constexpr bool operator<=(unspecified, strong_ordering v) noexcept; constexpr bool operator>=(unspecified, strong_ordering v) noexcept;
7
#
Returns: 0 @ v.value for operator@.
🔗
constexpr strong_ordering operator<=>(strong_ordering v, unspecified) noexcept;
8
#
Returns: v.
🔗
constexpr strong_ordering operator<=>(unspecified, strong_ordering v) noexcept;
9
#
Returns: v < 0 ? strong_­ordering​::​greater : v > 0 ? strong_­ordering​::​less : v.

16.11.3 Class template common_­comparison_­category [cmp.common]

1
#
The type common_­comparison_­category provides an alias for the strongest comparison category to which all of the template arguments can be converted.
[ Note
:
A comparison category type is stronger than another if they are distinct types and an instance of the former can be converted to an instance of the latter.
— end note
 ]
🔗
template<class... Ts> struct common_comparison_category { using type = see below; };
2
#
Remarks: The member typedef-name type denotes the common comparison type ([class.spaceship]) of Ts..., the expanded parameter pack.
[ Note
:
This is well-defined even if the expansion is empty or includes a type that is not a comparison category type.
— end note
 ]

16.11.4 Comparison algorithms [cmp.alg]

🔗
template<class T> constexpr strong_ordering strong_order(const T& a, const T& b);
1
#
Effects: Compares two values and produces a result of type strong_­ordering:
  • (1.1)
    If numeric_­limits<T>​::​is_­iec559 is true, returns a result of type strong_­ordering that is consistent with the totalOrder operation as specified in ISO/IEC/IEEE 60559.
  • (1.2)
    Otherwise, returns a <=> b if that expression is well-formed and convertible to strong_­ordering.
  • (1.3)
    Otherwise, if the expression a <=> b is well-formed, then the function is defined as deleted.
  • (1.4)
    Otherwise, if the expressions a == b and a < b are each well-formed and convertible to bool, then
    • (1.4.1)
      if a == b is true, returns strong_­ordering​::​equal;
    • (1.4.2)
      otherwise, if a < b is true, returns strong_­ordering​::​less;
    • (1.4.3)
      otherwise, returns strong_­ordering​::​greater.
  • (1.5)
    Otherwise, the function is defined as deleted.
🔗
template<class T> constexpr weak_ordering weak_order(const T& a, const T& b);
2
#
Effects: Compares two values and produces a result of type weak_­ordering:
  • (2.1)
    Returns a <=> b if that expression is well-formed and convertible to weak_­ordering.
  • (2.2)
    Otherwise, if the expression a <=> b is well-formed, then the function is defined as deleted.
  • (2.3)
    Otherwise, if the expressions a == b and a < b are each well-formed and convertible to bool, then
    • (2.3.1)
      if a == b is true, returns weak_­ordering​::​equivalent;
    • (2.3.2)
      otherwise, if a < b is true, returns weak_­ordering​::​less;
    • (2.3.3)
      otherwise, returns weak_­ordering​::​greater.
  • (2.4)
    Otherwise, the function is defined as deleted.
🔗
template<class T> constexpr partial_ordering partial_order(const T& a, const T& b);
3
#
Effects: Compares two values and produces a result of type partial_­ordering:
  • (3.1)
    Returns a <=> b if that expression is well-formed and convertible to partial_­ordering.
  • (3.2)
    Otherwise, if the expression a <=> b is well-formed, then the function is defined as deleted.
  • (3.3)
    Otherwise, if the expressions a == b and a < b are each well-formed and convertible to bool, then
    • (3.3.1)
      if a == b is true, returns partial_­ordering​::​equivalent;
    • (3.3.2)
      otherwise, if a < b is true, returns partial_­ordering​::​less;
    • (3.3.3)
      otherwise, returns partial_­ordering​::​greater.
  • (3.4)
    Otherwise, the function is defined as deleted.
🔗
template<class T> constexpr strong_equality strong_equal(const T& a, const T& b);
4
#
Effects: Compares two values and produces a result of type strong_­equality:
  • (4.1)
    Returns a <=> b if that expression is well-formed and convertible to strong_­equality.
  • (4.2)
    Otherwise, if the expression a <=> b is well-formed, then the function is defined as deleted.
  • (4.3)
    Otherwise, if the expression a == b is well-formed and convertible to bool, then
    • (4.3.1)
      if a == b is true, returns strong_­equality​::​equal;
    • (4.3.2)
      otherwise, returns strong_­equality​::​nonequal.
  • (4.4)
    Otherwise, the function is defined as deleted.
🔗
template<class T> constexpr weak_equality weak_equal(const T& a, const T& b);
5
#
Effects: Compares two values and produces a result of type weak_­equality:
  • (5.1)
    Returns a <=> b if that expression is well-formed and convertible to weak_­equality.
  • (5.2)
    Otherwise, if the expression a <=> b is well-formed, then the function is defined as deleted.
  • (5.3)
    Otherwise, if the expression a == b is well-formed and convertible to bool, then
    • (5.3.1)
      if a == b is true, returns weak_­equality​::​equivalent;
    • (5.3.2)
      otherwise, returns weak_­equality​::​nonequivalent.
  • (5.4)
    Otherwise, the function is defined as deleted.