18 Concepts library [concepts]

18.4 Language-related concepts [concepts.lang]

18.4.1 General [concepts.lang.general]

1
#
Subclause [concepts.lang] contains the definition of concepts corresponding to language features.
These concepts express relationships between types, type classifications, and fundamental type properties.

18.4.2 Concept same_­as [concept.same]

🔗
template<class T, class U> concept same-as-impl = is_same_v<T, U>; // exposition only template<class T, class U> concept same_­as = same-as-impl<T, U> && same-as-impl<U, T>;
1
#
[Note
:
same_­as<T, U> subsumes same_­as<U, T> and vice versa.
— end note
]

18.4.3 Concept derived_­from [concept.derived]

🔗
template<class Derived, class Base> concept derived_­from = is_base_of_v<Base, Derived> && is_convertible_v<const volatile Derived*, const volatile Base*>;
1
#
[Note
:
derived_­from<Derived, Base> is satisfied if and only if Derived is publicly and unambiguously derived from Base, or Derived and Base are the same class type ignoring cv-qualifiers.
— end note
]

18.4.4 Concept convertible_­to [concept.convertible]

1
#
Given types From and To and an expression E such that decltype((E)) is add_­rvalue_­reference_­t<From>, convertible_­to<From, To> requires E to be both implicitly and explicitly convertible to type To.
The implicit and explicit conversions are required to produce equal results.
🔗
template<class From, class To> concept convertible_­to = is_convertible_v<From, To> && requires(add_rvalue_reference_t<From> (&f)()) { static_cast<To>(f()); };
2
#
Let FromR be add_­rvalue_­reference_­t<From> and test be the invented function: 
To test(FromR (&f)()) {
  return f();
}
and let f be a function with no arguments and return type FromR such that f() is equality-preserving.
Types From and To model convertible_­to<From, To> only if:
  • (2.1)
    To is not an object or reference-to-object type, or static_­cast<To>(f()) is equal to test(f).
  • (2.2)
    FromR is not a reference-to-object type, or
    • (2.2.1)
      If FromR is an rvalue reference to a non const-qualified type, the resulting state of the object referenced by f() after either above expression is valid but unspecified ([lib.types.movedfrom]).
    • (2.2.2)
      Otherwise, the object referred to by f() is not modified by either above expression.

18.4.5 Concept common_­reference_­with [concept.commonref]

1
#
For two types T and U, if common_­reference_­t<T, U> is well-formed and denotes a type C such that both convertible_­to<T, C> and convertible_­to<U, C> are modeled, then T and U share a common reference type, C.
[Note
:
C could be the same as T, or U, or it could be a different type.
C may be a reference type.
— end note
]
🔗
template<class T, class U> concept common_­reference_­with = same_­as<common_reference_t<T, U>, common_reference_t<U, T>> && convertible_­to<T, common_reference_t<T, U>> && convertible_­to<U, common_reference_t<T, U>>;
2
#
Let C be common_­reference_­t<T, U>.
Let t1 and t2 be equality-preserving expressions ([concepts.equality]) such that decltype((t1)) and decltype((t2)) are each T, and let u1 and u2 be equality-preserving expressions such that decltype((u1)) and decltype((u2)) are each U.
T and U model common_­reference_­with<T, U> only if:
  • (2.1)
    C(t1) equals C(t2) if and only if t1 equals t2, and
  • (2.2)
    C(u1) equals C(u2) if and only if u1 equals u2.
3
#
[Note
:
Users can customize the behavior of common_­reference_­with by specializing the basic_­common_­reference class template ([meta.trans.other]).
— end note
]

18.4.6 Concept common_­with [concept.common]

1
#
If T and U can both be explicitly converted to some third type, C, then T and U share a common type, C.
[Note
:
C could be the same as T, or U, or it could be a different type.
C might not be unique.
— end note
]
🔗
template<class T, class U> concept common_­with = same_­as<common_type_t<T, U>, common_type_t<U, T>> && requires { static_cast<common_type_t<T, U>>(declval<T>()); static_cast<common_type_t<T, U>>(declval<U>()); } && common_reference_with< add_lvalue_reference_t<const T>, add_lvalue_reference_t<const U>> && common_reference_with< add_lvalue_reference_t<common_type_t<T, U>>, common_reference_t< add_lvalue_reference_t<const T>, add_lvalue_reference_t<const U>>>;
2
#
Let C be common_­type_­t<T, U>.
Let t1 and t2 be equality-preserving expressions ([concepts.equality]) such that decltype((t1)) and decltype((t2)) are each T, and let u1 and u2 be equality-preserving expressions such that decltype((u1)) and decltype((u2)) are each U.
T and U model common_­with<T, U> only if:
  • (2.1)
    C(t1) equals C(t2) if and only if t1 equals t2, and
  • (2.2)
    C(u1) equals C(u2) if and only if u1 equals u2.
