[concepts.lang] (original) (raw)

18 Concepts library [concepts]

18.4 Language-related concepts [concepts.lang]

18.4.1 General [concepts.lang.general]

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_](#concept:same-as-impl "18.4.2 Concept same_­as [concept.same]") = [is_same_v](meta.type.synop#lib:is%5Fsame%5Fv "21.3.3 Header <type_­traits> synopsis [meta.type.synop]")<T, U>; // _exposition only_ template<class T, class U> concept [same_as](#concept:same%5Fas "18.4.2 Concept same_­as [concept.same]") = [_same-as-impl_](#concept:same-as-impl "18.4.2 Concept same_­as [concept.same]")<T, U> && [_same-as-impl_](#concept:same-as-impl "18.4.2 Concept same_­as [concept.same]")<U, T>;

[Note 1:

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](#concept:derived%5Ffrom "18.4.3 Concept derived_­from [concept.derived]") = is_base_of_v<Base, Derived> && is_convertible_v<const volatile Derived*, const volatile Base*>;

[Note 1:

derived_from<Derived, Base> is satisfied if and only ifDerived is publicly and unambiguously derived from Base, orDerived and Base are the same class type ignoring cv-qualifiers.

— _end note_]

18.4.4 Concept convertible_to [concept.convertible]

Given types From and To and an expression Ewhose type and value category are the same as those of declval<From>(),convertible_to<From, To> requires Eto 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](#concept:convertible%5Fto "18.4.4 Concept convertible_­to [concept.convertible]") = is_convertible_v<From, To> && requires { static_cast<To>(declval<From>());};

Let FromR be add_rvalue_reference_t<From> andtest be the invented function:To test(FromR (&f)()) { return f();} and let f be a function with no arguments and return type FromRsuch that f() is equality-preserving.

Types From and To model convertible_to<From, To>only if:

• To is not an object or reference-to-object type, orstatic_cast<To>(f()) is equal to test(f).
• FromR is not a reference-to-object type, or
  • 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]).
  • Otherwise, the object referred to by f() is not modified by either above expression.

18.4.5 Concept common_reference_with [concept.commonref]

For two types T and U, if common_reference_t<T, U>is well-formed and denotes a type C such that bothconvertible_to<T, C>andconvertible_to<U, C>are modeled, then T and U share acommon reference type, C.

[Note 1:

C can be the same as T or U, or can be a different type.

C can be a reference type.

— _end note_]

