18 Concepts library [concepts]

18.5 Comparison concepts [concepts.compare]

18.5.1 General [concepts.compare.general]

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

18.5.2 Boolean testability [concept.booleantestable]

1
#
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
2
#
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).
3
#
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.
4
#
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
:
In 
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
]
5
#
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]).
6
#
[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; };
7
#
Let e be an expression such that decltype((e)) is T.
T models boolean-testable only if bool(e) == !bool(!e).
8
#
[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; };
1
#
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>;
2
#
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.
3
#
[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>;
4
#
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>;
1
#
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>;
2
#
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 totally_­ordered_­with<T, U> only if
  • (2.1)
    bool(t < u) == bool(C(t) < C(u)).
  • (2.2)
    bool(t > u) == bool(C(t) > C(u)).
  • (2.3)
    bool(t <= u) == bool(C(t) <= C(u)).
  • (2.4)
    bool(t >= u) == bool(C(t) >= C(u)).
  • (2.5)
    bool(u < t) == bool(C(u) < C(t)).
  • (2.6)
    bool(u > t) == bool(C(u) > C(t)).
  • (2.7)
    bool(u <= t) == bool(C(u) <= C(t)).
  • (2.8)
    bool(u >= t) == bool(C(u) >= C(t)).