cpp/experimental/constraints

__NOINDEX__

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

Class templates, function templates, and non-template 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:

Violations of constraints are detected at compile time, early in the template instantiation process, which leads to easy to follow error messages.

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 here are indicated by the macro constant with a value equal or greater.

Placeholders
The unconstrained placeholder and constrained placeholders which have the form  , 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)

Placeholders may also appear in parameters, in which case they turn function declarations into template declarations (constrained if the placeholder is constrained)

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

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

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

All placeholders introduced by equivalent constrained type specifiers have the same invented template parameter. However, each unconstrained specifier always introduces a different template parameter

Both function templates and class templates can be declared using a template introduction, which has the syntax {{ttb|{}} {{ttb|} }}, in which case the keyword  is not needed: each parameter from the  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 a predicate constraint (see below) that names (for variable concepts) or invokes (for function concepts) the concept named by the introduction.

For function templates, template introduction can be combined with placeholders:

Concepts
A concept is a named set of requirements. The definition of a concept appears at namespace scope and 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 appears in the :

The following restrictions apply to function concepts:
 * and are not allowed, the function is automatically  and
 * and are not allowed
 * exception specification is not allowed, the function is automatically.
 * cannot be declared and defined later, cannot be redeclared
 * the return type must be
 * return type deduction is not allowed
 * parameter list must be empty
 * the function body must consist of only a statement, whose argument must be a constraint-expression (predicate constraint, conjunction/disjunction of other constraints, or a requires-expression, see below)

The following restrictions apply to variable concepts:
 * Must have the type
 * Cannot be declared without an initializer
 * Cannot be declared or at class scope.
 * is not allowed, the variable is automatically
 * 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:

Explicit instantiations, explicit specializations, or partial specializations of concepts are not allowed (the meaning of the original definition of a constraint cannot be changed)

Constraints
A constraint is a sequence of logical operations that specifies requirements on template arguments. They can appear within requires-expressions (see below) and directly as bodies of concepts

There are 9 types of constraints: @1@ conjunctions @2@ disjunctions @3@ predicate constraints @4@ expression constraints (only in a requires-expression) @5@ type constraints (only in a requires-expression) @6@ implicit conversion constraints (only in a requires-expression) @7@ argument deduction constraints (only in a requires-expression) @8@ exception constraints (only in a requires-expression) @9@ parametrized constraints (only in a requires-expression)

The first three types of constraints may appear directly as the body of a concept or as an ad-hoc requires-clause:

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:

Conjunctions
Conjunction of constraints and  is specified as.

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 of are not allowed in constraint conjunctions.

Disjunctions
Disjunction of constraints and  is specified as.

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 of are not allowed in constraint disjunctions.

Predicate constraints
A predicate constraint is a constant expression of type. It is satisfied only if it evaluates to

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

Predicate constraints must evaluate directly to, no conversions allowed:

Requirements
The keyword is used in two ways: @1@ To introduce a requires-clause, which specifies constraints on template arguments or on a function declaration.

@@ 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 requires-expression is used. @2@ To begin a requires-expression, which is a prvalue expression of type that describes the constraints on some template arguments. Such expression is if the corresponding concept is satisfied, and false otherwise:

The syntax of requires-expression is as follows:

{{par | | a comma-separated 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 {{ttb|} }} of the. If no parameters are used, the round parentheses may be omitted as well }}

Each requirement in the 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. When parametrized, a requires-expression is said to introduce a parametrized constraint

The substitution of template arguments into a requires-expression may result in the formation of invalid types or expressions in its requirements. In such cases,
 * If a substitution failure occurs in a requires-expression that is used outside of a templated entity declaration, then the program is ill-formed.
 * If the requires-expression 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 requires-expression for every possible template argument, the program is ill-formed, no diagnostic required:

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.

Type requirements
A type requirement is the keyword 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.

Compound Requirements
A compound requirement has the form

and specifies a conjunction of the following constraints: @1@ is a valid expression (expression constraint) @2@ If is used, expression must also be noexcept (exception constraint) @3@ If that names a type that uses placeholders, the type must be deducible from the type of the expression (argument deduction constraint) @4@ If that names a type that does not use placeholders, then two more constraints are added:
 * @4a@ the type named by is valid (type constraint)
 * @4b@ the result of the expression is implicitly convertible to that type (implicit conversion constraint)

Nested requirements
A nested requirement is another requires-clause, 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)

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 same.

Concept resolution is performed when a (which may be qualified) appears in @1@ a constrained type specifier @2@ a constrained parameter @3@ a template introduction @4@ a constraint-expression

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, non-type, 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.

@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.

@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

@4@ If a concept appears as the name of a template-id, the concept argument list is exactly the sequence of arguments of that template-id

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.

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 is said to subsume concept  if it can be proven that  implies  without analyzing types and expressions for equivalence (so  does not subsume )

Specifically, first is converted to disjunctive normal form and  is converted to conjunctive normal form, and they are compared as follows:
 * each atomic constraint subsumes equivalent atomic constraint
 * each atomic constraint subsumes a disjunction  and does not subsume a conjunction
 * each conjunction subsumes, but a disjunction  does not subsume

Subsumption relationship defines partial order of constraints, which is used to determine:
 * the best viable candidate for a non-template function in overload resolution
 * the address 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 declarations and  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.

Keywords
,

Compiler support
GCC >= 6.1 supports this technical specification (required option )