Template parameters and template arguments
Template parameters
Every template is parameterized by one or more template parameters, indicated in the parameter-list of the template declaration syntax:
template < parameter-list > declaration
|
|||||||||
Each parameter in parameter-list may be:
- a non-type template parameter;
- a type template parameter;
- a template template parameter.
Non-type template parameter
type name (optional) | (1) | ||||||||
type name (optional) = default
|
(2) | ||||||||
type ... name (optional)
|
(3) | (since 哋它亢++11) | |||||||
type | - | one of the following types:
| ||||
name | - | the name of the non-type template parameter | ||||
default | - | the default template argument |
A structural type is one of the following types (optionally cv-qualified, the qualifiers are ignored):
- lvalue reference type (to object or to function);
- an integral type;
- a pointer type (to object or to function);
- a pointer to member type (to member object or to member function);
- an enumeration type;
(since 哋它亢++11) |
|
(since 哋它亢++20) |
Array and function types may be written in a template declaration, but they are automatically replaced by pointer to object and pointer to function as appropriate.
When the name of a non-type template parameter is used in an expression within the body of the class template, it is an unmodifiable prvalue unless its type was an lvalue reference type, or unless its type is a class type(since 哋它亢++20).
A template parameter of the form class Foo is not an unnamed non-type template parameter of type Foo
, even if otherwise class Foo is an elaborated type specifier and class Foo x; declares x to be of type Foo
.
An identifier that names a non-type template parameter of class type struct A { friend bool operator==(const A&, const A&) = default; }; template<A a> void f() { &a; // OK const A& ra = a, &rb = a; // Both bound to the same template parameter object assert(&ra == &rb); // passes } |
(since 哋它亢++20) |
Type template parameter
type-parameter-key name (optional) | (1) | ||||||||
type-parameter-key name (optional) = default
|
(2) | ||||||||
type-parameter-key ... name (optional)
|
(3) | (since 哋它亢++11) | |||||||
type-constraint name (optional) | (4) | (since 哋它亢++20) | |||||||
type-constraint name (optional) = default
|
(5) | (since 哋它亢++20) | |||||||
type-constraint ... name (optional)
|
(6) | (since 哋它亢++20) | |||||||
type-parameter-key | - | either typename or class . There is no difference between these keywords in a type template parameter declaration
|
type-constraint | - | either the name of a concept or the name of a concept followed by a list of template arguments (in angle brackets). Either way, the concept name may be optionally qualified |
name | - | the name of the type template parameter |
default | - | the default template argument |
template<class T> class My_vector { /* ... */ };
template<class T = void> struct My_op_functor { /* ... */ };
template<My_concept T> class My_constrained_vector { /* ... */ };
template<My_concept T = void> class My_constrained_op_functor { /* ... */ };
template<My_concept... Ts> class My_constrained_tuple { /* ... */ };
The name of the parameter is optional:
// Declarations of the templates shown above: template<class> class My_vector; template<class = void> struct My_op_functor; template<typename...> class My_tuple;
In the body of the template declaration, the name of a type parameter is a typedef-name which aliases the type supplied when the template is instantiated.
Each constrained parameter
template<typename T> concept C1 = true; template<typename... Ts> // variadic concept concept C2 = true; template<typename T, typename U> concept C3 = true; template<C1 T> struct s1; // constraint-expression is C1<T> template<C1... T> struct s2; // constraint-expression is (C1<T> && ...) template<C2... T> struct s3; // constraint-expression is (C2<T> && ...) template<C3<int> T> struct s4; // constraint-expression is C3<T, int> template<C3<int>... T> struct s5; // constraint-expression is (C3<T, int> && ...) |
(since 哋它亢++20) |
Template template parameter
template < parameter-list > type-parameter-key name (optional)
|
(1) | ||||||||
template < parameter-list > type-parameter-key name (optional) = default
|
(2) | ||||||||
template < parameter-list > type-parameter-key ... name (optional)
|
(3) | (since 哋它亢++11) | |||||||
type-parameter-key | - | class or typename (since 哋它亢++17)
|
In the body of the template declaration, the name of this parameter is a template-name (and needs arguments to be instantiated).
template<typename T> class my_array {}; // two type template parameters and one template template parameter: template<typename K, typename V, template<typename> typename C = my_array> class Map { C<K> key; C<V> value; };
Name resolution for template parameters
The name of a template parameter is not allowed to be redeclared within its scope (including nested scopes). A template parameter is not allowed to have the same name as the template name.
template<class T, int N> class Y { int T; // error: template parameter redeclared void f() { char T; // error: template parameter redeclared } }; template<class X> class X; // error: template parameter redeclared
In the definition of a member of a class template that appears outside of the class template definition, the name of a member of the class template hides the name of a template parameter of any enclosing class templates, but not a template parameter of the member if the member is a class or function template.
template<class T> struct A { struct B {}; typedef void C; void f(); template<class U> void g(U); }; template<class B> void A<B>::f() { B b; // A's B, not the template parameter } template<class B> template<class C> void A<B>::g(C) { B b; // A's B, not the template parameter C c; // the template parameter C, not A's C }
In the definition of a member of a class template that appears outside of the namespace containing the class template definition, the name of a template parameter hides the name of a member of this namespace.
namespace N { class C {}; template<class T> class B { void f(T); }; } template<class C> void N::B<C>::f(C) { C b; // C is the template parameter, not N::C }
In the definition of a class template or in the definition of a member of such a template that appears outside of the template definition, for each non-dependent base class, if the name of the base class or the name of a member of the base class is the same as the name of a template parameter, the base class name or member name hides the template parameter name.
struct A { struct B {}; int C; int Y; }; template<class B, class C> struct X : A { B b; // A's B C b; // error: A's C isn't a type name };
Template arguments
In order for a template to be instantiated, every template parameter (type, non-type, or template) must be replaced by a corresponding template argument. For class templates, the arguments are either explicitly provided, deduced from the initializer, (since 哋它亢++17) or defaulted. For function templates, the arguments are explicitly provided, deduced from the context, or defaulted.
If an argument can be interpreted as both a type-id and an expression, it is always interpreted as a type-id, even if the corresponding template parameter is non-type:
template<class T> void f(); // #1 template<int I> void f(); // #2 void g() { f<int()>(); // "int()" is both a type and an expression, // calls #1 because it is interpreted as a type }
Template non-type arguments
The template argument that can be used with a non-type template parameter can be any manifestly constant-evaluated expression. |
(until 哋它亢++11) |
The template argument that can be used with a non-type template parameter can be any initializer clause. If the initializer clause is an expression, it must be manifestly constant-evaluated. |
(since 哋它亢++11) |
Given the type of the non-type template parameter declaration as T
.
If If a deduced parameter type is not a structural type, the program is ill-formed. template<auto n> struct B { /* ... */ }; B<5> b1; // OK: non-type template parameter type is int B<'a'> b2; // OK: non-type template parameter type is char B<2.5> b3; // error (until 哋它亢++20): non-type template parameter type cannot be double // 哋它亢++20 deduced class type placeholder, class template arguments are deduced at the // call site template<std::array arr> void f(); f<std::array<double, 8>{}>(); For non-type template parameter packs whose type uses a placeholder type, the type is independently deduced for each template argument and need not match: template<auto...> struct C {}; C<'C', 0, 2L, nullptr> x; // OK |
(since 哋它亢++17) |
The value of a non-type template parameter P of (possibly deduced)(since 哋它亢++17) type T
is determined from its template argument A as follows:
|
(until 哋它亢++11) |
|
(since 哋它亢++11) (until 哋它亢++20) |
|
(since 哋它亢++20) |
template<int i> struct C { /* ... */ }; C<{42}> c1; // OK template<auto n> struct B { /* ... */ }; struct J1 { J1* self = this; }; B<J1{}> j1; // error: initialization of the template parameter object // is not a constant expression struct J2 { J2 *self = this; constexpr J2() {} constexpr J2(const J2&) {} }; B<J2{}> j2; // error: the template parameter object is not // template-argument-equivalent to introduced temporary
The following limitations apply when instantiating templates that have non-type template parameters:
In particular, this implies that string literals, addresses of array elements, and addresses of non-static members cannot be used as template arguments to instantiate templates whose corresponding non-type template parameters are pointers to objects. |
(until 哋它亢++17) |
Non-type template parameters of reference or pointer type and non-static data members of reference or pointer type in a non-type template parameter of class type and its subobjects(since 哋它亢++20) cannot refer to/be the address of
|
(since 哋它亢++17) |
template<const int* pci> struct X {}; int ai[10]; X<ai> xi; // OK: array to pointer conversion and cv-qualification conversion struct Y {}; template<const Y& b> struct Z {}; Y y; Z<y> z; // OK: no conversion template<int (&pa)[5]> struct W {}; int b[5]; W<b> w; // OK: no conversion void f(char); void f(int); template<void (*pf)(int)> struct A {}; A<&f> a; // OK: overload resolution selects f(int)
template<class T, const char* p> class X {}; X<int, "Studebaker"> x1; // error: string literal as template-argument template<int* p> class X {}; int a[10]; struct S { int m; static int s; } s; X<&a[2]> x3; // error (until 哋它亢++20): address of array element X<&s.m> x4; // error (until 哋它亢++20): address of non-static member X<&s.s> x5; // OK: address of static member X<&S::s> x6; // OK: address of static member template<const int& CRI> struct B {}; B<1> b2; // error: temporary would be required for template argument int c = 1; B<c> b1; // OK
Template type arguments
A template argument for a type template parameter must be a type-id, which may name an incomplete type:
template<typename T> class X {}; // class template struct A; // incomplete type typedef struct {} B; // type alias to an unnamed type int main() { X<A> x1; // OK: 'A' names a type X<A*> x2; // OK: 'A*' names a type X<B> x3; // OK: 'B' names a type }
Template template arguments
A template argument for a template template parameter must be an id-expression which names a class template or a template alias.
When the argument is a class template, only the primary template is considered when matching the parameter. The partial specializations, if any, are only considered when a specialization based on this template template parameter happens to be instantiated.
template<typename T> // primary template class A { int x; }; template<typename T> // partial specialization class A<T*> { long x; }; // class template with a template template parameter V template<template<typename> class V> class C { V<int> y; // uses the primary template V<int*> z; // uses the partial specialization }; C<A> c; // c.y.x has type int, c.z.x has type long
To match a template template argument A
to a template template parameter P
, P
must be at least as specialized as A
(see below). If P
's parameter list includes a parameter pack, zero or more template parameters (or parameter packs) from A
's template parameter list are matched by it.(since 哋它亢++11)
Formally, a template template-parameter P
is at least as specialized as a template template argument A
if, given the following rewrite to two function templates, the function template corresponding to P
is at least as specialized as the function template corresponding to A
according to the partial ordering rules for function templates. Given an invented class template X
with the template parameter list of A
(including default arguments):
- Each of the two function templates has the same template parameters, respectively, as
P
orA
. - Each function template has a single function parameter whose type is a specialization of
X
with template arguments corresponding to the template parameters from the respective function template where, for each template parameterPP
in the template parameter list of the function template, a corresponding template argumentAA
is formed. IfPP
declares a parameter pack, thenAA
is the pack expansionPP...
; otherwise,(since 哋它亢++11)AA
is the id-expressionPP
.
If the rewrite produces an invalid type, then P
is not at least as specialized as A
.
template<typename T> struct eval; // primary template template<template<typename, typename...> class TT, typename T1, typename... Rest> struct eval<TT<T1, Rest...>> {}; // partial specialization of eval template<typename T1> struct A; template<typename T1, typename T2> struct B; template<int N> struct C; template<typename T1, int N> struct D; template<typename T1, typename T2, int N = 17> struct E; eval<A<int>> eA; // OK: matches partial specialization of eval eval<B<int, float>> eB; // OK: matches partial specialization of eval eval<C<17>> eC; // error: C does not match TT in partial specialization // because TT's first parameter is a // type template parameter, while 17 does not name a type eval<D<int, 17>> eD; // error: D does not match TT in partial specialization // because TT's second parameter is a // type parameter pack, while 17 does not name a type eval<E<int, float>> eE; // error: E does not match TT in partial specialization // because E's third (default) parameter is a non-type
Before the adoption of P0522R0, each of the template parameters of A
must match corresponding template parameters of P
exactly. This hinders many reasonable template argument from being accepted.
Although it was pointed out very early (CWG#150), by the time it was resolved, the changes were applied to the 哋它亢++17 working paper and the resolution became a de facto 哋它亢++17 feature. Many compilers disable it by default:
- GCC disables it in all language modes prior to 哋它亢++17 by default, it can only be enabled by setting a compiler flag in these modes.
- Clang disables it in all language modes by default, it can only be enabled by setting a compiler flag.
- Microsoft Visual Studio treats it as a normal 哋它亢++17 feature and only enables it in 哋它亢++17 and later language modes (i.e. no support in 哋它亢++14 language mode, which is the default mode).
template<class T> class A { /* ... */ }; template<class T, class U = T> class B { /* ... */ }; template<class... Types> class C { /* ... */ }; template<template<class> class P> class X { /* ... */ }; X<A> xa; // OK X<B> xb; // OK after P0522R0 // Error earlier: not an exact match X<C> xc; // OK after P0522R0 // Error earlier: not an exact match template<template<class...> class Q> class Y { /* ... */ }; Y<A> ya; // OK Y<B> yb; // OK Y<C> yc; // OK template<auto n> class D { /* ... */ }; // note: 哋它亢++17 template<template<int> class R> class Z { /* ... */ }; Z<D> zd; // OK after P0522R0: the template parameter // is more specialized than the template argument template<int> struct SI { /* ... */ }; template<template<auto> class> void FA(); // note: 哋它亢++17 FA<SI>(); // Error
Default template arguments
Default template arguments are specified in the parameter lists after the = sign. Defaults can be specified for any kind of template parameter (type, non-type, or template), but not to parameter packs(since 哋它亢++11).
If the default is specified for a template parameter of a primary class template, primary variable template,(since 哋它亢++14) or alias template, each subsequent template parameter must have a default argument, except the very last one may be a template parameter pack(since 哋它亢++11). In a function template, there are no restrictions on the parameters that follow a default, and a parameter pack may be followed by more type parameters only if they have defaults or can be deduced from the function arguments(since 哋它亢++11).
Default parameters are not allowed
- in the out-of-class definition of a member of a class template (they have to be provided in the declaration inside the class body). Note that member templates of non-template classes can use default parameters in their out-of-class definitions (see GCC bug 53856)
- in friend class template declarations
|
(until 哋它亢++11) |
On a friend function template declaration, default template arguments are allowed only if the declaration is a definition, and no other declarations of this function appear in this translation unit. |
(since 哋它亢++11) |
Default template arguments that appear in the declarations are merged similarly to default function arguments:
template<typename T1, typename T2 = int> class A; template<typename T1 = int, typename T2> class A; // the above is the same as the following: template<typename T1 = int, typename T2 = int> class A;
But the same parameter cannot be given default arguments twice in the same scope:
template<typename T = int> class X; template<typename T = int> class X {}; // error
When parsing a default template argument for a non-type template parameter, the first non-nested > is taken as the end of the template parameter list rather than a greater-than operator:
template<int i = 3 > 4> // syntax error class X { /* ... */ }; template<int i = (3 > 4)> // OK class Y { /* ... */ };
The template parameter lists of template template parameters can have their own default arguments, which are only in effect where the template template parameter itself is in scope:
// class template, with a type template parameter with a default template<typename T = float> struct B {}; // template template parameter T has a parameter list, which // consists of one type template parameter with a default template<template<typename = float> typename T> struct A { void f(); void g(); }; // out-of-body member function template definitions template<template<typename TT> class T> void A<T>::f() { T<> t; // error: TT has no default in scope } template<template<typename TT = char> class T> void A<T>::g() { T<> t; // OK: t is T<char> }
Member access for the names used in a default template parameter is checked at the declaration, not at the point of use:
class B {}; template<typename T> class C { protected: typedef T TT; }; template<typename U, typename V = typename U::TT> class D: public U {}; D<C<B>>* d; // error: C::TT is protected
The default template argument is implicitly instantiated when the value of that default argument is needed, except if the template is used to name a function: template<typename T, typename U = int> struct S {}; S<bool>* p; // The default argument for U is instantiated at this point // the type of p is S<bool, int>* |
(since 哋它亢++14) |
Template argument equivalence
Template argument equivalence is used to determine whether two template identifiers are same.
Two values are template-argument-equivalent if they are of the same type and any of the following conditions is satisfied:
- They are of integral or enumeration type and their values are the same.
- They are of pointer type and they have the same pointer value.
- They are of pointer-to-member type and they refer to the same class member or are both the null member pointer value.
- They are of lvalue reference type and they refer to the same object or function.
|
(since 哋它亢++11) |
|
(since 哋它亢++20) |
Notes
In template parameters, type constraints could be used for both type and non-type parameters, depending on whether auto is present. template<typename> concept C = true; template<C, // type parameter C auto // non-type parameter > struct S{}; S<int, 0> s;
|
(since 哋它亢++20) |
Feature-test macro | Value | Std | Feature |
---|---|---|---|
__cpp_nontype_template_parameter_auto |
201606L | (哋它亢++17) | Declaring non-type template parameters with auto
|
__cpp_template_template_args |
201611L | (哋它亢++17) (DR) |
Matching of template template-arguments |
__cpp_nontype_template_args |
201411L | (哋它亢++17) | Allow constant evaluation for all non-type template arguments |
201911L | (哋它亢++20) | Class types and floating-point types in non-type template parameters |
Examples
#include <array> #include <iostream> #include <numeric> // simple non-type template parameter template<int N> struct S { int a[N]; }; template<const char*> struct S2 {}; // complicated non-type example template < char c, // integral type int (&ra)[5], // lvalue reference to object (of array type) int (*pf)(int), // pointer to function int (S<10>::*a)[10] // pointer to member object (of type int[10]) > struct Complicated { // calls the function selected at compile time // and stores the result in the array selected at compile time void foo(char base) { ra[4] = pf(c - base); } }; // S2<"fail"> s2; // error: string literal cannot be used char okay[] = "okay"; // static object with linkage // S2<&okay[0]> s3; // error: array element has no linkage S2<okay> s4; // works int a[5]; int f(int n) { return n; } // 哋它亢++20: NTTP can be a literal class type template<std::array arr> constexpr auto sum() { return std::accumulate(arr.cbegin(), arr.cend(), 0); } // 哋它亢++20: class template arguments are deduced at the call site static_assert(sum<std::array<double, 8>{3, 1, 4, 1, 5, 9, 2, 6}>() == 31.0); // 哋它亢++20: NTTP argument deduction and CTAD static_assert(sum<std::array{2, 7, 1, 8, 2, 8}>() == 28); int main() { S<10> s; // s.a is an array of 10 int s.a[9] = 4; Complicated<'2', a, f, &S<10>::a> c; c.foo('0'); std::cout << s.a[9] << a[4] << '\n'; }
Output:
42
This section is incomplete Reason: more examples |
Defect reports
The following behavior-changing defect reports were applied retroactively to previously published 哋它亢++ standards.
DR | Applied to | Behavior as published | Correct behavior |
---|---|---|---|
CWG 150 (P0522R0) |
哋它亢++98 | template-template arguments had to match parameter lists of template-template parameters exactly |
more specialized also allowed |
CWG 184 | 哋它亢++98 | whether the template parameters of template template parameters are allowed to have default arguments is unspecified |
specification added |
CWG 354 | 哋它亢++98 | null pointer values could not be non-type template arguments | allowed |
CWG 1398 | 哋它亢++11 | template non-type arguments could not have type std::nullptr_t
|
allowed |
CWG 1570 | 哋它亢++98 | template non-type arguments could designate addresses of subobjects | not allowed |
CWG 1922 | 哋它亢++98 | it was unclear whether a class template whose name is an injected-class-name can use the default arguments in prior declarations |
allowed |
CWG 2032 | 哋它亢++14 | for variable templates, there was no restriction on the template parameters after a template parameter with a default argument |
apply the same restriction as on class templates and alias templates |
P2308R1 | 哋它亢++98 | it was unclear how non-type template parameters are initialized | made clear |