Chapter 20: Function Templates

Don't hesitate to send in feedback: send an e-mail if you like the C++ Annotations; if you think that important material was omitted; if you find errors or typos in the text or the code examples; or if you just feel like e-mailing. Send your e-mail to Frank B. Brokken.
Please state the document version you're referring to, as found in the title (in this document: 8.3.1) and please state chapter and paragraph name or number you're referring to.
All received mail is processed conscientiously, and received suggestions for improvements will usually have been processed by the time a new version of the Annotations is released. Except for the incidental case I will normally not acknowledge the receipt of suggestions for improvements. Please don't interpret this as me not appreciating your efforts.

C++ supports syntactic constructs allowing programmers to define and use completely general (or abstract) functions or classes, based on generic types and/or (possibly inferred) constant values. In the chapters on abstract containers (chapter 12) and the STL (chapter 18) we've already used these constructs, commonly known as the template mechanism.

The template mechanism allows us to specify classes and algorithms, fairly independently of the actual types for which the templates will eventually be used. Whenever the template is used, the compiler generates code that is tailored to the particular data type(s) used with the template. This code is generated at compile-time from the template's definition. The piece of generated code is called an instantiation of the template.

In this chapter the syntactic peculiarities of templates are covered. The notions of template type parameter, template non-type parameter, and function template are introduced and several examples of templates are provided (both in this chapter and in chapter 23). Template classes are covered in chapter 21.

Templates offered standard by the language include the abstract containers (cf. chapter 12); the string (cf. chapter 5); streams (cf. chapter 6); and the generic algorithms (cf. chapter 19). So, templates play a central role in present-day C++, and should not be considered an esoteric feature of the language.

Templates should be approached somewhat similarly as generic algorithms: they're a way of life; a C++ software engineer should actively look for opportunities to use them. Initially, templates may appear to be rather complex and you might be tempted to turn your back on them. However, over time their strengths and benefits are more and more appreciated. Eventually you'll be able to recognize opportunities for using templates. That's the time where your efforts should no longer focus on constructing ordinary functions and classes (i.e., functions or classes that are not templates), but on constructing templates.

This chapter starts by introducing function templates. The emphasis is on the required syntax. This chapter lays the foundation upon which the other chapter about templates are built.

20.1: Defining function templates

A function template's definition is very similar to the definition of a normal function. A function template has a function head, a function body, a return type, possibly overloaded definitions, etc.. However, different from ordinary functions, function templates always use one or more formal types: types for which almost any exising (class or primitive) type could be used. Let's have a look at a simple example. The following function add expects two Type arguments and returns their sum:

    Type add(Type const &lvalue, Type const &rvalue)
    {
        return lvalue + rvalue;
    }

Note how closely the above function's definition follows its description: it gets two arguments, and returns its sum. Now consider what would happen if we would have defined this function for, e.g., int values. We would have written:

    int add(int const &lvalue, int const &rvalue)
    {
        return lvalue + rvalue;
    }

So far, so good. However, were we to add two doubles, we would have overloaded this function:

    double add(double const &lvalue, double const &rvalue)
    {
        return lvalue + rvalue;
    }

There is no end to the number of overloaded versions we might be forced to construct: an overloaded version for string, for size_t, for .... In general, we would need an overloaded version for every type supporting operator+ and a copy constructor. All these overloaded versions of basically the same function are required because of the strongly typed nature of C++. Because of this, a truly generic function cannot be constructed without resorting to the template mechanism.

Fortunately, we've already seen a large part of a template function. Our initial function add actually is an implementation of such a function although it isn't a full template definition yet. If we would give the first add function to the compiler, it would produce an error message like:

    error: `Type' was not declared in this scope
    error: parse error before `const'

And rightly so, as we failed to define Type. The error is prevented when we change add into a full template definition. To do this, we look at the function's implementation and decide that Type is actually a formal typename. Comparing it to the alternate implementations, it will be clear that we could have changed Type into int to get the first implementation, and into double to get the second.

The full template definition allows for this formal character of the Type typename. Using the keyword template, we prefix one line to our initial definition, obtaining the following function template definition:

    template <typename Type>
    Type add(Type const &lvalue, Type const &rvalue)
    {
        return lvalue + rvalue;
    }

In this definition we distinguish:

The keyword template, starting a template definition or declaration.
The angle bracket enclosed list following template. This is a list containing one or more comma-separated elements. This angle bracket enclosed list is called the template parameter list. Template parameter lists using multiple elements could look like this:
```
    typename Type1, typename Type2
```
Inside the template parameter list we find the formal type name Type. It is a formal type name, comparable to a formal parameter name in a function's definition. Up to now we've only encountered formal variable names with functions. The types of the parameters were always known by the time the function was defined. Templates escalate the notion of formal names one step further up the ladder. Templates allow type names to be formalized, rather than just the variable names themselves. The fact that Type is a formal type name is indicated by the keyword typename, prefixed to Type in the template parameter list. A formal type name like Type is also called a template type parameter. Template non-type parameters also exist, and are shortly introduced.
Other texts on C++ sometimes use the keyword class where we use typename. So, in other texts template definitions might start with a line like:
```
    template <class Type>
```
In the C++ Annotations the use of typename over class is preferred, reasoning that a template type parameter is, after all, a type name (some authors prefer class over typename; in the end it's a matter of taste).
The template keyword and the template parameter list is called the template header.
The function head: it is like a normal function head, albeit that the template's type parameters must be used in its parameter list. When the function is eventually called using actual arguments having actual types, these actual types are used by the compiler to infer which version (i.e., overload to fit the actual argument types) of the function template must be used. At the point where the function is called the compiler will create the function that is called, a process called instantiation. The function head may also use a formal type to specify its return value. This feature was actually used in the add template's definition.
The function parameters are specified as Type const & parameters. This has the usual meaning: the parameters are references to Type objects or values that will not be modified by the function.
The function body is like a normal function body. In the body the formal type names may be used to define or declare variables, which may then be used as any other local variable. But some restrictions apply. Looking at add's body, it is clear that operator+ is used, as well as a copy constructor, as the function returns a value. This allows us to formulate the following restrictions for the formal type Type as used by our add function template:
- Type should support operator+
- Type should support a copy constructor
Consequently, while Type could be a string, it could never be an ostream, as neither operator+ nor the copy constructor are available for streams.

Normal scope rules and identifier visibility rules apply to templates. Within the template definition's scope formal type names overrule identically named identifiers of broader scopes.

Look again at the add's parameters. By specifying Type const & rather than Type superfluous copying is prevented, at the same time allowing values of primitive types to be passed as arguments to the function. So, when add(3, 4) is called, int(4) will be assigned to Type const &rvalue. In general, function parameters should be defined as Type const & to prevent unnecessary copying. The compiler is smart enough to handle `references to references' in this case, which is something the language normally does not support. For example, consider the following main function (here and in the following simple examples it is assumed that the template and the required headers and namespace declarations have been provided):

    int main()
    {
        size_t const &var = size_t(4);
        cout << add(var, var) << '\n';
    }

Here var is a reference to a constant size_t. It is passed as argument to add, thereby initializing lvalue and rvalue as

Type
const &

to size_t const & values. The compiler interpreting Type as size_t. Alternatively, the parameters might have been specified using Type &, rather than Type const &. The disadvantage of this (non-const) specification being that temporary values cannot be passed to the function anymore. The following therefore fails to compile:

    int main()
    {
        cout << add(string("a"), string("b")) << '\n';
    }

Here, a string const & cannot be used to initialize a string &. If add would define Type && parameters the above program would compile just fine. In addition the following will compile as the compiler decides that Type apparently is a string const:

    int main()
    {
        string const &s = string("a");
        cout << add(s, s) << '\n';
    }

What can we deduce from these examples?

In general, function parameters should be specified as Type const & parameters to prevent unnecessary copying.

The template mechanism is fairly flexible. It will interpret formal types as plain types, const types, pointer types, etc., depending on the actually provided types. The rule of thumb is that the formal type is used as a generic mask for the actual type, with the formal type name covering whatever part of the actual type must be covered. Some examples, assuming the parameter is defined as Type const &:

argument type	Type ==
`size_t const`	`size_t`
`size_t`	`size_t`
`size_t *`	`size_t *`
`size_t const *`	`size_t const *`

As a second example of a function template, consider the following function template:

    template <typename Type, size_t Size>
    Type sum(Type const (&array)[Size])
    {
        Type tp = Type();

        for (size_t idx = 0; idx < Size; idx++)
            tp += array[idx];

        return tp;
    }

This template definition introduces the following new concepts and features:

The template parameter list. This template parameter list has two elements. The first element is a well-known template type parameter, but the second element has a very specific type: a size_t. Template parameters of specific (i.e., non-formal) types used in template parameter lists are called template non-type parameters. A template non-type parameter defines the type of a constant expression, which must be known by the time the template is instantiated and which is specified in terms of existing types, such as a size_t.
Looking at the function's head, we see one parameter:
```
    Type const (&array)[Size]
```
This parameter defines array as a reference to an array having Size elements of type Type that may not be modified.
In the parameter definition, both Type and Size are used. Type is of course the template's type parameter Type, but Size is also a template parameter. It is a size_t, whose value must be inferable by the compiler when it compiles an actual call of the sum function template. Consequently, Size must be a const value. Such a constant expression is called a template non-type parameter, and its type is named in the template's parameter list.
When the function template is called, the compiler must be able to infer not only Type's concrete value, but also Size's value. Since the function sum only has one parameter, the compiler is only able to infer Size's value from the function's actual argument. It can do so if the provided argument is an array (of known and fixed size) rather than a pointer to Type elements. So, in the following main function the first statement will compile correctly but the second statement will not:
```
    int main()
    {
        int values[5];
        int *ip = values;

        cout << sum(values) << '\n';    // compiles OK
        cout << sum(ip) << '\n';        // won't compile
    }
```
Inside the function's body the statement Type tp = Type() is used to initialize tp to a default value. Note here that no fixed value (like 0) is used. Any type's default value may be obtained using its default constructor rather than using a fixed numeric value. Of course, not every class accepts a numeric value as an argument to one of its constructors. But all types, even the primitive types, support default constructors (actually, some classes do not implement a default constructor, or make it inaccessible; but most do). The default constructor of primitive types will initialize their variables to 0 (or false). Furthermore, the statement Type tp = Type() is a true initialization: tp is initialized by Type's default constructor, rather than using Type's copy constructor to assign Type's copy to tp.
It's interesting to note here (although not directly related to the current topic) that the syntactic construction Type tp(Type()) cannot be used, even though it also looks like a proper initialization. Usually an initializing argument can be provided to an object's definition, like string s("hello"). Why, then, is Type tp = Type() accepted, whereas Type tp(Type()) isn't? When Type tp(Type()) is used it won't result in an error message. So we don't immediately detect that it's not a Type object's default initialization. Instead, the compiler will start generating error messages once tp is used. This is caused by the fact that in C++ (and in C alike) the compiler will do its best to recognize a function or function pointer whenever possible: the function prevalence rule. According to this rule Type() is (because of the pair of parentheses) interpreted as a pointer to a function expecting no arguments; returning a Type. It will do so unless the compiler clearly is unable to do so. In the initialization Type tp = Type() it can't see a pointer to a function as a Type object cannot be given the value of a function pointer (remember: Type() is interpreted as Type (*)() whenever possible). But in Type tp(Type()) it can use the pointer interpretation: tp is now declared as a function expecting a pointer to a function returning a Type, with t itself also returning a Type. E.g., t could have been defined as:
```
    Type t(Type (*tp)())
    {
        return (*tp)();
    }
```
Comparable to the first function template, sum also assumes the existence of certain public members in Type's class. This time operator+= and Type's copy constructor.

Like class definitions, template definitions should not contain using directives or declarations: the template might be used in a situation where such a directive overrides the programmer's intentions: ambiguities or other conflicts may result from the template's author and the programmer using different using directives (E.g, a cout variable defined in the std namespace and in the programmer's own namespace). Instead, within template definitions only fully qualified names, including all required namespace specifications should be used.

20.1.1: Late-specified return type (C++0x)

Traditional C++ requires function templates to specify their return type or to specify the return type as a template type parameter. Consider the following function:

    int add(int lhs, int rhs)
    {
        return lhs + rhs;
    }

The above function may be converted to a template function:

    template <typename Lhs, typename Rhs>
    Lhs add(Lhs lhs, Rhs rhs)
    {
        return lhs + rhs;
    }

Unfortunately, when the template function is called as

    add(3, 3.4)

the intended return type is probably a double rather than an int. This can be solved by adding an additional template type parameter specifying the return type but then that type must explicitly be specified:

    add<double>(3, 3.4);

Using decltype (cf. section 3.3.6) to define the return type won't work as lhs and rhs aren't known to the compiler by the time decltype is used. Thus the next attempt to get rid of the additional template type parameter will fail to compile:

    template <typename Lhs, typename Rhs>
    decltype(lhs + rhs) add(Lhs lhs, Rhs rhs)
    {
        return lhs + rhs;
    }

The decltype-based definition of a function's return type may become fairly complex. To reduce the complexities the C++0x standard provides the late-specified return type syntax that does allow the use of decltype to define a function's return type. It is primarily used with template functions but it may also be used for non-template functions:

    template <typename Lhs, typename Rhs>
    auto add(Lhs lhs, Rhs rhs) -> decltype(lhs + rhs)
    {
        return lhs + rhs;
    }

When this function is used in a statement like cout << add(3, 3.4) the resulting value will be 6.4, which is most likely the intended result, rather than 6. As an example how a late-specified return type may reduce the complexity of a function's return type definition consider the following:

    template <class T, class U>
    decltype((*(T*)0)+(*(U*)0)) add(T t, U u);

Using a late-specified return type we get the equivalent:

    template <class T, class U>
    auto add(T t, U u) -> decltype(t+u);

which most people think is easier to read.

The expression specified with decltype does not necessarily use the parameters lhs and rhs themselves. In the next function definition lhs.length is used instead of lhs itself:

    template <typename Class, typename Rhs>
    auto  add(Class lhs, Rhs rhs) -> decltype(lhs.length() + rhs)
    {
        return lhs.length() + rhs;
    }

Any variable visible at the time decltype is compiled can be used in the decltype expression. However, it is currently not possible to handle member selection through pointers to members. The following code aims at specifying the address of a member function as add's first argument and then use its return value type to determine the template function's return type:

    std::string global;

    template <typename MEMBER, typename RHS>
    auto  add(MEMBER mem, RHS rhs) -> decltype((global.*mem)() + rhs)
    {
        return (global.*mem)() + rhs;
    }

Although the above function compiles fine, it cannot currently be used as it results in a compiler error message like unimplemented: mangling dotstar_expr (generated for a statement like cout << add(&string::length, 3.4)).

20.2: Passing arguments by reference (reference wrappers) (C++0x)

Before using the reference wrappers discussed in this section the <functional> header file must have been included.

Situations exist where the compiler is unable to infer that a reference rather than a value is passed to a template function. In the following example the template function outer receives int x as its argument and the compiler will dutifully infer that Type is int:

    template <typename Type>
    void outer(Type t)
    {
        t.x();
    }
    void useInt()
    {
        int arg;
        outer(arg);
    }

Compilation will of course fail and the compiler nicely reports the inferred type, e.g.:

    In function 'void outer(Type) [with Type = int]': ...

Unfortunately the same error is generated when using call in the next example. The function call is a template expecting a function that takes an argument which is then itself modified, and a value to pass on to that function. Such a function is, e.g., sqrtArg expecting a reference to a double, which is modified by calling std::sqrt.

    void sqrtArg(double &arg)
    {
        arg = sqrt(arg);
    }
    template<typename Fun, typename Arg>
    void call(Fun fun, Arg arg)
    {
        fun(arg);
        cout << "In call: arg = " << arg << '\n';
    }

Assuming double value = 3 then call(sqrtArg, value) will not modify value as the compiler infers Arg to be double and hence passes value by value.

To have value itself changed the compiler must be informed that value must be passed by reference. Note that it might not be acceptable to define call's template argument as Arg & as not changing the actual argument might be appropriate in some situations.

The C++0x standard offers the ref(arg) and cref(arg) reference wrappers that take an argument and return it as a reference-typed argument. To actually change value it can be passed to call using ref(value) as shown in the following main function:

    int main()
    {
        double value = 3;
        call(sqrtArg, value);
        cout << "Passed value, returns: " << value << '\n';

        call(sqrtArg, ref(value));
        cout << "Passed ref(value), returns: " << value << '\n';
    }
    /*
        Displays:
            In call: arg = 1.73205
            Passed value, returns: 3
            In call: arg = 1.73205
            Passed ref(value), returns: 1.73205
    */

20.3: Template parameter deduction

In this section we'll concentrate on the process by which the compiler deduces the actual types of the template type parameters. These types are deduced when a template function is called using a process called template parameter deduction. As we've already seen, the compiler is able to substitute a wide range of actual types for a single formal template type parameter. Even so, not every thinkable conversion is possible. In particular when a function has multiple parameters of the same template type parameter, the compiler is very restrictive when determining what argument types will actually be accepted.

When the compiler deduces the actual types for template type parameters it will only consider the types of the arguments that are actually used. Neither local variables nor the function's return value is considered in this process. This is understandable. When a function is called the compiler is only certain about the types of the function template's arguments. At the point of the call it will definitely not see the types of the function's local variables. Also, the function's return value might not actually be used or may be assigned to a variable of a subrange (or super-range) type of a deduced template type parameter. So, in the following example, the compiler won't ever be able to call fun(), as it won't be able to deduce the actual type for the Type template type parameter.

    template <typename Type>
    Type fun()              // can never be called as `fun()'
    {
        return Type();
    }

Although the compiler won't be able to handle a call to `fun()', it is possible to call fun() using an explicit type specification. E.g., fun<int>() calls fun, instantiated for int. This is of course not the same as compiler argument deduction.

In general, when a function has multiple parameters of identical template type parameters, the actual types must be exactly the same. So, whereas

    void binarg(double x, double y);

may be called using an int and a double, with the int argument silently being converted to a double, a similar function template cannot be called using an int and double argument: the compiler won't by itself promote int to double deciding that Type should be double:

    template <typename Type>
    void binarg(Type const &p1, Type const &p2)
    {}

    int main()
    {
        binarg(4, 4.5); // ?? won't compile: different actual types
    }

What, then, are the transformations the compiler will apply when deducing the actual types of template type parameters? It will perform only three types of parameter type transformations and a fourth one to function template non-type parameters. If it cannot deduce the actual types using these transformations, the template function will not be considered. The transformations performed by the compiler are:

lvalue transformations, creating an rvalue from an lvalue;
qualification transformations, inserting a const modifier to a non-constant argument type;
transformation to a base class instantiated from a class template, using a template base class when an argument of a template derived class type was provided in the call.
Standard transformations for function template non-type parameters. This isn't a template type parameter transformation, but it refers to any remaining template non-type parameter of function templates. For these function parameters the compiler will perform any standard conversion it has available (e.g., int to size_t, int to double, etc.).

The purpose of the various template parameter type deduction transformations is not to match function arguments to function parameters, but rather, having matched arguments to parameters, to determine the actual types of the various template type parameters.

20.3.1: Lvalue transformations

There are three types of lvalue transformations:

lvalue-to-rvalue transformations.
An lvalue-to-rvalue transformation is applied when an rvalue is required, but an lvalue is provided. This happens when a variable is used as argument to a function specifying a value parameter. For example,
```
    template<typename Type>
    Type negate(Type value)
    {
        return -value;
    }
    int main()
    {
        int x = 5;
        x = negate(x);  // lvalue (x) to rvalue (copies x)
    }
```
array-to-pointer transformations.
An array-to-pointer transformation is applied when the name of an array is assigned to a pointer variable. This is frequently used with functions defining pointer parameters. Such functions frequently receive arrays as their arguments. The array's address is then assigned to the pointer-parameter and its type is used to deduce the corresponding template parameter's type. For example:
```
    template<typename Type>
    Type sum(Type *tp, size_t n)
    {
        return accumulate(tp, tp + n, Type());
    }
    int main()
    {
        int x[10];
        sum(x, 10);
    }
```
In this example, the location of the array x is passed to sum, expecting a pointer to some type. Using the array-to-pointer transformation, x's address is considered a pointer value which is assigned to tp, deducing that Type is int in the process.
function-to-pointer transformations.
This transformation is most frequently used with function templates defining a parameter which is a pointer to a function. When calling such a function the name of a function may be specified as its argument. The address of the function is then assigned to the pointer-parameter, deducing the template type parameter in the process. This is called a function-to-pointer transformation. For example:
```
    #include <cmath>

    template<typename Type>
    void call(Type (*fp)(Type), Type const &value)
    {
        (*fp)(value);
    }
    int main()
    {
        call(&sqrt, 2.0);
    }
```
In this example, the address of the sqrt function is passed to call, expecting a pointer to a function returning a Type and expecting a Type for its argument. Using the function-to-pointer transformation, sqrt's address is assigned to fp, deducing that Type is double in the process. The argument 2.0 could not have been specified as 2 as there is no int sqrt(int) prototype. Furthermore, the function's first parameter specifies Type (*fp)(Type), rather than Type (*fp)(Type const &) as might have been expected from our previous discussion about how to specify the types of function template's parameters, preferring references over values. However, fp's argument Type is not a function template parameter, but a parameter of the function fp points to. Since sqrt has prototype double sqrt(double), rather than double sqrt(double const &), call's parameter fp must be specified as Type (*fp)(Type). It's that strict.

20.3.2: Qualification transformations

A qualification transformation adds const or volatile qualifications to pointers. This transformation is applied when the function template's type parameter explicitly specifies const (or volatile) but the function's argument isn't a const or volatile entity. In that case const or volatile is provided by the compiler. Subsequently the compiler deduces the template's type parameter. For example:

    template<typename Type>
    Type negate(Type const &value)
    {
        return -value;
    }
    int main()
    {
        int x = 5;
        x = negate(x);
    }

Here we see the function template's Type const &value parameter: a reference to a const Type. However, the argument isn't a const int, but an int that can be modified. Applying a qualification transformation, the compiler adds const to x's type, and so it matches

int const
x

. This is then matched against Type const &value allowing the compiler to deduce that Type must be int.

20.3.3: Transformation to a base class

Although the construction of class templates is the topic of chapter 21 class templates have already extensively been used earlier. For example, abstract containers (cf. chapter 12) are defined as class templates. Class templates can, like ordinary classes, participate in the construction of class hierarchies.

In section 21.10 it is shown how a class template can be derived from another class template.

As class template derivation remains to be covered, the following discussion is necessarily somewhat premature. The reader may of course skip briefly to section 21.10 returning back to this section thereafter.

In this section it should be assumed, for the sake of argument, that a class template Vector has somehow been derived from a std::vector. Furthermore, assume that the following function template has been constructed to sort a vector using some function object obj:

    template <typename Type, typename Object>
    void sortVector(std::vector<Type> vect, Object const &obj)
    {
        sort(vect.begin(), vect.end(), obj);
    }

To sort std::vector<string> objects case-insensitively, a

class
Caseless

could be constructed as follows:

    class CaseLess
    {
        public:
            bool operator()(std::string const &before,
                            std::string const &after) const
            {
                return strcasecmp(before.c_str(), after.c_str()) < 0;
            }
    };

Now various vectors may be sorted using sortVector():

    int main()
    {
        std::vector<string> vs;
        std::vector<int> vi;

        sortVector(vs, CaseLess());
        sortVector(vi, less<int>());
    }

Applying the transformation transformation to a base class instantiated from a class template, the function template sortVectors() may now also be used to sort Vector objects. For example:

    int main()
    {
        Vector<string> vs;      // `Vector' instead of `std::vector'
        Vector<int> vi;

        sortVector(vs, CaseLess());
        sortVector(vi, less<int>());
    }

In this example, Vectors were passed as argument to sortVector. Applying the transformation to a base class instantiated from a class template, the compiler considers Vector to be a std::vector enabling it to deduce the template's type parameter. A std::string for the Vector vs, an int for Vector vi.

20.3.4: The template parameter deduction algorithm

The compiler uses the following algorithm to deduce the actual types of its template type parameters:

In turn, the function template's parameters are identified using the arguments of the called function.
For each template parameter used in the function template's parameter list, the template type parameter is associated with the corresponding argument's type (e.g., Type is int if the argument is int x, and the function's parameter is Type &value).
While matching the argument types to the template type parameters, the three allowed transformations (see section 20.3) for template type parameters are applied where necessary.
If identical template type parameters are used with multiple function parameters, the deduced template types must exactly match. So, the next function template cannot be called with an int and a double argument:
```
    template <typename Type>
    Type add(Type const &lvalue, Type const &rvalue)
    {
        return lvalue + rvalue;
    }
```
When calling this function template, two identical types must be used (albeit that the three standard transformations are of course allowed). If the template deduction mechanism does not come up with identical actual types for identical template types, then the function template will not be instantiated.

20.3.5: Template type contractions

With function templates the combination of the types of template arguments and template parameters shows some interesting contractions. What happens, for example if a template type parameter is specified as an rvalue reference but an lvalue reference argument type is provided?

In such cases the compiler performs type contractions. Doubling identical reference types results in a simple contraction: the type is deduced to be a single reference type. Example: if the template parameter type is specified as a Type && and the actual parameter is an int && then Type is deduced to be an int, rather than an int &&.

This is fairly intuitive. But what happens if the actual type is int &? There is no such thing as an int & &&param and so the compiler contracts the double reference by removing the rvalue reference, keeping the lvalue reference. Here a simple rule is followed: Any reference to an lvalue reference results in an lvalue reference and vice versa: an lvalue to any reference also results in an lvalue:

if Type is Actual & then Type & is Actual & and Type == Actual;
if Type is Actual & then Type && still is Actual & and Type == Actual;
if Type is Actual && then Type & again is Actual & and Type == Actual;
if Type is Actual && then Type && is Actual && and Type == Actual;

Let's look at a concrete exampe where contraction occurs. Consider the following template function where a function parameter is defined as an rvalue references to some template type parameter:

    template <typename Type>
    void function(Type &&param)
    {
        callee(static_cast<Type &&>(param));
    }

In this situation, when function is called with an (lvalue) argument of type TP & the template type parameter Type is deduced to be

Tp
&

. Therefore, param is considered to be instantiated as Tp &param (as Tp & &&param) is contracted as Tp &param. But with an rvalue typed argument (Tp &&) it results in Tp &&param (again using contraction).

Likewise, when callee is called using the static_cast the same contraction occurs, so if Type &&param is interpreted as Tp &param the static cast also uses type Tp &param. If (Type &&param) is interpreted as Tp &&param the static cast also uses type Tp &&param.

This characteristics allows us to pass a function argument straight through to a nested function without changing its type: lvalues remain lvalues, rvalues remain rvalues. This characteristic is therefore also known as perfect forwarding which will be discussed in greated detail in section 21.5.2. Perfect forwarding prevents the template author from having to define multiply overloaded versions of a function template.

20.4: Declaring function templates

Up to now, we've only defined function templates. There are various consequences of including function template definitions in multiple source files, none of them serious, but worth knowing.

Like class interfaces, template definitions are usually included in header files. Every time a header file containing a template definition is read by the compiler it must process the full definition. It must do so even if it does not actually use the template. This will relatively slow-down the compilation. For example, compiling a template header file like algorithm on my old laptop takes about four times the amount of time it takes to compile a plain header file like cmath. The header file iostream is even harder to process, requiring almost 15 times the amount of time it takes to process cmath. Clearly, processing templates is serious business for the compiler. On the other hand this drawback shouldn't be taken too seriously. Compilers are continuously improving their template processing capacity and computers keep getting faster and faster. What was a nuisance a few years ago is hardly noticeable today.
Every time a function template is instantiated, its code appears in the resulting object module. However, if multiple instantiations of a template using the same actual types for its template parameter exist in multiple object files the one definition rule is lifted. The linker will weed out superfluous instantiations (i.e., identical definitions of instantiated templates). In the final program only one instantiation for a particular set of actual template type parameters will remain (see section 20.5 for an illustration). Therefore, the linker will have an additional task to perform (viz. weeding out multiple instantiations), which somewhat slows down the linking process.
Sometimes the definitions themselves are not, but references or pointers to the templates are required. Requiring the compiler to process the full template definitions in those cases will needlessly slow down the compilation process.
In the context of template meta programming (see chapter 22) it is sometimes not even required to provide a template implementation. Instead, only specializations (cf. section 20.8) are created which are based upon the mere declaration.

So in some contexts template definitions may not be required. Instead the software enginieer may opt to declare a template rather than to include the template's definition time and again in various source files.

When templates are declared, the compiler does not have to process the template's definitions again and again; and no instantiations will be created on the basis of template declarations alone. Any actually required instantiation must then be available elsewhere (of course, this holds true for declarations in general). Unlike the situation we encounter with ordinary functions, which are usually stored in libraries, it is currently not possible to store templates in libraries (although the compiler may construct precompiled header files). Consequently, using template declarations puts a burden on the shoulders of the software engineer, who has to make sure that the required instantiations exist. Below a simple way to accomplish that is introduced.

To create a function template declaration simply replace the function's body by a semicolon. Note that this is exactly identical to the way ordinary function declarations are constructed. So, the previously defined function template add can simply be declared as

    template <typename Type>
    Type add(Type const &lvalue, Type const &rvalue);

We've already encountered template declarations. The header file iosfwd may be included in sources not requiring instantiations of elements from the class ios and its derived classes. For example, to compile the declaration

    std::string getCsvLine(std::istream &in, char const *delim);

it is not necessary to include the string and istream header files. Rather, a single

    #include <iosfwd>

is sufficient. Processing iosfwd requires only a fraction of the time it takes to process the string and istream header files.

20.4.1: Instantiation declarations

If declaring function templates speeds up the compilation and the linking phases of a program, how can we make sure that the required instantiations of the function templates will be available when the program is eventually linked together?

For this a variant of a template declaration is available, a so-called explicit instantiation declaration. An explicit instantiation declaration consists of the following elements:

It starts with the keyword template, omitting the template parameter list.
Next the function template's return type and name are specified.
The function template's name is followed by a type specification list. A type specification list is an angle brackets enclosed list of type names. Each type specifies the actual type of the corresponding template type parameter in the template's parameter list.
Finally the function template's parameter list is specified, terminated by a semicolon.

Although this is a declaration, it is understood by the compiler as a request to instantiate that particular variant of the function template.

Using explicit instantiation declarations all instantiations of template functions required by a program can be collected in one file. This file, which should be a normal source file, should include the template definition header file and should subsequently specify the required explicit instantiation declarations. Since it's a source file, it will not be included by other sources. So namespace using directives and declarations may safely be used once the required headers have been included. Here is an example showing the required instantiations for our earlier add function template, instantiated for double, int, and std::string types:

    #include "add.h"
    #include <string>
    using namespace std;

    template int add<int>(int const &lvalue, int const &rvalue);
    template double add<double>(double const &lvalue, double const &rvalue);
    template string add<string>(string const &lvalue, string const &rvalue);

If we're sloppy and forget to mention an instantiation required by our program then the repair is easily made by adding the missing instantiation declaration to the above list. After recompiling the file and relinking the program we're done.

20.5: Instantiating function templates

Different from an ordinary function that results in code once the compiler reads its definition a template is not instantiated when its definition is read. A template is merely a recipe telling the compiler how to create particular code once it's time to do so. It's indeed very much like a recipe in a cooking book. You reading how to bake a cake doesn't mean you have actually baked that cake by the time you've read the recipe.

So, when is a function template actually instantiated? There are two situations where the compiler decides to instantiate templates:

They are instantiated when they are used (e.g., the function add is called with a pair of size_t values);
When addresses of function templates are taken they are instantiated. Example:
```
    char (*addptr)(char const &, char const &) = add;
```

The location of statements causing the compiler to instantiate a template is called the template's point of instantiation. The point of instantiation has serious implications for the function template's code. These implications are discussed in section 20.11.

The compiler is not always able to deduce the template's type parameters unambiguously. When the compiler reports an ambiguity it must be solved by the software engineer. Consider the following code:

    #include <iostream>
    #include "add.h"

    size_t fun(int (*f)(int *p, size_t n));
    double fun(double (*f)(double *p, size_t n));

    int main()
    {
        std::cout << fun(add);
    }

When this little program is compiled, the compiler reports an ambiguity it cannot resolve. It has two candidate functions as for each overloaded version of fun an add function can be instantiated:

    error: call of overloaded 'fun(<unknown type>)' is ambiguous
    note: candidates are: int fun(size_t (*)(int*, size_t))
    note:                 double fun(double (*)(double*, size_t))

Such situations should of course be avoided. Function templates can only be instantiated if there's no ambiguity. Ambiguities arise when multiple functions emerge from the compiler's function selection mechanism (see section 20.9). It is up to us to resolve the ambiguities. They could be resolved using a blunt static_cast (by which we select among alternatives, all of them possible and available):

    #include <iostream>
    #include "add.h"

    int fun(int (*f)(int const &lvalue, int const &rvalue));
    double fun(double (*f)(double const &lvalue, double const &rvalue));

    int main()
    {
        std::cout << fun(
                        static_cast<int (*)(int const &, int const &)>(add)
                    );
    }

But it's good practice to avoid type casts wherever possible. How to do this is explained in the next section (20.6).

As mentioned in section 20.4, the linker removes identical instantiations of a template from the final program, leaving only one instantiation for each unique set of actual template type parameters. To illustrate the linker's behavior we do as follows:

First we construct several source files:

source1.cc defines a function fun, instantiating add for int-type arguments, including add's template definition. It displays add's address:

    union PointerUnion
    {
        int (*fp)(int const &, int const &);
        void *vp;
    };

    #include <iostream>
    #include "add.h"
    #include "pointerunion.h"

    void fun()
    {
        PointerUnion pu = { add };

        std::cout << pu.vp << '\n';
    }

source2.cc defines the same function, but merely declares the proper add template using a template declaration (not an instantiation declaration). Here is source2.cc:

    #include <iostream>
    #include "pointerunion.h"

    template<typename Type>
    Type add(Type const &, Type const &);

    void fun()
    {
        PointerUnion pu = { add };

        std::cout << pu.vp << '\n';
    }

main.cc again includes add's template definition, declares the function fun and defines main, defining add for int-type arguments as well and displaying add's function address. It also calls the function fun. Here is main.cc:
```
    #include <iostream>
    #include "add.h"
    #include "pointerunion.h"

    void fun();

    int main()
    {
        PointerUnion pu = { add };

        fun();
        std::cout << pu.vp << '\n';
    }
```

All sources are compiled to object modules. Note the different sizes of source1.o (1912 bytes using g++ version 4.3.4. All sizes reported here may differ somewhat for different compilers and/or run-time libraries) and source2.o (1740 bytes). Since source1.o contains the instantiation of add, it is somewhat larger than source2.o, containing only the template's declaration. Now we're ready to start our little experiment.
Linking main.o and source1.o, we obviously link together two object modules, each containing its own instantiation of the same template function. The resulting program produces the following output:
```
    0x80486d8
    0x80486d8
```
Furthermore, the size of the resulting program is 6352 bytes.
Linking main.o and source2.o, we now link together an object module containing the instantiation of the add template, and another object module containing the mere declaration of the same template function. So, the resulting program cannot but contain a single instantiation of the required function template. This program has exactly the same size, and produces exactly the same output as the first program.

From our little experiment we conclude that the linker indeed removes identical template instantiations from a final program. Furthermore we conclude that using mere template declarations does not result in template instantiations.

20.6: Using explicit template types

In the previous section we saw that the compiler may encounter ambiguities when attempting to instantiate a template. In an example overloaded versions of a function (fun) existed, expecting different types of arguments. The ambiguity resulted from the fact that both arguments could have been provided by an instantiation of a function template. The intuitive way to solve such an ambiguity is to use a static_cast. But casts should be avoided wherever possible.

With function templates static casts may indeed be avoided using explicit template type arguments. Explicit template type arguments can be used to inform the compiler about the actual types it should use when instantiating a template. To use explicit type arguments the function's name is followed by an actual template type argument list which may again be followed by the function's argument list. The actual types mentioned in the actual template argument list are used by the compiler to `deduce' what types to use when instantiating the template. Here is the example from the previous section, now using explicit template type arguments:

    #include <iostream>
    #include "add.h"

    int fun(int (*f)(int const &lvalue, int const &rvalue));
    double fun(double (*f)(double const &lvalue, double const &rvalue));

    int main()
    {
        std::cout << fun(add<int>) << '\n';
    }

Explicit template type arguments can be used in situations where the compiler has no way to detect which types should actually be used. E.g., in section 20.3 the function template Type fun() was defined. To instantiate this function for the double type, we can call fun<double>().

20.7: Overloading function templates

Let's once again look at our add template. That template was designed to return the sum of two entities. If we would want to compute the sum of three entities, we could write:

    int main()
    {
        add(add(2, 3), 4);
    }

This is an acceptable solution for the occasional situation. However, if we would have to add three entities regularly, an overloaded version of the add function expecting three arguments might be a useful function to have. There's a simple solution to this problem: function templates may be overloaded.

To define an overloaded function template, merely put multiple definitions of the template in its header file. For the add function this would boil down to:

    template <typename Type>
    Type add(Type const &lvalue, Type const &rvalue)
    {
        return lvalue + rvalue;
    }
    template <typename Type>
    Type add(Type const &lvalue, Type const &mvalue, Type const &rvalue)
    {
        return lvalue + mvalue + rvalue;
    }

The overloaded function does not have to be defined in terms of simple values. Like all overloaded functions, a unique set of function parameters is enough to define an overloaded function template. For example, here's an overloaded version that can be used to compute the sum of the elements of a vector:

    template <typename Type>
    Type add(std::vector<Type> const &vect)
    {
        return accumulate(vect.begin(), vect.end(), Type());
    }

When overloading function templates we do not have to restrict ourselves to the function's parameter list. The template's type parameter list itself may also be overloaded. The last definition of the add template allows us to specify a vector as its first argument, but no deque or map. Overloaded versions for those types of containers could of course be constructed, but how far should we go? A better approach seems to be to look for common characteristics of these containers. If found we may be able to define an overloaded function template based on these common characteristics. One common characteristic of the mentioned containers is that they all support begin and end members, returning iterators. Using this, we could define a template type parameter representing containers that must support these members. But mentioning a plain `container type' doesn't tell us for what type of data it was instantiated. So we need a second template type parameter representing the container's data type, thus overloading the template's type parameter list. Here is the resulting overloaded version of the add template:

    template <typename Container, typename Type>
    Type add(Container const &cont, Type const &init)
    {
        return std::accumulate(cont.begin(), cont.end(), init);
    }

One may wonder whether the init parameter could not be left out of the parameter list as init will often have a default initialization value. The answer is a somewhat complex `yes', It is possible to define the add function as follows:

    template <typename Type, typename Container>
    Type add(Container const &cont)
    {
        return std::accumulate(cont.begin(), cont.end(), Type());
    }

But note that the template's type parameters were reordered, which is necessary because the compiler won't be able to determine Type in a call like:

    int x = add(vectorOfInts);

After reordering the template type parameters, putting Type first, an explicit template type argument can be provided for the first template type parameter:

    int x = add<int>(vectorOfInts);

In this example we provided a vector<int> argument. One might wonder why we have to specify int explicitly to allow the compiler to determine the template type parameter Type. In fact, we don't. A third kind of template parameter exists, a template template parameter, allowing the compiler to determine Type directly from the actual container argument. Template template parameters are discussed in section 22.3.

With all these overloaded versions in place, we may now start the compiler to compile the following function:

    using namespace std;

    int main()
    {
        vector<int> v;

        add(3, 4);          // 1 (see text)
        add(v);             // 2
        add(v, 0);          // 3
    }

In statement 1 the compiler recognizes two identical types, both int. It will therefore instantiate add<int>, our very first definition of the add template.
In statement 2 a single argument is used. Consequently, the compiler looks for an overloaded version of add requiring but one argument. It finds the overloaded function template expecting a std::vector, deducing that the template's type parameter must be int. It instantiates
```
    add<int>(std::vector<int> const &)
```
In statement 3 the compiler again encounters an argument list having two arguments. However, this time the types of the arguments aren't equal, so add template's first definition can't be used. But it can use the last definition, expecting entities having different types. As a std::vector supports begin and end, the compiler is now able to instantiate the function template
```
    add<std::vector<int>, int>(std::vector<int> const &, int const &)
```

Having defined the add function template for two equal and two different template type parameters we've exhausted the possibilities for using an add function template having two template type parameters.

Although it is possible to define another function template add this will introduce an ambiguity as the compiler won't be able to choose which of the two overloaded versions defining two differently typed function parameters to use. For example when defining:

    #include "add.h"

    template <typename T1, typename T2>
    T1 add(T1 const &lvalue, T2 const &rvalue)
    {
        return lvalue + rvalue;
    }
    int main()
    {
        add(3, 4.5);
    }

the compiler will report an ambiguity like the following:

        error: call of overloaded `add(int, double)' is ambiguous
        error: candidates are: Type add(const Container&, const Type&)
                                    [with Container = int, Type = double]
        error:                 T1 add(const T1&, const T2&)
                                    [with T1 = int, T2 = double]

Now recall the overloaded function template accepting three arguments:

    template <typename Type>
    Type add(Type const &lvalue, Type const &mvalue, Type const &rvalue)
    {
        return lvalue + mvalue + rvalue;
    }

It may be considered as a disadvantage that only equally typed arguments are accepted by this function (three ints, three doubles, etc.). To remedy this we define yet another overloaded function template, this time accepting arguments of any type. This function template can only be used if operator+ is defined between the function's actually used types, but apart from that there appears to be no problem. Here is the overloaded version accepting arguments of any type:

    template <typename Type1, typename Type2, typename Type3>
    Type1 add(Type1 const &lvalue, Type2 const &mvalue, Type3 const &rvalue)
    {
        return lvalue + mvalue + rvalue;
    }

Now that we've defined the above two overloaded function templates expecting three arguments let's call add as follows:

    add(1, 2, 3);

Should we expect an ambiguity here? After all, the compiler might select the former function, deducing that Type == int, but it might also select the latter function, deducing that Type1 == int, Type2 == int and

Type3
== int

. Remarkably, the compiler reports no ambiguity.

No ambiguity is reported because of the following. If overloaded template functions are defined using less and more specialized template type parameters (e.g., less specialized: all types different vs. more specialized: all types equal) then the compiler selects the more specialized function whenever possible.

As a rule of thumb: overloaded function templates must allow a unique combination of template type arguments to be specified to prevent ambiguities when selecting which overloaded function template to instantiate. The ordering of template type parameters in the function template's type parameter list is not important. E.g., trying to instantiate one of the following function templates results in an ambiguity:

    template <typename T1, typename T2>
    void binarg(T1 const &first, T2 const &second)
    {}
    template <typename T1, typename T2>
    void binarg(T2 const &first, T1 const &second)
    {}

This should not come as a surprise. After all, template type parameters are just formal names. Their names (T1, T2 or Whatever) have no concrete meanings.

Like any function overloaded functions may also be declared, either using plain declarations or instantiation declarations. Explicit template argument types may also be used. Example:

To declare a function template add accepting certain containers:

    template <typename Container, typename Type>
    Type add(Container const &container, Type const &init);

to use an instantiation declaration (in which case the compiler must already have seen the template's definition):

    template int add<std::vector<int>, int>
                    (std::vector<int> const &vect, int const &init);

to use explicit template type arguments:

    std::vector<int> vi;
    int sum = add<std::vector<int>, int>(vi, 0);

20.8: Specializing templates for deviating types

The initial add template, defining two identically typed parameters works fine for all types supporting operator+ and a copy constructor. However, these assumptions are not always met. For example, when using char *s using operator+ or a `copy constructor' does not make sense. The compiler will first try to instantiate the function template, but then compilation fails as operator+ is not defined for pointers.

In such situations the compiler may be able to resolve the template type parameters but it (or we ...) may then detect that the standard implementation is pointless or produces errors.

To solve this problem a template explicit specialization may be defined. A template explicit specialization defines the function template for which a generic definition already exists using specific actual template type parameters. As we saw in the previous section the compiler will always prefer a more specialized function over a less specialized one. So the template explicit specialization will be selected whenever possible.

A template explicit specialization may offer a specialization for its template type parameter(s). The special type will then consistently be subsituted for the template type parameter in all of the template function's code. For example if the explicitly specialized type is char const * then in the template definition

    template <typename Type>
    Type add(Type const &lvalue, Type const &rvalue)
    {
        return lvalue + rvalue;
    }

Type must be replaced by char const *, resulting in a function having prototype

    char const *add(char const *const &lvalue, char const * const &rvalue);

Now we try to use this function:

    int main(int argc, char **argv)
    {
        add(argv[0], argv[1]);
    }

However, the compiler ignores our specialization and tries to instantiate the initial function template. This fails leaving us wondering why it didn't select the explicit specialization....

To see what happened here we replay, step by step, the compiler's actions:

add is called with char * arguments.
Both types are equal, so the compiler deduces that Type equals char *.
Now it inspects the specialization. Can a char * template type argument match a char const *const & template parameter? Here opportunities for the allowable transformations from section 20.3 may arise. A qualification transformation seems to be the only viable one, allowing the compiler to bind a const-parameter to a non-const argument.
So, in terms of Type the compiler can match an argument of some Type or an argument of some Type const to a Type const &.
Type itself is not modified, and so Type is a char *.
Next the compiler inspects the available explicit specializations. It finds one, specializing for char const *.
Since a char const * is not a char * it rejects the explicit specialization and uses the generic form, resulting in a compilation error.

If our add function template should also be able to handle char * template type arguments another explicit specialization for char * may be required, resulting in the prototype

    char *add(char *const &lvalue, char * const &rvalue);

Instead of defining another explicit specialization an overloaded function template could be designed expecting pointers. The following function template definition expects two pointers to constant Type values and returns a pointer to a non-constant Type:

    template <typename Type>
    Type *add(Type const *t1, Type const *t2)
    {
        std::cout << "Pointers\n";
        return new Type;
    }

What actual types may be bound to the above function parameters? In this case only a Type const *, allowing char const *'s to be passed as arguments. There's no opportunity for a qualification transformation here. The qualification transformation allows the compiler to add a const to a non-const argument if the parameter itself (and not Type) is specified in terms of a const or const &. Loooking at, e.g., t1 we see that it's defined as a Type const *. There's nothing const here that's referring to the parameter (in which case it would have been

Type
const *const t1

or Type const *const &t1). Consequently a qualification transformation cannot be applied here.

As the above overloaded function template only accepts char const * arguments, it will not accept (without a reinterpret cast) char * arguments. So main's argv elements cannot be passed to our overloaded function template.

So do we have to define yet another overloaded function template, this time expecting Type * arguments? It is possible, but at some point it should become clear that our approach doesn't scale. Like ordinary functions and classes, function templates should have one conceptually clear purpose. Trying to add overloaded function templates to overloaded function templates quickly turns the template into a kludge. Don't use this approach. A better approach is to construct the template so that it fits its original purpose, to make allowances for the occasional specific case and to describe its purpose clearly in its documentation.

In some situations constructing template explicit specialization may of course be defensible. Two specializations for const and non-const pointers to characters might be appropriate for our add function template. Here's how they are constructed:

Start with the keyword template.
Next, an empty set of angle brackets is written. This indicates to the compiler that there must be an existing template whose prototype matches the one we're about to define. If we err and there is no such template then the compiler reports an error like:
```
    error: template-id `add<char*>' for `char* add(char* const&, char*
           const&)' does not match any template declaration
```
Now the function's head is defined. It must match the prototype of the initial function template or the form of a template explicit instantiation declaration (see section 20.4.1) if its specialized type cannot be determined from the function's arguments. It must specify the correct returntype, function name, maybe explicit template type arguments, as well as the function's parameter list.
Finally the function's body is defined, providing the special implementation that is required for the specialization.

Here are two explicit specializations for the function template add, expecting char * and char const * arguments:

    template <> char *add<char *>(char * const &p1,
                                        char * const &p2)
    {
        std::string str(p1);
        str += p2;
        return strcpy(new char[str.length() + 1], str.c_str());
    }

    template <> char const *add<char const *>(char const *const &p1,
                                        char const *const &p2)
    {
        static std::string str;
        str = p1;
        str += p2;
        return str.c_str();
    }

Template explicit specializations are normally included in the file containing the other function template's implementations.

Template explicit specializations can be declared in the usual way. I.e., by replacing its body with a semicolon.

When declaring a template explicit specialization the pair of angle brackets following the template keyword are essential. If omitted, we would have constructed a template instantiation declaration. The compiler would silently process it, at the expense of a somewhat longer compilation time.

When declaring a template explicit specialization (or when using an instantiation declaration) the explicit specification of the template type parameters can be omitted if the compiler is able to deduce these types from the function's arguments. As this is the case with the char (const) * specializations, they could also be declared as follows:

    template <> char *add(char * const &p1, char * const &p2)
    template <> char const *add(char const *const &p1,
                                char const *const &p2);

If in addition template <> could be omitted the template character would be removed from the declaration. The resulting declaration is now a mere function declaration. This is not an error: template functions and non-function templates may mutually overload each other. Ordinary functions are not as restrictive as function templates with respect to allowed type conversions. This could be a reason to overload a template with an ordinary function every once in a while.

A function template explicit specialization is not just another overloaded version of the the function template. Whereas an overloaded version may define a completely different set of template parameters, a specialization must use the same set of template parameters as its non-specialized variant. The compiler uses the specialization in situations where the actual template arguments match the types defined by the specialization (following the rule that the most specialized set of parameters matching a set of arguments will be used). For different sets of parameters overloaded versions of functions (or function templates) must be used.

Now that we've covered explicit specializations and overloading let's consider what happens when a class defines a std::string conversion operator (cf. section 10.3). A conversion operator is guaranteed to be used as an rvalue. This means that obects of a class defining a string conversion operator can be assigned to, e.g., string objects. But when trying to insert objects defining string conversion operators into streams then the compiler complains that we're attemping to insert an inappropriate type into an ostream. However, when this class defines an int conversion operator insertion is performed flawlessly. The reason for this distinction is that operator<< is defined as a plain (free) function when inserting a basic type (like int) but it is defined as a function template when inserting a string. Hence, when trying to insert an object of our class defining a string conversion operator the compiler visits all overloaded versions of insertion operators inserting into ostream objects. Since no basic type conversion is available the basic type insertion operators can't be used. Since the available conversions for template arguments do not allow the compiler to look for conversion operators our class defining the string conversion operator cannot be inserted into an ostream. If such a class should be insertable into ostream objects it must define its own overloaded insertion operator (in addition to the string conversion operator that was required to use the class's objects as rvalue in string assignments).

20.9: The function selection mechanism

When the compiler encounters a function call, it must decide which function to call when overloaded functions are available. Earlier we've encountered principles like `the most specific function will be selected'. This is a fairly intuitive description of the compiler's function selection mechanism. In this section we'll have a closer look at this mechanism.

Assume we ask the compiler to compile the following main function:

    int main()
    {
        process(3, 3);
    }

Furthermore assume that the compiler has encountered the following function declarations when it's about to compile main:

    template <class T>
    void process(T &t1, int i);                 // 1

    template <class T1, class T2>
    void process(T1 const &t1, T2 const &t2);   // 2

    template <class T>
    void process(T const &t, double d);         // 3

    template <class T>
    void process(T const &t, int i);            // 4

    template <>
    void process<int, int>(int i1, int i2);     // 5

    void process(int i1, int i2);               // 6

    void process(int i, double d);              // 7

    void process(double d, int i);              // 8

    void process(double d1, double d2);         // 9

    void process(std::string s, int i)          // 10

    int add(int, int);                          // 11

The compiler, having read main's statement, must now decide which function must actually be called. It proceeds as follows:

First, a set of candidate functions is constructed. This set contains all functions that:
- are visible at the point of the call;
- have the same names as the called function.
As function 11 has a different name, it is removed from the set. The compiler is left with a set of 10 candidate functions.
Second, the set of viable functions is constructed. Viable functions are functions for which type conversions exist that can be applied to match the types of the function's parameters of the functions and the types of the actual arguments to the types of the actual arguments. This implies that at least the number of arguments must match the number of parameters of the viable functions. Function 10's first argument is a string. As a string cannot be initialized by an int value no approprate conversion exists and function 10 is removed from the list of candidate functions. double parameters can be retained. Standard conversions do exists for ints to doubles, so all functions having ordinary double parameters can be retained. Therefore, the set of viable functions consists of functions 1 until 9.

At this point the compiler tries to determine the types of the template type parameters. It may use any of the three standard template parameter transformation procedures when trying to match actual types to template type parameters. In this process it concludes that no type cannot be determined for the T in function 1's T &t1 parameter as the argument 3 is a constant int value. Thus function 1 is removed from the list of viable functions. The compiler is now confronted with the following set of potentially instantiated function templates and ordinary functions:

    void process(T1 [= int] const &t1, T2 [= int] const &t2);   // 2
    void process(T [= int] const &t, double d);                 // 3
    void process(T [= int] const &t, int i);                    // 4
    void process<int, int>(int i1, int i2);                     // 5
    void process(int i1, int i2);                               // 6
    void process(int i, double d);                              // 7
    void process(double d, int i);                              // 8
    void process(double d1, double d2);                         // 9

The compiler associates a direct match count value to each of the viable functions. The direct match count counts the number of arguments that can be matched to function parameters without an (automatic) type conversion. E.g., for function 2 this count equals 2, for fuction 6 it is 1 and for function 9 it is 0. The functions are now (decrementally) sorted by their direct match count values:

                                                             match
                                                             count
    void process(T1 [= int] const &t1, T2 [= int] const &t2);  2 // 2
    void process(T [= int] const &t, int i);                   2 // 4
    void process<int, int>(int i1, int i2);                    2 // 5
    void process(int i1, int i2);                              2 // 6
    void process(T [= int] const &t, double d);                1 // 3
    void process(int i, double d);                             1 // 7
    void process(double d, int i);                             1 // 8
    void process(double d1, double d2);                        0 // 9

If there is no draw for the top value the corresponding function is selected and the function selection process is completed.

When multiple functions appear at the top the compiler verifies that no ambiguity has been encountered. An ambiguity is encountered if the sequences of parameters for which type conversions were (not) required differ. As an example consider functions 3 and 8. Using D for `direct match' and C for `conversion' the arguments match function 3 as D,C and function 8 as C,D. If 2, 4, 5 and 6 would not have been present then the compiler would have reported an ambiguity as the sequences of argument/parameter matching procedures differ for functions 3 and 8. The same difference is encountered comparing functions 7 and 8 and no such difference is encountered comparing functions 3 and 7.

At this point there is a draw for the top value and the compiler proceeds with the subset of associated functions (functions 2, 4, 5 and 6). With each of these functions an `ordinary parameter count' is associated counting the number of non-template parameters of the functions. The functions are decrementally sorted by this count, resulting in:

                                                         ordin. param.
                                                             count
    void process(int i1, int i2);                              2 // 6
    void process(T [= int] const &t, int i);                   1 // 4
    void process(T1 [= int] const &t1, T2 [= int] const &t2);  0 // 2
    void process<int, int>(int i1, int i2);                    0 // 5

Now there is no draw for the top value. The corresponding function (process(int, int), function 6) is selected and the function selection process is completed. Function 6 is used in main's function call statement.

If function 6 would not have existed function 4 would have been used. Assuming that neither function 4 nor function 6 would have existed the selection process would continue with functions 2 and 5:

                                                         ordin. param.
                                                             count
    void process(T1 [= int] const &t1, T2 [= int] const &t2);  0 // 2
    void process<int, int>(int i1, int i2);                    0 // 5

In this situation a draw is encountered once again and the selection process continues. A `type of function' value is associated with each of the functions having the highest ordinary parameter count and these functions are decrementally sorted by their type of function values. Value 2 is associated to ordinary functions, value 1 to template explicit specializations and value 0 to plain function templates.

If there is no draw for the top value the corresponding function is selected and the function selection process is completed. If there is a draw the compiler reports and ambiguity and cannot determine which function to call. Assuming only functions 2 and 5 existed then this selection step would have resulted in the following ordering:

                                                           function
                                                             type
    void process<int, int>(int i1, int i2);                    1 // 5
    void process(T1 [= int] const &t1, T2 [= int] const &t2);  0 // 2

Function 5, the template explicit specialization, would have been selected.

Figure 20: The function template selection mechanism

Here is a summary of the function template selection mechanism (cf. figure Figure 20):

The set of candidate functions is constructed: identical names;
The set of viable functions is constructed: correct number of parameters and available type conversions;
Template type determination, dropping templates whose type parameters cannot be determined;
Decrementally sort the functions by their direct match count values. If there no draw for the top value the associated function is selected, completing the selection process.
Inspect the functions associated with the top value for ambiguities in automatic type conversion sequences. If different sequences are encountered report an ambiguity and terminate the selection process.
Decrementally sort the functions associated with the top value by their ordinary parameter count values. If there no draw for the top value the associated function is selected, completing the selection process.
Decrementally sort the functions associated with the top value by their function type values using 2 for ordinary functions, 1 for template explicit specializations and 0 for plain template functions. parameter count values. If there no draw for the top value the associated function is selected, completing the selection process.
Report an ambiguity and terminate the selection process.

20.10: SFINAE: Substitution Failure Is Not An Error

Consider the following struct definition:

    struct Int
    {
        typedef int type;
    };

Although at this point it may seem strange to embed a typedef in a struct, in chapter 22 we'll encounter situations where this is actually very useful. It allows us to define a variable of a type that is required by the template. E.g., (ignore the use of typename in the following function parameter list, but see section 21.2.1 for details):

    template <typename Type>
    void func(typename Type::type value)
    {
    }

To call func(10) Int has to be specified explicitly since there may be many structs that define type: the compiler needs some assistance. The correct call is func<Int>(10). Now that it's clear that Int is meant the compiler may correctly deduce that value is an int.

But templates may be overloaded and our next definition is:

    template <typename Type>
    void func(Type value)
    {}

Now, to make sure this function is used we specify func<int>(10) and again this compiles flawlessly.

But as we've seen in the previous section when the compiler determines which template to instantiate it creates a list of viable functions by matching the parameter types of available function prototypes with the provided actual argument types. To do so it has to determine the types of the parameters and herein lies a problem.

When evaluating Type = int the compiler encounters the prototypes func(int::Type) (first template definition) and func(int) (second template definition). But there is no int::Type, and so in a way this generates an error. However, the error results from substituting the provided template type argument into the various template definitions.

A type-problem caused by substituting a type in a template definition is not considered an error, but merely an indication that that particular type cannot be used in that particular template. The template is therefore removed from the list of candidate functions.

This principle is known as substitution failure is not an error ( SFINAE) and it is often used by the compiler to select not only a simple overloaded function (as shown here) but also to choose among available template specializations (see also chapters 21 and 22).

20.11: Compiling template definitions and instantiations

Consider this definition of the add function template:

    template <typename Container, typename Type>
    Type add(Container const &container, Type init)
    {
        return std::accumulate(container.begin(), container.end(), init);
    }

Here std::accumulate is called using container's begin and end members.

The calls container.begin() and container.end() are said to depend on template type parameters. The compiler, not having seen container's interface, cannot check whether container actually has members begin and end returning input iterators.

On the other hand, std::accumulate itself is independent of any template type parameter. Its arguments depend on template parameters, but the function call itself isn't. Statements in a template's body that are independent of template type parameters are said not to depend on template type parameters.

When the compiler encounters a template definition, it verifies the syntactic correctness of all statements not depending on template parameters. I.e., it must have seen all class definitions, all type definitions, all function declarations etc. that are used in those statements. If it hasn't seen the required definitions and declarations the compiler will reject the template's definition. Therefore, when submitting the above template to the compiler the header file numeric must first have been included as this header file declares std::accumulate.

With statements depending on template parameters the compiler cannot perform those extensive syntactic checks. It has no way to verify the existence of a member begin for the as yet unspecified type Container. In these cases the compiler performs superficial checks, assuming that the required members, operators and types eventually become available.

The location in the program's source where the template is instantiated is called its point of instantiation. At the point of instantiation the compiler deduces the actual types of the template's parameters. At that point it checks the syntactic correctness of the template's statements that depend on template type parameters. This implies that the compiler must have seen the required declarations only at the point of instantiation. As a rule of thumb, you should make sure that all required declarations (usually: header files) have been read by the compiler at every point of instantiation of the template. For the template's definition itself a more relaxed requirement can be formulated. When the definition is read only the declarations required for statements not depending on the template's type parameters must have been provided.

20.12: Static assertions (C++0x)

The

    static_assert(constant expression, error message)

utility is defined by the C++0x standard to allow assertions to be made within template definitions. Here are two examples of its use:

    static_assert(BUFSIZE1 == BUFSIZE2,
                                "BUFSIZE1 and BUFSIZE2 must be equal");

    template <typename Type1, typename Type2>
    void rawswap(Type1 &type1, Type2 &type2)
    {
        static_assert(sizeof(Type1) == sizeof(Type2),
                        "rawswap: Type1 and Type2 must have equal sizes");
        // ...
    }

The first example shows how to avoid yet another preprocessor directive preprocessor directive: error vs. static_assert (in this case the #error directive).

The second example shows how static_assert can be used to ensure that a template operates under the right condition(s).

The string defined in static_assert's second argument is displayed and compilation stops if the condition specified in static_assert's first argument is false.

Like the #error preprocessor directive static_assert is a compile-time matter that doesn't have any effect on the run-time efficiency of the code in which it is used.

20.13: Summary of the template declaration syntax

In this section the basic syntactic constructions for declaring templates are summarized. When defining templates, the terminating semicolon should be replaced by a function body.

Not every template declaration may be converted into a template definition. If a definition may be provided it is explicitly mentioned.

A plain template declaration (a definition may be provided):

    template <typename Type1, typename Type2>
    void function(Type1 const &t1, Type2 const &t2);

A template instantiation declaration (no definition may be provided):

    template
    void function<int, double>(int const &t1, double const &t2);

A template using explicit types (no definition may be provided):

    void (*fp)(double, double) = function<double, double>;
    void (*fp)(int, int) = function<int, int>;

A template explicit specialization (a definition may be provided):

    template <>
    void function<char *, char *>(char *const &t1, char *const &t2);

A template declaration declaring friend function templates within class templates (covered in section 21.9, no definition may be provided):
```
    friend void function<Type1, Type2>(parameters);
```