Constraints and concepts
This page describes an experimental core language feature. For named type requirements used in the specification of the standard library, see library concepts
Class templates, function templates, and nontemplate functions (typically members of class templates) may be associated with a constraint, which specifies the requirements on template arguments, which can be used to select the most appropriate function overloads and template specializations.
Constraints may also be used to limit automatic type deduction in variable declarations and function return types to only the types that satisfy specified requirements.
Named sets of such requirements are called concepts. Each concept is a predicate, evaluated at compile time, and becomes a part of the interface of a template where it is used as a constraint:
#include <string> #include <locale> using namespace std::literals; // Declaration of the concept "EqualityComparable", which is satisfied by // any type T such that for values a and b of type T, // the expression a==b compiles and its result is convertible to bool template<typename T> concept EqualityComparable = requires(T a, T b) { { a == b } > bool; }; template<EqualityComparable T> void f(T&&); // constrained C++20 function template // template<typename T> // void f(T&&) requires EqualityComparable<T>; // long form of the same // void f(EqualityComparable&&); // short form of the same (Concepts TS only, not C++20) int main() { f("abc"s); // OK, std::string is EqualityComparable f(std::use_facet<std::ctype<char>>(std::locale{})); // Error: not EqualityComparable }
Violations of constraints are detected at compile time, early in the template instantiation process, which leads to easy to follow error messages.
std::list<int> l = {3,1,10}; std::sort(l.begin(), l.end()); //Typical compiler diagnostic without concepts: // invalid operands to binary expression ('std::_List_iterator<int>' and // 'std::_List_iterator<int>') // std::__lg(__last  __first) * 2); // ~~~~~~ ^ ~~~~~~~ // ... 50 lines of output ... // //Typical compiler diagnostic with concepts: // error: cannot call std::sort with std::_List_iterator<int> // note: concept RandomAccessIterator<std::_List_iterator<int>> was not satisfied
The intent of concepts is to model semantic categories (Number, Range, RegularFunction) rather than syntactic restrictions (HasPlus, Array). According to ISO C++ core guideline T.20, "The ability to specify a meaningful semantics is a defining characteristic of a true concept, as opposed to a syntactic constraint."
If feature testing is supported, the features described in this section (Concepts TS version published in 2015) are indicated by the macro constant __cpp_concepts with a value equal or greater 201507.
PlaceholdersThe unconstrained placeholder auto and constrained placeholders which have the form conceptname Placeholders may appear in variable declarations (in which case they are deduced from the initializer) or in function return types (in which case they are deduced from return statements) std::pair<auto, auto> p2 = std::make_pair(0, 'a'); // first auto is int, // second auto is char Sortable x = f(y); // the type of x is deduced from the return type of f, // only compiles if the type satisfies the constraint Sortable auto f(Container) > Sortable; // return type is deduced from the return statement // only compiles if the type satisfies Sortable Placeholders may also appear in parameters, in which case they turn function declarations into template declarations (constrained if the placeholder is constrained) template<size_t N> concept bool Even = (N%2 == 0); void f(std::array<auto, Even>); // this is a template with two parameters: // unconstrained type parameter and a constrained nontype parameter Constrained placeholders may be used anywhere auto may be used, for example, in generic lambda declarations auto gl = [](Assignable& a, auto* b) { a = *b; }; Abbreviated templatesIf one or more placeholders appears in a function parameter list, the function declaration is actually a function template declaration, whose template parameter list includes one invented parameter for every unique placeholder, in order of appearance // short form void g1(const EqualityComparable*, Incrementable&); // long form: // template<EqualityComparable T, Incrementable U> void g1(const T*, U&); // longer form: // template<typename T, typename U> // void g1(const T*, U&) requires EqualityComparable<T> && Incrementable<U>; void f2(std::vector<auto*>...); // long form: template<typename... T> void f2(std::vector<T*>...); void f4(auto (auto::*)(auto)); // long form: template<typename T, typename U, typename V> void f4(T (U::*)(V)); All placeholders introduced by equivalent constrained type specifiers have the same invented template parameter. However, each unconstrained specifier ( void f0(Comparable a, Comparable* b); // long form: template<Comparable T> void f0(T a, T* b); void f1(auto a, auto* b); // long form: template<typename T, typename U> f1(T a, U* b); Both function templates and class templates can be declared using a template introduction, which has the syntax conceptname Besides declaring a template, template introduction associates a predicate constraint (see below) that names (for variable concepts) or invokes (for function concepts) the concept named by the introduction. EqualityComparable{T} class Foo; // long form: template<EqualityComparable T> class Foo; // longer form: template<typename T> requires EqualityComparable<T> class Foo; template<typename T, int N, typename... Xs> concept bool Example = ...; Example{A, B, ...C} struct S1; // long form template<class A, int B, class... C> requires Example<A,B,C...> struct S1; For function templates, template introduction can be combined with placeholders: Sortable{T} void f(T, auto); // long form: template<Sortable T, typename U> void f(T, U); // alternative using only placeholders: void f(Sortable, auto);

