cpp/language/function template

A function template defines a family of functions.

Explanation
{{rrev|since=c++20|

Abbreviated function template
When placeholder types (either or Concept auto) appear in the parameter list of a function declaration or of a function template declaration, the declaration declares a function template, and one invented template parameter for each placeholder is appended to the template parameter list:

Abbreviated function templates can be specialized like all function templates.

}}

Function template instantiation
A function template by itself is not a type, or a function, or any other entity. No code is generated from a source file that contains only template definitions. In order for any code to appear, a template must be instantiated: the template arguments must be determined so that the compiler can generate an actual function (or class, from a class template).

Explicit instantiation
@1@ Explicit instantiation definition (without if every non-default template parameter is explicitly specified) @2@ Explicit instantiation definition with template argument deduction for all parameters @3@ Explicit instantiation declaration (without template argument deduction if every non-default template parameter is explicitly specified) @4@ Explicit instantiation declaration with template argument deduction for all parameters

An explicit instantiation definition forces instantiation of the function or member function they refer to. It may appear in the program anywhere after the template definition, and for a given argument-list, is only allowed to appear once in the program, no diagnostic required.

A trailing template-argument can be left unspecified in an explicit instantiation of a function template specialization or of a member function template specialization if it can be from the function parameter:

Explicit instantiation of a function template or of a member function of a class template cannot use or. If the declaration of the explicit instantiation names an implicitly-declared special member function, the program is ill-formed.

Explicit instantiation of a cannot use a template parameter list (syntax ), which is also never necessary because they can be deduced (syntax ).

Explicit instantiation declarations do not suppress the implicit instantiation of functions, -declarations, references, and class template specializations. (thus, when the inline function that is a subject of explicit instantiation declaration is ODR-used, it is implicitly instantiated for inlining, but its out-of-line copy is not generated in this translation unit)

Explicit instantiation definition of a function template with is not a use of the arguments, and does not attempt to initialize them:

Implicit instantiation
When code refers to a function in context that requires, and this particular function has not been explicitly instantiated, implicit instantiation occurs. The list of template arguments does not have to be supplied if it can be from context.

Note: omitting entirely allows  to examine both template and non-template overloads.

Template argument deduction
In order to instantiate a function template, every template argument must be known, but not every template argument has to be specified. When possible, the compiler will deduce the missing template arguments from the function arguments. This occurs when a function call is attempted and when an address of a function template is taken.

This mechanism makes it possible to use template operators, since there is no syntax to specify template arguments for an operator other than by re-writing it as a function call expression.

Template argument deduction takes place after the function template (which may involve ) and before.

See for details.

Explicit template arguments
Template arguments of a function template may be obtained from
 * template argument deduction
 * default template arguments
 * specified explicitly, which can be done in the following contexts:
 * in a function call expression
 * when an address of a function is taken
 * when a reference to function is initialized
 * when a pointer to member function is formed
 * in an explicit specialization
 * in an explicit instantiation
 * in a friend declaration

There is no way to explicitly specify template arguments to, , and constructors, because they are called without the use of the function name.

The specified template arguments must match the template parameters in kind (i.e., type for type, non-type for non-type, and template for template). There cannot be more arguments than there are parameters.

The specified non-type arguments must either match the types of the corresponding non-type template parameters, or be.

The function parameters that do not participate in template argument deduction (e.g. if the corresponding template arguments are explicitly specified) are subject to implicit conversions to the type of the corresponding function parameter (as in the usual ).

Template argument substitution
When all template arguments have been specified, deduced or obtained from default template arguments, every use of a template parameter in the function parameter list is replaced with the corresponding template arguments.

Substitution failure (that is, failure to replace template parameters with the deduced or provided template arguments) of a function template removes the function template from the. This allows a number of ways to manipulate overload sets using template metaprogramming: see for details.

After substitution, all function parameters of array and function type are adjusted to pointers and all top-level cv-qualifiers are dropped from function parameters (as in a regular ).

The removal of the top-level cv-qualifiers does not affect the type of the parameter as it appears within the function:

Function template overloading
Function templates and non-template functions may be overloaded.

A non-template function is always distinct from a template specialization with the same type. Specializations of different function templates are always distinct from each other even if they have the same type. Two function templates with the same return type and the same parameter list are distinct and can be distinguished with explicit template argument list.

When an expression that uses type or non-type template parameters appears in the function parameter list or in the return type, that expression remains a part of the function template signature for the purpose of overloading:

Two expressions involving template parameters are called equivalent if two function definitions that contain these expressions would be the same under, that is, the two expressions contain the same sequence of tokens whose names are resolved to same entities via name lookup, except template parameters may be differently named.

When determining if two are equivalent, only the dependent names involved are considered, not the results of name lookup. If multiple declarations of the same template differ in the result of name lookup, the first such declaration is used:

Two function templates are considered equivalent if
 * they are declared in the same scope
 * they have the same name
 * they have equivalent template parameter lists, meaning the lists are of the same length, and for each corresponding parameter pair, all of the following is true:
 * the two parameters are of the same kind (both types, both non-types, or both templates)


 * if non-type, their types are equivalent,
 * if template, their template parameters are equivalent,


 * the expressions involving template parameters in their return types and parameter lists are equivalent