template<class T, class U> concept [common_reference_with](#concept:common%5Freference%5Fwith "18.4.5 Concept common_­reference_­with [concept.commonref]") = [same_as](#concept:same%5Fas "18.4.2 Concept same_­as [concept.same]")<common_reference_t<T, U>, common_reference_t<U, T>> && [convertible_to](#concept:convertible%5Fto "18.4.4 Concept convertible_­to [concept.convertible]")<T, common_reference_t<T, U>> && [convertible_to](#concept:convertible%5Fto "18.4.4 Concept convertible_­to [concept.convertible]")<U, common_reference_t<T, U>>;

Let C be common_reference_t<T, U>.

Let t1 and t2 be equality-preserving expressions ([concepts.equality]) such thatdecltype((t1)) and decltype((t2)) are each T, and let u1 and u2 be equality-preserving expressions such thatdecltype((u1)) and decltype((u2)) are each U.

T and U model common_reference_with<T, U>only if

• C(t1) equals C(t2) if and only ift1 equals t2, and
• C(u1) equals C(u2) if and only ifu1 equals u2.

[Note 2:

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]

If T and U can both be explicitly converted to some third type,C, then T and U share a common type,C.

[Note 1:

C can be the same as T or U, or can be a different type.

C is not necessarily unique.

— _end note_]

template<class T, class U> concept [common_with](#concept:common%5Fwith "18.4.6 Concept common_­with [concept.common]") = [same_as](#concept:same%5Fas "18.4.2 Concept same_­as [concept.same]")<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](#concept:common%5Freference%5Fwith "18.4.5 Concept common_­reference_­with [concept.commonref]")< add_lvalue_reference_t<const T>, add_lvalue_reference_t<const U>> && [common_reference_with](#concept:common%5Freference%5Fwith "18.4.5 Concept common_­reference_­with [concept.commonref]")< add_lvalue_reference_t<common_type_t<T, U>>, common_reference_t< add_lvalue_reference_t<const T>, add_lvalue_reference_t<const U>>>;

Let C be common_type_t<T, U>.

Let t1 and t2 be equality-preserving expressions ([concepts.equality]) such thatdecltype((t1)) and decltype((t2)) are each T, and let u1 and u2 be equality-preserving expressions such thatdecltype((u1)) and decltype((u2)) are each U.

T and U model common_with<T, U>only if

• C(t1) equals C(t2) if and only ift1 equals t2, and
• C(u1) equals C(u2) if and only ifu1 equals u2.

[Note 2:

Users can customize the behavior of common_with by specializing thecommon_type class template ([meta.trans.other]).

— _end note_]

18.4.7 Arithmetic concepts [concepts.arithmetic]

template<class T> concept [integral](#concept:integral "18.4.7 Arithmetic concepts [concepts.arithmetic]") = [is_integral_v](meta.type.synop#lib:is%5Fintegral%5Fv "21.3.3 Header <type_­traits> synopsis [meta.type.synop]")<T>;template<class T> concept [signed_integral](#concept:signed%5Fintegral "18.4.7 Arithmetic concepts [concepts.arithmetic]") = [integral](#concept:integral "18.4.7 Arithmetic concepts [concepts.arithmetic]")<T> && [is_signed_v](meta.type.synop#lib:is%5Fsigned%5Fv "21.3.3 Header <type_­traits> synopsis [meta.type.synop]")<T>;template<class T> concept [unsigned_integral](#concept:unsigned%5Fintegral "18.4.7 Arithmetic concepts [concepts.arithmetic]") = [integral](#concept:integral "18.4.7 Arithmetic concepts [concepts.arithmetic]")<T> && ![signed_integral](#concept:signed%5Fintegral "18.4.7 Arithmetic concepts [concepts.arithmetic]")<T>;template<class T> concept [floating_point](#concept:floating%5Fpoint "18.4.7 Arithmetic concepts [concepts.arithmetic]") = is_floating_point_v<T>;

[Note 1:

signed_integral can be modeled even by types that are not signed integer types ([basic.fundamental]); for example, char.

— _end note_]

[Note 2:

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](#concept:assignable%5Ffrom "18.4.8 Concept assignable_­from [concept.assignable]") = is_lvalue_reference_v<LHS> && [common_reference_with](#concept:common%5Freference%5Fwith "18.4.5 Concept common_­reference_­with [concept.commonref]")<const remove_reference_t<LHS>&, const remove_reference_t<RHS>&> && requires(LHS lhs, RHS&& rhs) { { lhs = std::forward<RHS>(rhs) } -> [same_as](#concept:same%5Fas "18.4.2 Concept same_­as [concept.same]")<LHS>;};

Let:

• lhs be an lvalue that refers to an object lcopy such thatdecltype((lhs)) is LHS,
• rhs be an expression such that decltype((rhs)) isRHS, and
• rcopy be a distinct object that is equal to rhs.

LHS and RHS modelassignable_from<LHS, RHS> only if

• addressof(lhs = rhs) == addressof(lcopy).
• After evaluating lhs = rhs:
  • lhs is equal to rcopy, unless rhs is a non-const xvalue that refers to lcopy.
  • If rhs is a non-const xvalue, the resulting state of the object to which it refers is valid but unspecified ([lib.types.movedfrom]).
  • Otherwise, if rhs is a glvalue, the object to which it refers is not modified.

[Note 1:

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]

Let t1 and t2 be equality-preserving expressions that denote distinct equal objects of type T, and let u1 and u2similarly denote distinct equal objects of type U.

[Note 1:

t1 and u1 can denote distinct objects, or the same object.

— _end note_]

An operationexchanges the values denoted by t1 and u1 if and only if the operation modifies neither t2 nor u2 and:

• If T and U are the same type, the result of the operation is that t1 equals u2 and u1 equals t2.
• If T and U are different types andcommon_reference_with<decltype((t1)), decltype((u1))> is modeled, the result of the operation is thatC(t1) equals C(u2) andC(u1) equals C(t2) where C is common_reference_t<decltype((t1)), decltype((u1))>.

The expressionranges​::​swap(E1, E2) for subexpressions E1and E2 is expression-equivalent to an expressionS determined as follows:

• S is (void)swap(E1, E2)193if 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 declarationtemplate<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 byE1 and E2, the program is ill-formed, no diagnostic required.
  [Note 2:
  This precludes calling unconstrained program-defined overloads ofswap.
  When the deleted overload is viable, program-defined overloads need to be more specialized ([temp.func.order]) to be selected.
  — _end note_]
• 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 thatnoexcept(S) is equal tonoexcept(​ranges​::​swap(*E1, *E2)).
• Otherwise, if E1 and E2 are lvalues of the same type T that models move_constructible<T> andassignable_from<T&, T>,S is an expression that exchanges the denoted values.
  S is a constant expression if
  • T is a literal type ([basic.types.general]),
  • both E1 = std​::​move(E2) and E2 = std​::​move(E1) are constant subexpressions ([defns.const.subexpr]), and
  • the full-expressions of the initializers in the declarationsT t1(std::move(E1)); T t2(std::move(E2));are constant subexpressions.
    noexcept(S) is equal tois_nothrow_move_constructible_v<T> && is_nothrow_move_assignable_v<T>.
• Otherwise, ranges​::​swap(E1, E2) is ill-formed.
  [Note 3:
  This case can result in substitution failure when ranges​::​swap(E1, E2) appears in the immediate context of a template instantiation.
  — _end note_]

[Note 4:

Whenever ranges​::​swap(E1, E2) is a valid expression, it exchanges the values denoted byE1 and E2 and has type void.

— _end note_]

template<class T> concept [swappable](#concept:swappable "18.4.9 Concept swappable [concept.swappable]") = requires(T& a, T& b) { ranges::swap(a, b); };

template<class T, class U> concept [swappable_with](#concept:swappable%5Fwith "18.4.9 Concept swappable [concept.swappable]") = [common_reference_with](#concept:common%5Freference%5Fwith "18.4.5 Concept common_­reference_­with [concept.commonref]")<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));};

[Note 5:

The semantics of the swappable and swappable_withconcepts are fully defined by the ranges​::​swap customization point object.

— _end note_]

[Example 1:

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_]

18.4.10 Concept destructible [concept.destructible]

The destructible concept specifies properties of all types, instances of which can be destroyed at the end of their lifetime, or reference types.

[Note 1:

Unlike the Cpp17Destructible requirements (Table 35), 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]

The constructible_from concept constrains the initialization of a variable of a given type with a particular set of argument types.

18.4.12 Concept default_initializable [concept.default.init]

template<class T> constexpr bool _is-default-initializable_ = _see below_; // _exposition only_ template<class T> concept [default_initializable](#concept:default%5Finitializable "18.4.12 Concept default_­initializable [concept.default.init]") = [constructible_from](#concept:constructible%5Ffrom "18.4.11 Concept constructible_­from [concept.constructible]")<T> && requires { T{}; } && _is-default-initializable_<T>;

For a type T, is-default-initializable<T> is trueif and only if the variable definitionT 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](#concept:move%5Fconstructible "18.4.13 Concept move_­constructible [concept.moveconstructible]") = [constructible_from](#concept:constructible%5Ffrom "18.4.11 Concept constructible_­from [concept.constructible]")<T, T> && [convertible_to](#concept:convertible%5Fto "18.4.4 Concept convertible_­to [concept.convertible]")<T, T>;

If T is an object type, then let rv be an rvalue of typeT and u2 a distinct object of type T equal torv.

T models move_constructible only if

• After the definition T u = rv;, u is equal to u2.
• 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](#concept:copy%5Fconstructible "18.4.14 Concept copy_­constructible [concept.copyconstructible]") = [move_constructible](#concept:move%5Fconstructible "18.4.13 Concept move_­constructible [concept.moveconstructible]")<T> && [constructible_from](#concept:constructible%5Ffrom "18.4.11 Concept constructible_­from [concept.constructible]")<T, T&> && [convertible_to](#concept:convertible%5Fto "18.4.4 Concept convertible_­to [concept.convertible]")<T&, T> && [constructible_from](#concept:constructible%5Ffrom "18.4.11 Concept constructible_­from [concept.constructible]")<T, const T&> && [convertible_to](#concept:convertible%5Fto "18.4.4 Concept convertible_­to [concept.convertible]")<const T&, T> && [constructible_from](#concept:constructible%5Ffrom "18.4.11 Concept constructible_­from [concept.constructible]")<T, const T> && [convertible_to](#concept:convertible%5Fto "18.4.4 Concept convertible_­to [concept.convertible]")<const T, T>;

If T is an object type, then let v be an lvalue of typeT or const T or an rvalue of type const T.

T models copy_constructible only if

• T(v) is equal to v and does not modify v.