(concepts TS) 
[edit] Concepts
A concept is a named set of requirements. The definition of a concept appears at namespace scope.
The definition of a concept has the form
// concept template <class T, class U> concept Derived = std::is_base_of<U, T>::value; Concepts cannot recursively refer to themselves and cannot be constrained template<typename T> concept V = V<T*>; // error: recursive concept template<class T> concept C1 = true; template<C1 T> concept Error1 = true; // Error: C1 T attempts to constrain a concept definition template<class T> requires C1<T> concept Error2 = true; // Error: the requiresclause attempts to constrain a concept 
(since C++20)  
The definition of a concept has the form of a function template definition (in which case it is called function concept) or variable template definition (in which case it is called variable concept). The only difference is that the keyword concept appears in the declspecifierseq:
// variable concept template <class T, class U> concept bool Derived = std::is_base_of<U, T>::value; // function concept template <class T> concept bool EqualityComparable() { return requires(T a, T b) { {a == b} > Boolean; {a != b} > Boolean; }; } The following restrictions apply to function concepts:
The following restrictions apply to variable concepts:
Concepts cannot recursively refer to themselves in the body of the function or in the initializer of the variable: template<typename T> concept bool F() { return F<typename T::type>(); } // error template<typename T> concept bool V = V<T*>; // error A concept definition cannot have associated constraints. template<class T> concept bool C1 = true; template<C1 T> concept bool Error1 = true; // Error: C1 T declares an associated constraint template<class T> requires C1<T> concept bool Error2 = true; // Error: the requiresclause declares an associated constraint 
(concepts TS) 
Explicit instantiations, explicit specializations, or partial specializations of concepts are not allowed (the meaning of the original definition of a constraint cannot be changed)
[edit] Constraints
A constraint is a sequence of logical operations that specifies requirements on template arguments. They can appear within requiresexpressions (see below) and directly as bodies of concepts
There are 9 types of constraints:
The first three types of constraints may appear directly as the body of a concept or as an adhoc requiresclause:
template<typename T> requires // requiresclause (adhoc constraint) sizeof(T) > 1 && get_value<T>() // conjunction of two predicate constraints void f(T);
When multiple constraints are attached to the same declaration, the total constraint is a conjunction in the following order: the constraint introduced by template introduction, constraints for each template parameter in order of appearance, the requires clause after the template parameter list, constraints for each function parameter in order of appearance, trailing requires clause:
// the declarations declare the same constrained function template // with the constraint Incrementable<T> && Decrementable<T> template<Incrementable T> void f(T) requires Decrementable<T>; template<typename T> requires Incrementable<T> && Decrementable<T> void f(T); // OK in concepts TS, illformed no diagnostic required in C++20 // the following two declarations have different constraints: // the first declaration has Incrementable<T> && Decrementable<T> // the second declaration has Decrementable<T> && Incrementable<T> // Even though they are logically equivalent. // The second declaration is illformed, no diagnostic required template<Incrementable T> requires Decrementable<T> void g(); template<Decrementable T> requires Incrementable<T> void g(); // error
[edit] Conjunctions
Conjunction of constraints P
and Q
is specified as P && Q.
template <class T> concept Integral = std::is_integral<T>::value; template <class T> concept SignedIntegral = Integral<T> && std::is_signed<T>::value; template <class T> concept UnsignedIntegral = Integral<T> && !SignedIntegral<T>;
A conjunction of two constraints is satisfied only if both constraints are satisfied. Conjunctions are evaluated left to right and shortcircuited (if the left constraint is not satisfied, template argument substitution into the right constraint is not attempted: this prevents failures due to substitution outside of immediate context). Userdefined overloads of operator&&
are not allowed in constraint conjunctions.
[edit] Disjunctions
Disjunction of constraints P
and Q
is specified as P  Q.
A disjunction of two constraints is satisfied if either constraint is satisfied. Disjunctions are evaluated left to right and shortcircuited (if the left constraint is satisfied, template argument deduction into the right constraint is not attempted). Userdefined overloads of operator
are not allowed in constraint disjunctions.
template <class T = void> requires EqualityComparable<T>()  Same<T, void> struct equal_to;
[edit] Predicate constraints
A predicate constraint is a constant expression of type bool. It is satisfied only if it evaluates to true
template<typename T> concept Size32 = sizeof(T) == 4;
Predicate constraints can specify requirements on nontype template parameters and on template template arguments.
Predicate constraints must evaluate directly to bool, no conversions allowed:
template<typename T> struct S { constexpr explicit operator bool() const { return true; } }; template<typename T> requires S<T>{} // bad predicate constraint: S<T>{} is not bool void f(T); f(0); // error: constraint never satisfied
[edit] Requirements
The keyword requires is used in two ways:
template<typename T> void f(T&&) requires Eq<T>; // can appear as the last element of a function declarator template<typename T> requires Addable<T> // or right after a template parameter list T add(T a, T b) { return a + b; }
In this case, the keyword requires must be followed by some constant expression (so it's possible to write "requires true;"), but the intent is that a named concept (as in the example above) or a conjunction/disjunction of named concepts or a requiresexpression is used.
The expression must have one of the following forms:

(since C++20) 
true
if the corresponding concept is satisfied, and false otherwise:
template<typename T> concept Addable = requires (T x) { x + x; }; // requiresexpression template<typename T> requires Addable<T> // requiresclause, not requiresexpression T add(T a, T b) { return a + b; } template<typename T> requires requires (T x) { x + x; } // adhoc constraint, note keyword used twice T add(T a, T b) { return a + b; }
The syntax of requiresexpession is as follows:
requires ( parameterlist(optional) ) { requirementseq }


parameterlist    a commaseparated list of parameters like in a function declaration, except that default arguments are not allowed and the last parameter cannot be an ellipsis. These parameters have no storage, linkage or lifetime. These parameters are in scope until the closing } of the requirementseq. If no parameters are used, the round parentheses may be omitted as well