Two expressions involving template parameters are called functionally equivalent if they are not equivalent, but for any given set of template arguments, the evaluation of the two expressions results in the same value.

Two function templates are considered functionally equivalent if they are equivalent, except that one or more expressions that involve template parameters in their return types and parameter lists are functionally equivalent.

If a program contains declarations of function templates that are functionally equivalent but not equivalent, the program is ill-formed; no diagnostic is required.

When the same function template specialization matches more than one overloaded function template (this often results from ), partial ordering of overloaded function templates is performed to select the best match.

Specifically, partial ordering takes place in the following situations: @1@ for a call to a function template specialization:

@2@ when the is taken:

@3@ when a placement operator delete that is a function template specialization is selected to match a placement operator new:

@4@ when a, an , or an refers to a function template specialization:

Informally "A is more specialized than B" means "A accepts fewer types than B".

Formally, to determine which of any two function templates is more specialized, the partial ordering process first transforms one of the two templates as follows:
 * For each type, non-type, and template parameter, a unique fictitious type, value, or template is generated and substituted into function type of the template
 * If only one of the two function templates being compared is a member function, and that function template is a non-static member of some class, a new first parameter is inserted into its parameter list. Given cv as the cv-qualifiers of the function template, the new parameter type is cv . This helps the ordering of operators, which are looked up both as member and as non-member functions:

After one of the two templates was transformed as described above, is executed using the transformed template as the argument template and the original template type of the other template as the parameter template. The process is then repeated using the second template (after transformations) as the argument and the first template in its original form as the parameter.

The types used to determine the order depend on the context:
 * in the context of a function call, the types are those function parameter types for which the function call has arguments (default function arguments, and ellipsis parameters are not considered -- see examples below)
 * in the context of a call to a user-defined conversion function, the return types of the conversion function templates are used
 * in other contexts, the function template type is used

Each type from the list above from the parameter template is deduced. Before deduction begins, each parameter of the parameter template and the corresponding argument  of the argument template is adjusted as follows:


 * If both and  are reference types before, determine which is more cv-qualified (in all other cases, cv-qualifications are ignored for partial ordering purposes)
 * If is a reference type, it is replaced by the type referred to
 * If is a reference type, it is replaced by the type referred to
 * If is cv-qualified,  is replaced with cv-unqualified version of itself
 * If is cv-qualified,  is replaced with cv-unqualified version of itself

After these adjustments, deduction of from  is done following.

If the argument of the transformed template-1 can be used to deduce the corresponding parameter  of template-2, but not vice versa, then this  is more specialized than  with regards to the type(s) that are deduced by this  pair.

If deduction succeeds in both directions, and the original and  were reference types, then additional tests are made:
 * If was lvalue reference and  was rvalue reference,  is considered to be more specialized than
 * If was more cv-qualified than,  is considered to be more specialized than

In all other cases, neither template is more specialized than the other with regards to the type(s) deduced by this pair.

After considering every and  in both directions, if, for each type that was considered,
 * template-1 is at least as specialized as template-2 for all types
 * template-1 is more specialized than template-2 for some types
 * template-2 is not more specialized than template-1 for any types OR is not at least as specialized for any types

Then template-1 is more specialized than template-2. If the conditions above are true after switching template order, then template-2 is more specialized than template-1. Otherwise, neither template is more specialized than the other.

If, after considering all pairs of overloaded templates, there is one that is unambiguously more specialized than all others, that template's specialization is selected, otherwise compilation fails.

In the following examples, the fictitious arguments will be called U1, U2:

Since a call context considers only parameters for which there are explicit call arguments, those ellipsis parameters, and parameters with default arguments, for which there is no explicit call argument, are ignored:

During template argument deduction within the partial ordering process, template parameters don't require to be matched with arguments, if the argument is not used in any of the types considered for partial ordering

To compile a call to a function template, the compiler has to decide between non-template overloads, template overloads, and the specializations of the template overloads.

Function overloads vs function specializations
Note that only non-template and primary template overloads participate in overload resolution. The specializations are not overloads and are not considered. Only after the overload resolution selects the best-matching primary function template, its specializations are examined to see if one is a better match.

It is important to remember this rule while ordering the header files of a translation unit. For more examples of the interplay between function overloads and function specializations, expand below:

Consider first some scenarios where the argument-dependent lookup is not employed. For that, we use the call. As described in, wrapping the function name in parentheses is suppressing the argument-dependent lookup.


 * Multiple overloads of declared before the point-of-reference (POR) in.


 * A better matching template overload is declared after POR.


 * A better matching explicit template specialization is declared after POR.


 * A better matching template overload is declared after POR. The best matching explicit template specialization is declared after the better matching overload.

Let's consider now those cases employing argument-dependent lookup (i.e., we use the more common call format ).


 * A better matching template overload is declared after POR.


 * A better matching template overload is declared after POR. The best matching explicit template specialization is declared before the better matching overload.


 * A better matching template overload is declared after POR. The best matching explicit template specialization is declared last.

Whenever the arguments are some C++ basic types, there are no ADL-associated namespaces. Hence, those scenarios are identical with the non-ADL examples above.

For detailed rules on overload resolution, see.