13 Templates [temp]

13.5 Template constraints [temp.constr]

13.5.2 Constraints [temp.constr.constr]

13.5.2.1 General [temp.constr.constr.general]

13.5.2.2 Logical operations [temp.constr.op]

13.5.2.3 Atomic constraints [temp.constr.atomic]

13.5.2.4 Concept-dependent constraints [temp.constr.concept]

13.5.2.5 Fold expanded constraint [temp.constr.fold]

13.5.2.1 General [temp.constr.constr.general]

A constraint is a sequence of logical operations and operands that specifies requirements on template arguments.

The operands of a logical operation are constraints.

There are five different kinds of constraints:

(1.1)
conjunctions ([temp.constr.op]),
(1.2)
disjunctions ([temp.constr.op]),
(1.3)
atomic constraints ([temp.constr.atomic]),
(1.4)
concept-dependent constraints ([temp.constr.concept]), and
(1.5)
fold expanded constraints ([temp.constr.fold]).

In order for a constrained template to be instantiated ([temp.spec]), its associated constraints shall be satisfied as described in the following subclauses.

[Note 1:

Forming the name of a specialization of a class template, a variable template, or an alias template ([temp.names]) requires the satisfaction of its constraints.

Overload resolution requires the satisfaction of constraints on functions and function templates.

— end note]

13.5.2.2 Logical operations [temp.constr.op]

There are two binary logical operations on constraints: conjunction and disjunction.

[Note 1:

These logical operations have no corresponding C++ syntax.

For the purpose of exposition, conjunction is spelled using the symbol ∧ and disjunction is spelled using the symbol ∨ .

The operands of these operations are called the left and right operands.

In the constraint A ∧ B, A is the left operand, and B is the right operand.

— end note]

A conjunction is a constraint taking two operands.

To determine if a conjunction is satisfied, the satisfaction of the first operand is checked.

If that is not satisfied, the conjunction is not satisfied.

Otherwise, the conjunction is satisfied if and only if the second operand is satisfied.

A disjunction is a constraint taking two operands.

To determine if a disjunction is satisfied, the satisfaction of the first operand is checked.

If that is satisfied, the disjunction is satisfied.

Otherwise, the disjunction is satisfied if and only if the second operand is satisfied.

[Example 1: template<typename T> constexpr bool get_value() { return T::value; } template<typename T> requires (sizeof(T) > 1) && (get_value<T>()) void f(T); // has associated constraint sizeof(T) > 1 ∧ get_value<T>() void f(int); f('a'); // OK, calls f(int)

In the satisfaction of the associated constraints of f, the constraint sizeof(char) > 1 is not satisfied; the second operand is not checked for satisfaction.

— end example]

[Note 2:

A logical negation expression ([expr.unary.op]) is an atomic constraint; the negation operator is not treated as a logical operation on constraints.

As a result, distinct negation constraint-expressions that are equivalent under [temp.over.link] do not subsume one another under [temp.constr.order].

Furthermore, if substitution to determine whether an atomic constraint is satisfied ([temp.constr.atomic]) encounters a substitution failure, the constraint is not satisfied, regardless of the presence of a negation operator.

[Example 2: template <class T> concept sad = false; template <class T> int f1(T) requires (!sad<T>); template <class T> int f1(T) requires (!sad<T>) && true; int i1 = f1(42); // ambiguous, !sad<T> atomic constraint expressions ([temp.constr.atomic]) // are not formed from the same expression template <class T> concept not_sad = !sad<T>; template <class T> int f2(T) requires not_sad<T>; template <class T> int f2(T) requires not_sad<T> && true; int i2 = f2(42); // OK, !sad<T> atomic constraint expressions both come from not_sad template <class T> int f3(T) requires (!sad<typename T::type>); int i3 = f3(42); // error: associated constraints not satisfied due to substitution failure template <class T> concept sad_nested_type = sad<typename T::type>; template <class T> int f4(T) requires (!sad_nested_type<T>); int i4 = f4(42); // OK, substitution failure contained within sad_nested_type

Here, requires (!sad<typename T::type>) requires that there is a nested type that is not sad, whereas requires (!sad_nested_type<T>) requires that there is no sad nested type.

— end example]

— end note]

13.5.2.3 Atomic constraints [temp.constr.atomic]

An atomic constraint is formed from an expression E and a mapping from the template parameters that appear within E to template arguments that are formed via substitution during constraint normalization in the declaration of a constrained entity (and, therefore, can involve the unsubstituted template parameters of the constrained entity), called the parameter mapping ([temp.constr.decl]).

[Note 1:

Atomic constraints are formed by constraint normalization .

E is never a logical and expression nor a logical or expression .

— end note]

Two atomic constraints,

e_{1}

and

e_{2}

, are identical if they are formed from the same appearance of the same expression and if, given a hypothetical template A whose template-parameter-list consists of template-parameters corresponding and equivalent ([temp.over.link]) to those mapped by the parameter mappings of the expression, a template-id naming A whose template-arguments are the targets of the parameter mapping of

e_{1}

is the same ([temp.type]) as a template-id naming A whose template-arguments are the targets of the parameter mapping of

e_{2}

