Templates

A template is a C++ entity that defines one of the following:

• a family of classes (class template), which may be nested classes
• a family of functions (function template), which may be member functions

Templates are parameterized by one or more template parameters, of three kinds: type template parameters, non-type template parameters, and template template parameters.

When template arguments are provided, or, for function and class (since C++17) templates only, deduced, they are substituted for the template parameters to obtain a specialization of the template, that is, a specific type or a specific function lvalue. Specializations may also be provided explicitly: full specializations are allowed for class, variable (since C++14) and function templates, partial specializations are only allowed for class templates and variable templates (since C++14).

When a class template specialization is referenced in context that requires a complete object type, or when a function template specialization is referenced in context that requires a function definition to exist, the template is instantiated (the code for it is actually compiled), unless the template was already explicitly specialized or explicitly instantiated. Instantiation of a class template doesn't instantiate any of its member functions unless they are also used. At link time, identical instantiations generated by different translation units are merged.

The definition of a class template must be visible at the point of implicit instantiation, which is why template libraries typically provide all template definitions in the headers (e.g. most boost libraries are header-only).

Syntax

template-id

A simple-template-id that names a class template specialization names a class.

A template-id that names an alias template specialization names a type.

A template-id that names a function template specialization names a function.

A template-id is only valid if.

• there are at most as many arguments as there are parameters or a parameter is a template parameter pack,
• there is an argument for each non-deducible non-pack parameter that does not have a default template-argument,
• each template-argument matches the corresponding template-parameter,
• substitution of each template argument into the following template parameters (if any) succeeds, and

An invalid simple-template-id is a compile-time error, unless it names a function template specialization (in which case SFINAE may apply).

template<class T, T::type n = 0>
class X;
 
struct S
{
    using type = int;
};
 
using T1 = X<S, int, int>; // error: too many arguments
using T2 = X<>;            // error: no default argument for first template parameter
using T3 = X<1>;           // error: value 1 does not match type-parameter
using T4 = X<int>;         // error: substitution failure for second template parameter
using T5 = X<S>;           // OK

template<typename T>
concept C1 = sizeof(T) != sizeof(int);
 
template<C1 T>
struct S1 {};
 
template<C1 T>
using Ptr = T*;
 
S1<int>* p;                      // error: constraints not satisfied
Ptr<int> p;                      // error: constraints not satisfied
 
template<typename T>
struct S2 { Ptr<int> x; };       // error, no diagnostic required
 
template<typename T>
struct S3 { Ptr<T> x; };         // OK, satisfaction is not required
 
S3<int> x;                       // error: constraints not satisfied
 
template<template<C1 T> class X>
struct S4
{
    X<int> x;                    // error, no diagnostic required
};
 
template<typename T>
concept C2 = sizeof(T) == 1;
 
template<C2 T> struct S {};
 
template struct S<char[2]>;      // error: constraints not satisfied
template<> struct S<char[2]> {}; // error: constraints not satisfied

Two template-id s are same if.

• their template-name s refer to the same template, and
• their corresponding type template arguments are the same type, and
• their corresponding non-type template arguments are template-argument-equivalent after conversion to the type of the template parameter, and
• their corresponding template template arguments refer to the same template.

Two template-id s that are the same refer to the same variable, (since C++14) class, or function.

Templated entity

A templated entity (or, in some sources, "temploid") is any entity that is defined (or, for a lambda expression, created) (since C++11) within a template definition. All of the following are templated entities:

• a class/function/variable (since C++14) template

• a member of a templated entity (such as a non-template member function of a class template)
• an enumerator of an enumeration that is a templated entity
• any entity defined or created within a templated entity: a local class, a local variable, a friend function, etc

For example, in.

template<typename T>
struct A
{
    void f() {}
};

the function A::f is not a function template, but is still considered to be templated.

A templated function is a function template or a function that is templated.

A templated class is a class template or a class that is templated.

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

See also