18 Concepts library [concepts]

18.5 Comparison concepts [concepts.compare]

18.5.1 General [concepts.compare.general]

Subclause [concepts.compare] describes concepts that establish relationships and orderings on values of possibly differing object types.

18.5.2 Boolean testability [concept.booleantestable]

The exposition-only boolean-testable concept specifies the requirements on expressions that are convertible to bool and for which the logical operators ([expr.log.and], [expr.log.or], [expr.unary.op]) have the conventional semantics.

🔗

template<class T>
  concept boolean-testable-impl = convertible_to<T, bool>;  // exposition only

Let e be an expression such that decltype((e)) is T.

T models boolean-testable-impl only if:

(2.1)
either remove_cvref_t<T> is not a class type, or name lookup for the names operator&& and operator|| within the scope of remove_cvref_t<T> as if by class member access lookup ([class.member.lookup]) results in an empty declaration set; and
(2.2)
name lookup for the names operator&& and operator|| in the associated namespaces and entities of T ([basic.lookup.argdep]) finds no disqualifying declaration (defined below).

A disqualifying parameter is a function parameter whose declared type P

(3.1)
is not dependent on a template parameter, and there exists an implicit conversion sequence ([over.best.ics]) from e to P; or
(3.2)
is dependent on one or more template parameters, and either
- (3.2.1)
  P contains no template parameter that participates in template argument deduction ([temp.deduct.type]), or
- (3.2.2)
  template argument deduction using the rules for deducing template arguments in a function call ([temp.deduct.call]) and e as the argument succeeds.

A key parameter of a function template D is a function parameter of type cv X or reference thereto, where X names a specialization of a class template that is a member of the same namespace as D, and X contains at least one template parameter that participates in template argument deduction.

[ Example

namespace Z {
  template<class> struct C {};
  template<class T>
    void operator&&(C<T> x, T y);
  template<class T>
    void operator||(C<type_identity_t<T>> x, T y);
}

the declaration of Z::operator&& contains one key parameter, C<T> x, and the declaration of Z::operator|| contains no key parameters.

— end example

]

A disqualifying declaration is

(5.1)
a (non-template) function declaration that contains at least one disqualifying parameter; or
(5.2)
a function template declaration that contains at least one disqualifying parameter, where
- (5.2.1)
  at least one disqualifying parameter is a key parameter; or
- (5.2.2)
  the declaration contains no key parameters; or
- (5.2.3)
  the declaration declares a function template that is not visible in its namespace ([namespace.memdef]).

[ Note

The intention is to ensure that given two types T1 and T2 that each model boolean-testable-impl, the && and || operators within the expressions declval<T1>() && declval<T2>() and declval<T1>() || declval<T2>() resolve to the corresponding built-in operators.

— end note

]

🔗

template<class T>
  concept boolean-testable =                // exposition only
    boolean-testable-impl<T> && requires (T&& t) {
      { !std::forward<T>(t) } -> boolean-testable-impl;
    };

Let e be an expression such that decltype((e)) is T.

T models boolean-testable only if bool(e) == !bool(!e).

[ Example

The types bool, true_type ([meta.type.synop]), int*, and bitset<N>::reference ([template.bitset]) model boolean-testable.

— end example

]

18.5.3 Concept equality_comparable [concept.equalitycomparable]

🔗

template<class T, class U>
  concept weakly-equality-comparable-with = // exposition only
    requires(const remove_reference_t<T>& t,
             const remove_reference_t<U>& u) {
      { t == u } -> boolean-testable;
      { t != u } -> boolean-testable;
      { u == t } -> boolean-testable;
      { u != t } -> boolean-testable;
    };

Given types T and U, let t and u be lvalues of types const remove_reference_t<T> and const remove_reference_t<U> respectively.

T and U model weakly-equality-comparable-with<T, U> only if

(1.1)
t == u, u == t, t != u, and u != t have the same domain.
(1.2)
bool(u == t) == bool(t == u).
(1.3)
bool(t != u) == !bool(t == u).
(1.4)
bool(u != t) == bool(t != u).

🔗

template<class T>
  concept equality_comparable = weakly-equality-comparable-with<T, T>;

Let a and b be objects of type T.

T models equality_comparable only if bool(a == b) is true when a is equal to b ([concepts.equality]), and false otherwise.

[ Note

The requirement that the expression a == b is equality-preserving implies that == is transitive and symmetric.

— end note

]

🔗

template<class T, class U>
  concept equality_comparable_with =
    equality_comparable<T> && equality_comparable<U> &&
    common_reference_with<const remove_reference_t<T>&, const remove_reference_t<U>&> &&
    equality_comparable<
      common_reference_t<
        const remove_reference_t<T>&,
        const remove_reference_t<U>&>> &&
    weakly-equality-comparable-with<T, U>;

Given types T and U, let t be an lvalue of type const remove_reference_t<T>, u be an lvalue of type const remove_reference_t<U>, and C be:

common_reference_t<const remove_reference_t<T>&, const remove_reference_t<U>&>

T and U model equality_comparable_with<T, U> only if bool(t == u) == bool(C(t) == C(u)).

18.5.4 Concept totally_ordered [concept.totallyordered]

🔗

template<class T>
  concept totally_ordered =
    equality_comparable<T> && partially-ordered-with<T, T>;

Given a type T, let a, b, and c be lvalues of type const remove_reference_t<T>.

T models totally_ordered only if

(1.1)
Exactly one of bool(a < b), bool(a > b), or bool(a == b) is true.
(1.2)
If bool(a < b) and bool(b < c), then bool(a < c).
(1.3)
bool(a <= b) == !bool(b < a).
(1.4)
bool(a >= b) == !bool(a < b).

🔗

template<class T, class U>
  concept totally_ordered_with =
    totally_ordered<T> && totally_ordered<U> &&
    equality_comparable_with<T, U> &&
    totally_ordered<
      common_reference_t<
        const remove_reference_t<T>&,
        const remove_reference_t<U>&>> &&
    partially-ordered-with<T, U>;