[Note 2:

The comparison of parameter mappings of atomic constraints operates in a manner similar to that of declaration matching with alias template substitution ([temp.alias]).

[Example 1: template <unsigned N> constexpr bool Atomic = true; template <unsigned N> concept C = Atomic<N>; template <unsigned N> concept Add1 = C<N + 1>; template <unsigned N> concept AddOne = C<N + 1>; template <unsigned M> void f() requires Add1<2 * M>; template <unsigned M> int f() requires AddOne<2 * M> && true; int x = f<0>(); // OK, the atomic constraints from concept C in both fs are Atomic<N> // with mapping similar to

N \mapsto 2 * M + 1

template <unsigned N> struct WrapN; template <unsigned N> using Add1Ty = WrapN<N + 1>; template <unsigned N> using AddOneTy = WrapN<N + 1>; template <unsigned M> void g(Add1Ty<2 * M> *); template <unsigned M> void g(AddOneTy<2 * M> *); void h() { g<0>(nullptr); // OK, there is only one g } — end example]

As specified in [temp.over.link], if the validity or meaning of the program depends on whether two constructs are equivalent, and they are functionally equivalent but not equivalent, the program is ill-formed, no diagnostic required.

[Example 2: template <unsigned N> void f2() requires Add1<2 * N>; template <unsigned N> int f2() requires Add1<N * 2> && true; void h2() { f2<0>(); // ill-formed, no diagnostic required: // requires determination of subsumption between atomic constraints that are // functionally equivalent but not equivalent } — end example]

— end note]

To determine if an atomic constraint is satisfied, the parameter mapping and template arguments are first substituted into its expression.

If substitution results in an invalid type or expression in the immediate context of the atomic constraint ([temp.deduct.general]), the constraint is not satisfied.

Otherwise, the lvalue-to-rvalue conversion is performed if necessary, and E shall be a constant expression of type bool.

The constraint is satisfied if and only if evaluation of E results in true.

If, at different points in the program, the satisfaction result is different for identical atomic constraints and template arguments, the program is ill-formed, no diagnostic required.

[Example 3: template<typename T> concept C = sizeof(T) == 4 && !true; // requires atomic constraints sizeof(T) == 4 and !true template<typename T> struct S { constexpr operator bool() const { return true; } }; template<typename T> requires (S<T>{}) void f(T); // #1 void f(int); // #2 void g() { f(0); // error: expression S<int>{} does not have type bool } // while checking satisfaction of deduced arguments of #1; // call is ill-formed even though #2 is a better match — end example]

13.5.2.4 Concept-dependent constraints [temp.constr.concept]

A concept-dependent constraint CD is an atomic constraint whose expression is a concept-id CI whose concept-name names a dependent concept named C.

To determine if CD is satisfied, the parameter mapping and template arguments are first substituted into C.

If substitution results in an invalid concept-id in the immediate context of the constraint ([temp.deduct.general]), the constraint is not satisfied.

Otherwise, let CI

^{'}

be the normal form ([temp.constr.normal]) of the concept-id after substitution of C.

[Note 1:

Normalization of CI might be ill-formed; no diagnostics is required.

— end note]

To form CI

^{''}

, each appearance of C's template parameters in the parameter mappings of the atomic constraints (including concept-dependent constraints) in CI

^{'}

is substituted with their respective arguments from the parameter mapping of CD and the arguments of CI.

CD is satisfied if CI

^{''}

is satisfied.

[Note 2:

Checking whether CI

^{''}

is satisfied can lead to further normalization of concept-dependent constraints.

— end note]

[Example 1: template<typename> concept C = true; template<typename T, template<typename> concept CC> concept D = CC<T>; template<typename U, template<typename> concept CT, template<typename, template<typename> concept> concept CU> int f() requires CU<U, CT>; int i = f<int, C, D>();

In this example, the associated constraints of f consist of a concept-dependent constraint whose expression is the concept-id CU<U, CT> with the mapping

U \mapsto U, CT \mapsto CT, CU \mapsto CU

The result of substituting D into this expression is D<U, CT>.

We consider the normal form of the resulting concept-id, which is CC<T> with the mapping

T \mapsto U, CC \mapsto CT

By recursion, C is substituted into CC<T>, and the result is normalized to the atomic constraint true, which is satisfied.

— end example]

13.5.2.5 Fold expanded constraint [temp.constr.fold]

A fold expanded constraint is formed from a constraint C and a fold-operator which can either be && or ||.

A fold expanded constraint is a pack expansion ([temp.variadic]).

Let N be the number of elements in the pack expansion parameters ([temp.variadic]).

A fold expanded constraint whose fold-operator is && is satisfied if it is a valid pack expansion and if

N = 0

or if for each i where

0 \leq i < N

in increasing order, C is satisfied when replacing each pack expansion parameter with the corresponding

i^{th}

element.

No substitution takes place for any i greater than the smallest i for which the constraint is not satisfied.

A fold expanded constraint whose fold-operator is || is satisfied if it is a valid pack expansion,

N > 0

, and if for i where

0 \leq i < N

in increasing order, there is a smallest i for which C is satisfied when replacing each pack expansion parameter with the corresponding

i^{th}

element.

No substitution takes place for any i greater than the smallest i for which the constraint is satisfied.

[Note 1:

If the pack expansion expands packs of different size, then it is invalid and the fold expanded constraint is not satisfied.

— end note]

Two fold expanded constraints are compatible for subsumption if their respective constraints both contain an equivalent unexpanded pack ([temp.over.link]).