requirementseq    whitespaceseparated sequence of requirements, described below (each requirement ends with a semicolon). Each requirement adds another constraint to the conjunction of constraints that this requiresexpression defines. 
Each requirement in the requirementsseq is one of the following:
 simple requirement
 type requirements
 compound requirements
 nested requirements
Requirements may refer to the template parameters that are in scope and to the local parameters introduced in the parameterlist. When parametrized, a requiresexpression is said to introduce a parametrized constraint
The substitution of template arguments into a requiresexpression may result in the formation of invalid types or expressions in its requirements. In such cases,
 If a substitution failure occurs in a requiresexpression that is used outside of a templated entity declaration, then the program is illformed.
 If the requiresexpression is used in a declaration of a templated entity, the corresponding constraint is treated as "not satisfied" and the substitution failure is not an error, however
 If a substitution failure would occur in a requiresexpression for every possible template argument, the program is illformed, no diagnostic required:
template<class T> concept C = requires { new int[(int)sizeof(T)]; // invalid for every T: illformed, no diagnostic required };
[edit] Simple requirements
A simple requirement is an arbitrary expression statement. The requirement is that the expression is valid (this is an expression constraint). Unlike with predicate constraints, evaluation does not take place, only language correctness is checked.
template<typename T> concept Addable = requires (T a, T b) { a + b; // "the expression a+b is a valid expression that will compile" }; template <class T, class U = T> concept Swappable = requires(T&& t, U&& u) { swap(std::forward<T>(t), std::forward<U>(u)); swap(std::forward<U>(u), std::forward<T>(t)); };
[edit] Type requirements
A type requirement is the keyword typename followed by a type name, optionally qualified. The requirement is that the named type exists (a type constraint): this can be used to verify that a certain named nested type exists, or that a class template specialization names a type, or that an alias template names a type.
template<typename T> using Ref = T&; template<typename T> concept C = requires { typename T::inner; // required nested member name typename S<T>; // required class template specialization typename Ref<T>; // required alias template substitution }; template <class T, class U> using CommonType = std::common_type_t<T, U>; template <class T, class U> concept Common = requires (T t, U u) { typename CommonType<T, U>; // CommonType<T, U> is valid and names a type { CommonType<T, U>{std::forward<T>(t)} }; { CommonType<T, U>{std::forward<U>(u)} }; };
[edit] Compound Requirements
A compound requirement has the form
{ expression } noexcept (optional) trailingreturntype(optional) ;


and specifies a conjunction of the following constraints:
noexcept
is used, expression must also be noexcept (exception constraint)template<typename T> concept C2 = requires(T x) { {*x} > typename T::inner; // the expression *x must be valid // AND the type T::inner must be valid // AND the result of *x must be convertible to T::inner }; template <class T, class U> concept Same = std::is_same<T,U>::value; template <class B> concept Boolean = requires(B b1, B b2) { { bool(b1) }; // direct initialization constraint has to use expression { !b1 } > bool; // compound constraint requires Same<decltype(b1 && b2), bool>; // nested constraint, see below requires Same<decltype(b1  b2), bool>; };
[edit] Nested requirements
A nested requirement is another requiresclause, terminated with a semicolon. This is used to introduce predicate constraints (see above) expressed in terms of other named concepts applied to the local parameters (outside a requires clause, predicate constraints can't use parameters, and placing an expression directly in a requires clause makes it an expression constraint which means it is not evaluated)
template <class T> concept Semiregular = DefaultConstructible<T> && CopyConstructible<T> && Destructible<T> && CopyAssignable<T> && requires(T a, size_t n) { requires Same<T*, decltype(&a)>; // nested: "Same<...> evaluates to true" { a.~T() } noexcept; // compound: "a.~T()" is a valid expression that doesn't throw requires Same<T*, decltype(new T)>; // nested: "Same<...> evaluates to true" requires Same<T*, decltype(new T[n])>; // nested { delete new T }; // compound { delete new T[n] }; // compound };
Concept resolutionLike any other function template, a function concept (but not variable concept) can be overloaded: multiple concept definitions may be provided that all use the same conceptname. Concept resolution is performed when a conceptname (which may be qualified) appears in 1) a constrained type specifier void f(Concept); std::vector<Concept> x = ...;
2) a constrained parameter template<Concept T> void f();
3) a template introduction Concept{T} struct X;
4) a constraintexpression template<typename T> void f() requires Concept<T>;
template<typename T> concept bool C() { return true; } // #1 template<typename T, typename U> concept bool C() { return true; } // #2 void f(C); // the set of concepts referred to by C includes both #1 and #2; // concept resolution (see below) selects #1. In order to perform concept resolution, template parameters of each concept that matches the name (and the qualification, if any) is matched against a sequence of concept arguments, which are template arguments and wildcards. A wildcard can match a template parameter of any kind (type, nontype, template). The argument set is constructed differently, depending on the context 1) For a concept name used as part of a constrained type specifier or parameter, if the concept name is used without a parameter list, the argument list is a single wildcard.
template<typename T> concept bool C1() { return true; } // #1 template<typename T, typename U> concept bool C1() { return true; } // #2 void f1(const C1*); // <wildcard> matches <T>, selects #1 2) For a concept name used as part of a constrained type specifier or parameter, if the concept name is used with a template argument list, the argument list is a single wildcard followed by that argument list.
template<typename T> concept bool C1() { return true; } // #1 template<typename T, typename U> concept bool C1() { return true; } // #2 void f2(C1<char>); // <wildcard, char> matches <T, U>, selects #2 3) If a concept appears in a template introduction, the argument list is a sequence of placeholders as long as the list of parameters in the template introduction
template<typename... Ts> concept bool C3 = true; C3{T} void q2(); // OK: <T> matches <...Ts> C3{...Ts} void q1(); // OK: <...Ts> matches <...Ts> 4) If a concept appears as the name of a templateid, the concept argument list is exactly the sequence of arguments of that templateid
template<typename T> concept bool C() { return true; } // #1 template<typename T, typename U> concept bool C() { return true; } // #2 template <typename T> void f(T) requires C<T>(); // matches #1 Concept resolution is performed by matching each argument against the corresponding parameter of each visible concept. Default template arguments (if used) are instantiated for each paramter that doesn't correspond to an argument, and are then appended to the argument list. Template parameter matches an argument only if it has the same kind (type, nontype, template), unless the argument is a wildcard. A parameter pack matches zero or more arguments as long as all arguments match the pattern in kind (unless they are wildcards). If any argument does not match its corresponding parameter or if there are more arguments than parameters and the last parameter is not a pack, the concept is not viable. If there is zero or more than one viable concept, the program is illformed. template<typename T> concept bool C2() { return true; } template<int T> concept bool C2() { return true; } template<C2<0> T> struct S1; // error: <wildcard, 0> matches // neither <typename T> nor <int T> template<C2 T> struct S2; // both #1 and #2 match: error

(concepts TS) 
[edit] Partial ordering of constraints
Before any further analysis, constraints are normalized by substituting the body of every name concept and every requires expression until what is left is a sequence of conjunctions and disjunctions on atomic constraints, which are predicate constraints, expression constraints, type constraints, implicit conversion constraints, argument deduction constraints, and exception constraints.
Concept P
is said to subsume concept Q
if it can be proven that P
implies Q
without analyzing types and expressions for equivalence (so N >= 0
does not subsume N > 0
)
Specifically, first P
is converted to disjunctive normal form and Q
is converted to conjunctive normal form, and they are compared as follows:
 each atomic constraint
A
subsumes equivalent atomic constraintA
 each atomic constraint
A
subsumes a disjunctionAB
and does not subsume a conjunctionA&&B
 each conjunction
A&&B
subsumesA
, but a disjunctionAB
does not subsumeA
Subsumption relationship defines partial order of constraints, which is used to determine:
 the best viable candidate for a nontemplate function in overload resolution
 the address of a nontemplate function in an overload set
 the best match for a template template argument
 partial ordering of class template specializations
 partial ordering of function templates
This section is incomplete Reason: backlinks from the above to here 
If declarations D1
and D2
are constrained and D1's normalized constraints subsume D2's normalized constraints (or if D1 is constrained and D2 is unconstrained), then D1 is said to be at least as constrained as D2. If D1 is at least as constrained as D2 and D2 is not at least as constrained as D1, then D1 is more constrained than D2.
template<typename T> concept Decrementable = requires(T t) { t; }; template<typename T> concept RevIterator = Decrementable<T> && requires(T t) { *t; }; // RevIterator subsumes Decrementable, but not the other way around // RevIterator is more constrained as Decrementable void f(Decrementable); // #1 void f(RevIterator); // #2 f(0); // int only satisfies Decrementable, selects #1 f((int*)0); // int* satisfies both constraints, selects #2 as more constrained void g(auto); // #3 (unconstrained) void g(Decrementable); // #4 g(true); // bool does not satisfy Decrementable, selects #3 g(0); // int satisfies Decrementable, selects #4 because it is more constrained
[edit] Keywords
[edit] Compiler support
GCC >= 6.1 supports the Concepts TS (required option fconcepts), marked as (concepts TS) in the text of this page.