Experimental Feature The functionality described on this page is part of the Concepts Technical Specification ISO/IEC TS 19217:2015(concepts TS). For the version of this feature adopted in C++20, seehere.

This page describes an experimental core language feature. For named type requirements used in the specification of the standard library, seenamed requirements

Class templates,function templates, and non-template functions (typically members of class templates) may be associated with aconstraint, 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 calledconcepts. 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>usingnamespace 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 booltemplate<typename T>conceptbool EqualityComparable= requires(T a, T b){{ a== b}->bool;}; void f(EqualityComparable&&);// declaration of a constrained function template// template<typename T>// void f(T&&) requires EqualityComparable<T>; // long form of the same 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 toISO 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 here are indicated by the macro constant__cpp_concepts with a value equal or greater201507.

[edit]Placeholders

The unconstrained placeholderauto andconstrained placeholders which have the formconcept-name<template-argument-list(optional)>, are placeholders for the type that is to be deduced.

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)

void f(std::pair<auto, EqualityComparable>);// this is a template with two parameters:// unconstrained type parameter and a constrained non-type parameter

Constrained placeholders may be used anywhereauto may be used, for example, in generic lambda declarations

auto gl=[](Assignable& a,auto* b){ a=*b;};

If constrained type specifier designates a non-type or a template, but is used as a constrained placeholder, the program is ill-formed:

template<size_t N> conceptbool Even=(N%2==0);struct S1{int n;};int Even::* p2=&S1::n;// error, invalid use of a non-type conceptvoid f(std::array<auto, Even>);// error, invalid use of a non-type concepttemplate<Even N>void f(std::array<auto, N>);// OK

[edit]Abbreviated templates

If 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 formvoid 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 (auto) always introduces a different template parameter

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 atemplate introduction, which has the syntaxconcept-name{parameter-list(optional)}, in which case the keywordtemplate is not needed: each parameter from theparameter-list of the template introduction becomes a template parameter whose kind (type, non-type, template) is determined by the kind of the corresponding parameter in the named concept.

Besides declaring a template, template introduction associates apredicate 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> conceptbool 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);

[edit]Concepts

A concept is a named set of requirements. The definition of a concept appears at namespace scope and has the form of afunction template definition (in which case it is calledfunction concept) orvariable template definition (in which case it is calledvariable concept). The only difference is that the keywordconcept appears in thedecl-specifier-seq:

// variable concept from the standard library (Ranges TS)template<class T,class U>conceptbool Derived=std::is_base_of<U, T>::value; // function concept from the standard library (Ranges TS)template<class T>conceptbool EqualityComparable(){return requires(T a, T b){{a== b}-> Boolean;{a!= b}-> Boolean;};}

The following restrictions apply to function concepts:

• inline andconstexpr are not allowed, the function is automaticallyinline andconstexpr
• friend andvirtual are not allowed
• exception specification is not allowed, the function is automaticallynoexcept(true).
• cannot be declared and defined later, cannot be redeclared
• the return type must bebool
• return type deduction is not allowed
• parameter list must be empty
• the function body must consist of only areturn statement, whose argument must be aconstraint-expression (predicate constraint, conjunction/disjunction of other constraints, or a requires-expression, see below)

The following restrictions apply to variable concepts:

• Must have the typebool
• Cannot be declared without an initializer
• Cannot be declared or at class scope.
• constexpr is not allowed, the variable is automaticallyconstexpr
• the initializer must be a constraint expression (predicate constraint, conjunction/disjunction of constraints, or a requires-expression, see below)

Concepts cannot recursively refer to themselves in the body of the function or in the initializer of the variable:

template<typename T>conceptbool F(){return F<typename T::type>();}// errortemplate<typename T>conceptbool V= V<T*>;// error

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 withinrequires-expressions (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 ad-hoc requires-clause:

template<typename T>requires// requires-clause (ad-hoc constraint)sizeof(T)>1&& get_value<T>()// conjunction of two predicate constraintsvoid f(T);

When multiple constraints are attached to the same declaration, the total constraint is a conjunction in the following order: the constraint introduced bytemplate introduction, constraints for each template parameter in order of appearance, therequires clause after the template parameter list, constraints for each function parameter in order of appearance, trailingrequires 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 // 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 ill-formed, no diagnostic required template<Incrementable T> requires Decrementable<T>void g();template<Decrementable T> requires Incrementable<T>void g();// error

[edit]Conjunctions

Conjunction of constraintsP andQ is specified asP&& Q.

// example concepts from the standard library (Ranges TS)template<class T>conceptbool Integral=std::is_integral<T>::value;template<class T>conceptbool SignedIntegral= Integral<T>&&std::is_signed<T>::value;template<class T>conceptbool 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 short-circuited (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). User-defined overloads ofoperator&& are not allowed in constraint conjunctions.

[edit]Disjunctions

Disjunction of constraintsP andQ is specified asP|| Q.

A disjunction of two constraints is satisfied if either constraint is satisfied. Disjunctions are evaluated left to right and short-circuited (if the left constraint is satisfied, template argument deduction into the right constraint is not attempted). User-defined overloads ofoperator|| are not allowed in constraint disjunctions.

// example constraint from the standard library (Ranges TS)template<class T=void>requires EqualityComparable<T>()|| Same<T,void>struct equal_to;

[edit]Predicate constraints

A predicate constraint is a constant expression of typebool. It is satisfied only if it evaluates totrue

template<typename T> conceptbool Size32= sizeof(T)==4;

Predicate constraints can specify requirements on non-type template parameters and on template template arguments.

Predicate constraints must evaluate directly tobool, no conversions allowed:

template<typename T>struct S{constexprexplicit operatorbool()const{returntrue;}};template<typename T>requires S<T>{}// bad predicate constraint: S<T>{} is not boolvoid f(T);f(0);// error: constraint never satisfied

[edit]Requirements

The keywordrequires 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 listT add(T a, T b){return a+ b;}

template<typename T>conceptbool Addable= requires(T x){ x+ x;};// requires-expression template<typename T> requires Addable<T>// requires-clause, not requires-expressionT add(T a, T b){return a+ b;} template<typename T>requires requires(T x){ x+ x;}// ad-hoc constraint, note keyword used twiceT add(T a, T b){return a+ b;}

The syntax ofrequires-expression is as follows:

Each requirement in therequirements-seq 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 theparameter-list. When parametrized, a requires-expression is said to introduce aparametrized constraint

The substitution of template arguments into a requires-expression may result in the formationof invalid types or expressions in its requirements. In such cases,

• If a substitution failure occurs in a requires-expression that is used outside of atemplated entity declaration, then the program is ill-formed.
• If the requires-expression is used in a declaration of atemplated entity, the corresponding constraint is treated as "not satisfied" and thesubstitution failure is not an error, however
• If a substitution failure would occur in a requires-expression for every possible template argument, the program is ill-formed, no diagnostic required:

template<class T> conceptbool C= requires{    newint[-(int)sizeof(T)];// invalid for every T: ill-formed, no diagnostic required};

[edit]Simple requirements

A simple requirement is an arbitrary expression statement. The requirement is that the expression is valid (this is anexpression constraint). Unlike with predicate constraints, evaluation does not take place, only language correctness is checked.

template<typename T>conceptbool Addable=requires(T a, T b){    a+ b;// "the expression a+b is a valid expression that will compile"}; // example constraint from the standard library (ranges TS)template<class T,class U= T>conceptbool 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 keywordtypename followed by a type name, optionally qualified. The requirement is that the named type exists (atype 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> conceptbool C=requires{typename T::inner;// required nested member nametypename S<T>;// required class template specializationtypename Ref<T>;// required alias template substitution}; //Example concept from the standard library (Ranges TS)template<class T,class U>using CommonType=std::common_type_t<T, U>;template<class T,class U> conceptbool 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

and specifies a conjunction of the following constraints:

template<typename T> conceptbool 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}; // Example concept from the standard library (Ranges TS)template<class T,class U> conceptbool Same=std::is_same<T,U>::value;template<class B> conceptbool 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 anotherrequires-clause, terminated with a semicolon. This is used to introducepredicate 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)

// example constraint from Ranges TStemplate<class T>conceptbool 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};

[edit]Concept resolution

Like any other function template, a function concept (but not variable concept) can be overloaded: multiple concept definitions may be provided that all use the sameconcept-name.

Concept resolution is performed when aconcept-name (which may be qualified) appears in

template<typename T> conceptbool C(){returntrue;}// #1template<typename T,typename U> conceptbool C(){returntrue;}// #2void 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 ofconcept arguments, which are template arguments andwildcards. A wildcard can match a template parameter of any kind (type, non-type, template). The argument set is constructed differently, depending on the context

template<typename T> conceptbool C1(){returntrue;}// #1template<typename T,typename U> conceptbool C1(){returntrue;}// #2void f1(const C1*);// <wildcard> matches <T>, selects #1

template<typename T> conceptbool C1(){returntrue;}// #1template<typename T,typename U> conceptbool C1(){returntrue;}// #2void f2(C1<char>);// <wildcard, char> matches <T, U>, selects #2

template<typename...Ts>conceptbool C3=true;C3{T}void q2();// OK: <T> matches <...Ts>C3{...Ts}void q1();// OK: <...Ts> matches <...Ts>

template<typename T> conceptbool C(){returntrue;}// #1template<typename T,typename U> conceptbool C(){returntrue;}// #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, non-type, 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 ill-formed.

template<typename T> conceptbool C2(){returntrue;}template<int T> conceptbool C2(){returntrue;} 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

[edit]Partial ordering of constraints

Before any further analysis, constraints arenormalized 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.

ConceptP is said tosubsume conceptQ if it can be proven thatPimpliesQ without analyzing types and expressions for equivalence (soN >= 0 does not subsumeN > 0)

Specifically, firstP is converted to disjunctive normal form andQ is converted to conjunctive normal form, and they are compared as follows:

• each atomic constraintA subsumes equivalent atomic constraintA
• each atomic constraintA subsumes a disjunctionA||B and does not subsume a conjunctionA&&B
• each conjunctionA&&B subsumesA, but a disjunctionA||B does not subsumeA

Subsumption relationship defines partial order of constraints, which is used to determine:

• the best viable candidate for a non-template function inoverload resolution
• theaddress of a non-template function in an overload set
• the best match for a template template argument
• partial ordering of class template specializations
• partial ordering of function templates

If declarationsD1 andD2 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 beat 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 ismore constrained than D2.

template<typename T>conceptbool Decrementable= requires(T t){--t;};template<typename T>conceptbool 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);// #1void f(RevIterator);// #2 f(0);// int only satisfies Decrementable, selects #1f((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 #3g(0);// int satisfies Decrementable, selects #4 because it is more constrained

[edit]Keywords

concept,requires

[edit]Compiler support

GCC >= 6.1 supports this technical specification (required option-fconcepts)

• In other languages

• Deutsch
• Español
• Français
• Italiano
• 日本語
• Português
• Русский
• 中文