3
#
[Note
:
Users can customize the behavior of common_­with by specializing the common_­type class template ([meta.trans.other]).
— end note
]

18.4.7 Arithmetic concepts [concepts.arithmetic]

🔗
template<class T> concept integral = is_integral_v<T>; template<class T> concept signed_­integral = integral<T> && is_signed_v<T>; template<class T> concept unsigned_­integral = integral<T> && !signed_integral<T>; template<class T> concept floating_­point = is_floating_point_v<T>;
1
#
[Note
:
signed_­integral can be modeled even by types that are not signed integer types ([basic.fundamental]); for example, char.
— end note
]
2
#
[Note
:
unsigned_­integral can be modeled even by types that are not unsigned integer types ([basic.fundamental]); for example, bool.
— end note
]

18.4.8 Concept assignable_­from [concept.assignable]

🔗
template<class LHS, class RHS> concept assignable_­from = is_lvalue_reference_v<LHS> && common_reference_with<const remove_reference_t<LHS>&, const remove_reference_t<RHS>&> && requires(LHS lhs, RHS&& rhs) { { lhs = std::forward<RHS>(rhs) } -> same_­as<LHS>; };
1
#
Let:
  • (1.1)
    lhs be an lvalue that refers to an object lcopy such that decltype((lhs)) is LHS,
  • (1.2)
    rhs be an expression such that decltype((rhs)) is RHS, and
  • (1.3)
    rcopy be a distinct object that is equal to rhs.
LHS and RHS model assignable_­from<LHS, RHS> only if
  • (1.4)
    addressof(lhs = rhs) == addressof(lcopy).
  • (1.5)
    After evaluating lhs = rhs:
    • (1.5.1)
      lhs is equal to rcopy, unless rhs is a non-const xvalue that refers to lcopy.
    • (1.5.2)
      If rhs is a non-const xvalue, the resulting state of the object to which it refers is valid but unspecified ([lib.types.movedfrom]).
    • (1.5.3)
      Otherwise, if rhs is a glvalue, the object to which it refers is not modified.
2
#
[Note
:
Assignment need not be a total function ([structure.requirements]); in particular, if assignment to an object x can result in a modification of some other object y, then x = y is likely not in the domain of =.
— end note
]

18.4.9 Concept swappable [concept.swappable]

1
#
Let t1 and t2 be equality-preserving expressions that denote distinct equal objects of type T, and let u1 and u2 similarly denote distinct equal objects of type U.
[Note
:
t1 and u1 can denote distinct objects, or the same object.
— end note
]
An operation exchanges the values denoted by t1 and u1 if and only if the operation modifies neither t2 nor u2 and:
  • (1.1)
    If T and U are the same type, the result of the operation is that t1 equals u2 and u1 equals t2.
  • (1.2)
    If T and U are different types and common_­reference_­with<decltype((t1)), decltype((u1))> is modeled, the result of the operation is that C(t1) equals C(u2) and C(u1) equals C(t2) where C is common_­reference_­t<decltype((t1)), decltype((u1))>.
2
#
The name ranges​::​swap denotes a customization point object ([customization.point.object]).
The expression ranges​::​swap(E1, E2) for subexpressions E1 and E2 is expression-equivalent to an expression S determined as follows:
  • (2.1)
    S is (void)swap(E1, E2)218 if E1 or E2 has class or enumeration type ([basic.compound]) and that expression is valid, with overload resolution performed in a context that includes the declaration 
    template<class T>
  void swap(T&, T&) = delete;
    and does not include a declaration of ranges​::​swap. If the function selected by overload resolution does not exchange the values denoted by E1 and E2, the program is ill-formed, no diagnostic required.
  • (2.2)
    Otherwise, if E1 and E2 are lvalues of array types ([basic.compound]) with equal extent and ranges​::​swap(*E1, *E2) is a valid expression, S is (void)ranges​::​swap_­ranges(E1, E2), except that noexcept(S) is equal to noexcept(​ranges​::​swap(*E1, *E2)).
  • (2.3)
    Otherwise, if E1 and E2 are lvalues of the same type T that models move_­constructible<T> and assignable_­from<T&, T>, S is an expression that exchanges the denoted values. S is a constant expression if
    • (2.3.1)
      T is a literal type ([basic.types]),
    • (2.3.2)
      both E1 = std​::​move(E2) and E2 = std​::​move(E1) are constant subexpressions ([defns.const.subexpr]), and
    • (2.3.3)
      the full-expressions of the initializers in the declarations 
      T t1(std::move(E1));
