17 Templates [temp]

17.7 Template instantiation and specialization [temp.spec]

17.7.2 Explicit instantiation [temp.explicit]

1
#
A class, function, variable, or member template specialization can be explicitly instantiated from its template.
A member function, member class or static data member of a class template can be explicitly instantiated from the member definition associated with its class template.
An explicit instantiation of a function template or member function of a class template shall not use the inline or constexpr specifiers.
2
#
The syntax for explicit instantiation is:
explicit-instantiation:
	extern template declaration
There are two forms of explicit instantiation: an explicit instantiation definition and an explicit instantiation declaration.
An explicit instantiation declaration begins with the extern keyword.
3
#
If the explicit instantiation is for a class or member class, the elaborated-type-specifier in the declaration shall include a simple-template-id.
If the explicit instantiation is for a function or member function, the unqualified-id in the declaration shall be either a template-id or, where all template arguments can be deduced, a template-name or operator-function-id.
[ Note
:
The declaration may declare a qualified-id, in which case the unqualified-id of the qualified-id must be a template-id.
— end note
 ]
If the explicit instantiation is for a member function, a member class or a static data member of a class template specialization, the name of the class template specialization in the qualified-id for the member name shall be a simple-template-id.
If the explicit instantiation is for a variable, the unqualified-id in the declaration shall be a template-id.
An explicit instantiation shall appear in an enclosing namespace of its template.
If the name declared in the explicit instantiation is an unqualified name, the explicit instantiation shall appear in the namespace where its template is declared or, if that namespace is inline ([namespace.def]), any namespace from its enclosing namespace set.
[ Note
:
Regarding qualified names in declarators, see [dcl.meaning].
— end note
 ]
[ Example
: 
template<class T> class Array { void mf(); };
template class Array<char>;
template void Array<int>::mf();

template<class T> void sort(Array<T>& v) { /* ... */ }
template void sort(Array<char>&);       // argument is deduced here

namespace N {
  template<class T> void f(T&) { }
}
template void N::f<int>(int&);
— end example
 ]
4
#
A declaration of a function template, a variable template, a member function or static data member of a class template, or a member function template of a class or class template shall precede an explicit instantiation of that entity.
A definition of a class template, a member class of a class template, or a member class template of a class or class template shall precede an explicit instantiation of that entity unless the explicit instantiation is preceded by an explicit specialization of the entity with the same template arguments.
If the declaration of the explicit instantiation names an implicitly-declared special member function (Clause [special]), the program is ill-formed.
5
#
For a given set of template arguments, if an explicit instantiation of a template appears after a declaration of an explicit specialization for that template, the explicit instantiation has no effect.
Otherwise, for an explicit instantiation definition the definition of a function template, a variable template, a member function template, or a member function or static data member of a class template shall be present in every translation unit in which it is explicitly instantiated.
6
#
An explicit instantiation of a class, function template, or variable template specialization is placed in the namespace in which the template is defined.
An explicit instantiation for a member of a class template is placed in the namespace where the enclosing class template is defined.
An explicit instantiation for a member template is placed in the namespace where the enclosing class or class template is defined.
[ Example
: 
namespace N {
  template<class T> class Y { void mf() { } };
}

template class Y<int>;          // error: class template Y not visible in the global namespace

using N::Y;
template class Y<int>;          // error: explicit instantiation outside of the namespace of the template

template class N::Y<char*>;             // OK: explicit instantiation in namespace N
template void N::Y<double>::mf();       // OK: explicit instantiation in namespace N
— end example
 ]
7
#
A trailing template-argument can be left unspecified in an explicit instantiation of a function template specialization or of a member function template specialization provided it can be deduced from the type of a function parameter ([temp.deduct]).
[ Example
: 
template<class T> class Array { /* ... */ };
template<class T> void sort(Array<T>& v) { /* ... */ }

// instantiate sort(Array<int>&) – template-argument deduced
template void sort<>(Array<int>&);
— end example
 ]
8
#
An explicit instantiation that names a class template specialization is also an explicit instantiation of the same kind (declaration or definition) of each of its members (not including members inherited from base classes and members that are templates) that has not been previously explicitly specialized in the translation unit containing the explicit instantiation, except as described below.
[ Note
:
In addition, it will typically be an explicit instantiation of certain implementation-dependent data about the class.
— end note
 ]
9
#
An explicit instantiation definition that names a class template specialization explicitly instantiates the class template specialization and is an explicit instantiation definition of only those members that have been defined at the point of instantiation.
10
#
Except for inline functions and variables, declarations with types deduced from their initializer or return value ([dcl.spec.auto]), const variables of literal types, variables of reference types, and class template specializations, explicit instantiation declarations have the effect of suppressing the implicit instantiation of the entity to which they refer.
[ Note
:
The intent is that an inline function that is the subject of an explicit instantiation declaration will still be implicitly instantiated when odr-used ([basic.def.odr]) so that the body can be considered for inlining, but that no out-of-line copy of the inline function would be generated in the translation unit.
— end note
 ]
11
#
If an entity is the subject of both an explicit instantiation declaration and an explicit instantiation definition in the same translation unit, the definition shall follow the declaration.
An entity that is the subject of an explicit instantiation declaration and that is also used in a way that would otherwise cause an implicit instantiation ([temp.inst]) in the translation unit shall be the subject of an explicit instantiation definition somewhere in the program; otherwise the program is ill-formed, no diagnostic required.
[ Note
:
This rule does apply to inline functions even though an explicit instantiation declaration of such an entity has no other normative effect.
This is needed to ensure that if the address of an inline function is taken in a translation unit in which the implementation chose to suppress the out-of-line body, another translation unit will supply the body.
— end note
 ]
An explicit instantiation declaration shall not name a specialization of a template with internal linkage.
12
#
The usual access checking rules do not apply to names used to specify explicit instantiations.
[ Note
:
In particular, the template arguments and names used in the function declarator (including parameter types, return types and exception specifications) may be private types or objects which would normally not be accessible and the template may be a member template or member function which would not normally be accessible.
— end note
 ]
13
#
An explicit instantiation does not constitute a use of a default argument, so default argument instantiation is not done.
[ Example
: 
char* p = 0;
template<class T> T g(T x = &p) { return x; }
template int g<int>(int);       // OK even though &p isn't an int.
— end example
 ]