Function Templates

A function template itself it is not a definition of a function; it is a blueprint or a recipe for defining an entire family of functions . A function template is a parametric function definition, where a particular function instance is created by one or more parameter values. The compiler uses a function template to generate a function definition when necessary. If it is never necessary, no code results from the template. A function definition that is generated from a template is an instance or an instantiation of the template. The parameters of a function template are usually data types, where an instance can be generated for a parameter value of type int, for example, and another with a parameter value of type string. But parameters are not necessarily types. They can be other things such as a dimension, for example. Let’s consider a specific example.

In the previous chapter, we defined various overloads of larger(), often for different parameter types. It makes for a good candidate for a template. Figure 9-1 shows a template for this function.

The function template starts with the template keyword to identify it as such. This is followed by a pair of angled brackets that contains a list of one or more template parameters. In this case, there’s only one, the parameter T. T is commonly used as a name for a parameter because most parameters are types, but you can use whatever name you like for a parameter; names such as my_type or Comparable are equally valid. Especially if there are multiple parameters, using more descriptive names may be recommended.

The typename keyword identifies that T is a type. T is hence called a template type parameter. You can also use the keyword class here, but we prefer typename because the type argument can be a fundamental type as well, not just a class type.

The rest of the definition is similar to a normal function except that the parameter name T is sprinkled around. The compiler creates an instance of the template by replacing T throughout the definition with a specific type. The type assigned to a type parameter T during instantiation is called a template type argument.

You can position the template in a source file in the same way as a normal function definition; you can also specify a prototype for a function template. In this case, it would be as follows:

Either the prototype or the definition of the template must appear in the source file before any statement that results in an instance of the template.

Creating Instances of a Function Template

The compiler creates instances of the template from any statement that uses the larger() function. Here’s an example:

You just use the function in the normal way. You don’t need to specify a value for the template parameter T. The compiler deduces the type that is to replace T from the arguments in the larger() function call. This mechanism is referred to as template argument deduction. The arguments to larger() are literals of type double, so this call causes the compiler to search for an existing definition of larger() with double parameters. If it doesn’t find one, the compiler creates this version of larger() from the template by substituting double for T in the template definition.

The resulting function definition accepts arguments of type double and returns a double value. With double plugged into the template in place of T, the template instance will effectively be as follows:

The compiler makes sure to generate each template instance only once. If a subsequent function call requires the same instance, then it calls the instance that exists. Your program only ever includes a single copy of the definition of each instance, even if the same instance is generated in different source files. Now that you are familiar with the concepts, let’s road test a function template:

This produces the following output:

The compiler creates a definition of larger() that accepts arguments of type double as a result of the first statement in main(). The same instance will be called in the next statement. The third statement requires a version of larger() that accepts an argument of type int, so a new template instance is created. The last statement results in yet another template instance being created that has parameters of type std::string and returns a value of type std::string.

Template Type Parameters

The name of a template type parameter can be used anywhere in the template’s function signature, return type, and body. It is a placeholder for a type and can thus be put in any context you would normally put the concrete type. That is, suppose T is a template parameter name; then you can use T to construct derived types such as T&, const T&, T*, and T[][3]. Or you can use T as an argument to a class template, as for instance in std::vector<T>.

Our larger() function template, for instance, currently instantiates functions that accept their arguments by value:

As witnessed by Ex9_01, this template can be instantiated with class types such as std::string as well. In the previous chapter, you learned that passing objects by value results in gratuitous copies of these objects, which is something you should avoid if possible. The standard mechanism for this, of course, is to pass the arguments by reference instead. We would therefore be better off redefining our template as follows:

While our latest definition of the larger() template is definitely superior, in the remainder of this chapter we’ll mostly keep using the version that passes the arguments by value. This makes it easier to explain a few additional aspects of function templates.

Explicit Template Arguments

If you add the following statement to main() in Ex9_01.cpp, it will not compile:

The arguments to larger() are of different types, whereas the parameters for larger() in the template are of the same type. The compiler cannot create a template instance that has different parameter types. Obviously, one argument could be converted to the type of the other, but you have to code this explicitly; the compiler won’t do it. You could define the template to allow the parameters for larger() to be different types, but this adds a complication that we’ll discuss later in this chapter: which of the two do you use for the return type? For now, let’s focus on how you can specify the argument for a template parameter explicitly when you call the function. This allows you to control which version of the function is used. The compiler no longer deduces the type to replace T; it accepts what you specify.