T t2(std::move(E2));
      are constant subexpressions.
    noexcept(S) is equal to is_­nothrow_­move_­constructible_­v<T> && is_­nothrow_­move_­assignable_­v<T>.
  • (2.4)
    Otherwise, ranges​::​swap(E1, E2) is ill-formed.
    [Note
    : This case can result in substitution failure when ranges​::​swap(E1, E2) appears in the immediate context of a template instantiation. — end note
    ]
3
#
[Note
:
Whenever ranges​::​swap(E1, E2) is a valid expression, it exchanges the values denoted by E1 and E2 and has type void.
— end note
]
🔗
template<class T> concept swappable = requires(T& a, T& b) { ranges::swap(a, b); };
🔗
template<class T, class U> concept swappable_­with = common_reference_with<T, U> && requires(T&& t, U&& u) { ranges::swap(std::forward<T>(t), std::forward<T>(t)); ranges::swap(std::forward<U>(u), std::forward<U>(u)); ranges::swap(std::forward<T>(t), std::forward<U>(u)); ranges::swap(std::forward<U>(u), std::forward<T>(t)); };
4
#
[Note
:
The semantics of the swappable and swappable_­with concepts are fully defined by the ranges​::​swap customization point object.
— end note
]
5
#
[Example
:
User code can ensure that the evaluation of swap calls is performed in an appropriate context under the various conditions as follows: 
#include <cassert>
#include <concepts>
#include <utility>

namespace ranges = std::ranges;

template<class T, std::swappable_with<T> U>
void value_swap(T&& t, U&& u) {
  ranges::swap(std::forward<T>(t), std::forward<U>(u));
}

template<std::swappable T>
void lv_swap(T& t1, T& t2) {
  ranges::swap(t1, t2);
}

namespace N {
  struct A { int m; };
  struct Proxy {
    A* a;
    Proxy(A& a) : a{&a} {}
    friend void swap(Proxy x, Proxy y) {
      ranges::swap(*x.a, *y.a);
    }
  };
  Proxy proxy(A& a) { return Proxy{ a }; }
}

int main() {
  int i = 1, j = 2;
  lv_swap(i, j);
  assert(i == 2 && j == 1);

  N::A a1 = { 5 }, a2 = { -5 };
  value_swap(a1, proxy(a2));
  assert(a1.m == -5 && a2.m == 5);
}
— end example
]
218)
The name swap is used here unqualified.
⮥

18.4.10 Concept destructible [concept.destructible]

1
#
The destructible concept specifies properties of all types, instances of which can be destroyed at the end of their lifetime, or reference types.
🔗
template<class T> concept destructible = is_nothrow_destructible_v<T>;
2
#
[Note
:
Unlike the Cpp17Destructible requirements (Table 32), this concept forbids destructors that are potentially throwing, even if a particular invocation of the destructor does not actually throw.
— end note
]

18.4.11 Concept constructible_­from [concept.constructible]

1
#
The constructible_­from concept constrains the initialization of a variable of a given type with a particular set of argument types.
🔗
template<class T, class... Args> concept constructible_­from = destructible<T> && is_constructible_v<T, Args...>;

18.4.12 Concept default_­initializable [concept.default.init]

🔗
template<class T> inline constexpr bool is-default-initializable = see below; // exposition only template<class T> concept default_­initializable = constructible_from<T> && requires { T{}; } && is-default-initializable<T>;
1
#
For a type T, is-default-initializable<T> is true if and only if the variable definition 
T t;
is well-formed for some invented variable t; otherwise it is false.
Access checking is performed as if in a context unrelated to T.
Only the validity of the immediate context of the variable initialization is considered.

18.4.13 Concept move_­constructible [concept.moveconstructible]

🔗
template<class T> concept move_­constructible = constructible_from<T, T> && convertible_­to<T, T>;
1
#
If T is an object type, then let rv be an rvalue of type T and u2 a distinct object of type T equal to rv.
T models move_­constructible only if
  • (1.1)
    After the definition T u = rv;, u is equal to u2.
  • (1.2)
    T(rv) is equal to u2.
  • (1.3)
    If T is not const, rv's resulting state is valid but unspecified ([lib.types.movedfrom]); otherwise, it is unchanged.

18.4.14 Concept copy_­constructible [concept.copyconstructible]

🔗
template<class T> concept copy_­constructible = move_constructible<T> && constructible_from<T, T&> && convertible_­to<T&, T> && constructible_from<T, const T&> && convertible_­to<const T&, T> && constructible_from<T, const T> && convertible_­to<const T, T>;
1
#
If T is an object type, then let v be an lvalue of type (possibly const) T or an rvalue of type const T.
T models copy_­constructible only if