You can resolve the problem of using different arguments types with larger() with an explicit instantiation of the template:

You put the explicit type argument for the function template between angled brackets after the function name. This generates an instance with T as type double. When you use explicit template arguments, the compiler has complete faith that you know what you are doing. It will insert an implicit type conversion for the first argument to type double. It will provide implicit conversions, even when this may not be what you want. Here’s an example:

You are telling the compiler to use a template instance with T as type int. This necessitates an implicit conversion of the second argument to int. The result of this conversion is the value 19, which may not be what you really want in this case. If you’re lucky, your compiler will warn you about such dangerous conversions, though not all compilers will.

Function Template Specialization

Suppose that you extended Ex9_01.cpp to call larger() with arguments that are pointers:

The compiler instantiates the template with the parameter as type int*. The prototype of this instance is as follows:

The return value is an address, and you have to dereference it to output the value. However, the result may very well be 10, which is incorrect. This is because the comparison is between addresses passed as arguments, not the values at those addresses. The compiler is free to rearrange the memory locations of local variables, so the actual outcome may vary across compilers, but given that the small_int variable comes second, it is certainly not unthinkable that its address would be larger. This illustrates how easy it is to create hidden errors using templates. You need to be particularly careful when using pointer types as template arguments.

You can define a specialization of the template to accommodate a template argument that is a pointer type. For a specific parameter value or set of values in the case of a template with multiple parameters, a template specialization defines a behavior that is different from the standard template. The definition of a template specialization must come after a declaration or definition of the original template. If you put a specialization first, then the program won’t compile. The specialization must also appear before its first use.

The definition of a specialization starts with the template keyword, but the parameter is omitted, so the angled brackets following the keyword are empty. You must still define the type of argument for the specialization, and you place this between angled brackets immediately following the template function name. The definition for a specialization of larger() for type int* is as follows:

The only change to the body of the function is to dereference the arguments a and b so that you compare values rather than addresses. To use this in Ex9_01.cpp, the specialization would need to be placed after the prototype for the template and before main().

Function Templates and Overloading

You can overload a function template by defining other functions with the same name. Thus, you can define “overrides” for specific cases, which will always be used by the compiler in preference to a template instance. As always, each overloaded function must have a unique signature.

Let’s reconsider the previous situation in which you need to overload the larger() function to take pointer arguments. Instead of using a template specialization for larger(), you could define an overloaded function. The following overloaded function prototype would do it:

In place of the specialization definition, you’d use this function definition:

It’s also possible to overload an existing template with another template. For example, you could define a template that overloads the larger() template in Ex9_01.cpp to find the largest value contained in an array:

The parameter list differentiates functions produced from this template from instances of the original template. You could define another template overload for vectors:

In fact, and this is a bit more subtle, you could even overload the original template with another template specifically for pointer types:

Note that this is not a specialization of the original template but instead a second, distinct template that will be instantiated only for pointer types. You do not need to know the details of exactly why and how this works. It suffices to know that if the compiler encounters a call larger(x,y) where x and y are pointers to values of the same type, it will instantiate an instance of this second function template; otherwise, it will still use an appropriate instance from our previous template.

You could extend Ex9_01.cpp to demonstrate this. Add the previous templates to the end of the source file and these prototypes at the beginning:

Naturally, you'll also need an #include directive for the vector header. The code in main() can be changed to the following:

The complete example is in the code download as Ex9_02.cpp. This generates instances of all three overloaded templates. If you compile and execute it, the output will be as follows:

Function Templates with Multiple Parameters

You’ve been using function templates with a single parameter, but there can be several parameters. Recall from earlier that we had some trouble compiling the following:

The compiler failed to deduce the template type argument because the two function arguments have a different type: int and double, respectively. We solved this before by explicitly specifying the type. But perhaps you were wondering why we could not simply create a larger() template for which the function arguments are allowed to be different? This could then look something like this:

Allowing different types for each function argument is easy enough and can often be a good idea to keep your templates as generic as possible. However, in cases such as this, you run into trouble when specifying the return type. That is, in the previous pseudocode, what should we put instead of the three question marks? T1? T2? Neither is correct in general because both could lead to undesired conversions.

A first possible solution is to add an extra template type argument to provide a way of controlling the return type. Here’s an example:

The compiler, however, cannot deduce this return type, TReturn . Template argument deduction works on the basis of the arguments passed in the function’s argument list alone. You must therefore always specify the TReturn template argument yourself. The compiler can deduce the type for the arguments, though, so you can get away with specifying just the return type. In general, if you specify fewer template arguments than the number of template parameters, the compiler will deduce the others. The following three lines are therefore equivalent:

Clearly, the sequence of parameters in the template definition is important here. If you had the return type as the second parameter, you’d always have to specify both parameters in a call. If you specify only one parameter, it would be interpreted as the argument type, leaving the return type undefined. Because we specified the return type as size_t, in all three cases, the results of these function calls will all be 2. The compiler creates a function that accepts arguments of type double and int and then converts its result to a value of type size_t.

While we did illustrate how multiple parameters can be defined and what that means for template argument deduction, you may have noticed that we still haven’t found a satisfactory solution that would allow us to write the following:

We’ll resolve this once and for all in the next section.

Return Type Deduction for Templates

In the previous chapter, you learned about automatic return type deduction for functions. For regular functions, the use of return type deduction was somewhat limited. While it may save you some typing, it does come with the risk of making your code less obvious to read. After all, the reader needs to make the same deduction as the compiler.

In the context of function templates, however, return type deduction can be a godsend. The return type of a template function with one or more type parameters may depend on the types used to instantiate the template. We have seen this already with the following example:

There is no easy way you can specify which type should be returned here. But there is an easy way to have the compiler deduce it for you after instantiating the template:

With this definition, the following statements will compile just fine, without the need to explicitly specify any type argument:

With our original definition of larger() in Ex9_01, which had only one type parameter, both of these instantiations would’ve been ambiguous and thus would’ve failed to compile. A working program using the two-parameter version is found in Ex9_03.cpp.

Default Values for Template Parameters

You can specify default values for function template parameters. For example, you could specify double as the default return type in the prototype for the template introduced earlier like this:

If you don’t specify any template parameter values, the return type will be double. Note that we only use this example to introduce default values for template parameters, not because it is necessarily a good idea to define larger() like this! The reason this is not such a great idea is that this default, double, is not always what you want. The larger() function resulting from the following statement, for instance, accepts arguments of type int and returns the result as type double:

The main point we want to convey with this example, though, is that you can specify default values for template arguments at the beginning of the template argument list. You’ll recall that for function parameters it was only possible to define default values at the end of the list. You have quite some more flexibility when specifying default values for template parameters. In our first example, TReturn is the first in the list. But you can also specify default values for parameters in the middle of the list or at the end. Here is yet another larger() template to illustrate the latter:

In this example, we use the TArg as the default value for the TReturn template parameter. Using a template parameter name in the default value of other parameters is possible only if that name, TArg in our example, appears earlier in the parameter list. This example again mostly serves to illustrate what is possible and less as something that is necessarily a good idea. If the default value for TReturn does not suit you and you have to specify another type explicitly, you would have to specify all other arguments as well. Nevertheless, it is common practice to specify default values for template parameters at the end of the list. The Standard Library uses this extensively, often also for nontype template parameters. Nontype template parameters are discussed next.

Nontype Template Parameters

All the template parameters you have seen so far have been types. Function templates can also have nontype parameters that require nontype arguments.

You haven’t met these last two. The former is introduced in Chapter 18; the latter is a more advanced feature we won’t discuss in this book. The application of nontype template parameters to all these types is beyond the scope of this book as well. We’ll only consider a few elementary examples with integral type parameters, just to show how it works.

The compiler needs to be able to evaluate the arguments corresponding to nontype parameters at compile time. For integral type parameters, for instance, this mostly means they will be either integral literals or integral compile-time constants.

Suppose you need a function to perform range checking on a value. You could define a template to handle a variety of types:

This template has a type parameter, T, and two nontype parameters, lower and upper, that are both of type int. The compiler can’t deduce all of the template parameters from the use of the function. The following function call won’t compile:

Compilation fails because upper and lower are unspecified. To use this template, you must specify the template parameter values. The correct way to use this is as follows:

It would be better to put the nontype template parameters before the template type parameter as follows:

If you define your template like that, the compiler is capable of deducing the type argument:

Even better, however, would be to use function parameters for the limits in this case. Function parameters give you the flexibility of being able to pass values that are calculated at runtime, whereas here you must supply the limits at compile time.

Summary