• Next chapter
• Previous chapter
• Table of contents

Chapter 17: Templates

We're always interested in getting feedback. E-mail us if you like this guide, if you think that important material is omitted, if you encounter errors in the code examples or in the documentation, if you find any typos, or generally just if you feel like e-mailing. Send your email to Frank Brokken.

Please state the document version you're referring to, as found in the title (in this document: 4.4.2).

The C++ language support a mechanism which allows programmers to define completely general functions or classes, based on hypothetical arguments or other entities. Code in which this mechanism has been used is found in de chapter on abstract containers.

These general functions or classes become concrete code once their definitions are applied to real entities. The general definitions of functions or classes are called templates, the concrete implementations instantiations.

In this chapter we will examine template functions and template classes.

17.1: Template functions

        int sumVector(int *array, unsigned n)
        {
            int 
                sum(0);        
            for (int idx = 0; idx < n; ++idx)
                sum += array[idx];
            return (sum);
        }        
    

        double sumVector(double *array, unsigned n)
        {
            double 
                sum(0);        
            for (int idx = 0; idx < n; ++idx)
                sum += array[idx];
            return (sum);
        }        
    

In cases like these, template functions are used to create the truly general function. The template function can be considered a general recipe for constructing a function that can be used with the general array. In the coming sections we'll discuss the construction of template functions. First, the construction of a template function is discussed. Then the instantiation is covered. With template functions the argument deduction deserves special attention, which is given in section 17.1.3.

17.1.1: Template function definitions

    template <class T>
    T sumVector(T *array, unsigned n)
    {
        T
            sum(0);        
        for (int idx = 0; idx < n; ++idx)
            sum += array[idx];
        return (sum);
    }        
        

Normal scope rules and identifier rules apply to template definitions and declarations: the type T is a formal name, it could have been named Type. The formal typename that is used overrules, within the scope of the template definition or declaration, any previously defined identifiers by that name.

A template non-type parameter represents 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 an unsigned.

An alternative definition for the above template function, using a template non-type parameter is:

        template <class T, unsigned size>
        T sumVector(const T (&array)[size])
        {
            T
                sum(0);        
            for (int idx = 0; idx < size; ++idx)
                sum += array[idx];
            return (sum);
        }        

    template 
    <
        class T1, 
        class T2, 
        unsigned size1, 
        unsigned size2
    >
        T1
        (
            *outerProduct
            (
                T2 const (&v1)[size1], 
                T2 const (&v2)[size2]
            )
        )[size2];
            

        template <class T>
        void function()
        {
            unsigned
                p;
            ...
            {
                T::member
                    *p;
                ...
            }
        }        
    

The compiler does so, because it cannot know from the template definition whether member is a typename, defined in the class T, or a member of the class T. It takes the latter and, consequently, interprets the * as a multiplication operator.

What if this interpretation was not intended? In that case the typename keyword must be used. In the following template definition the * indicates a pointer definition to a T::member type.

        template <class T>
        void function()
        {
            unsigned
                p;
            ...
            {
                typename T::member
                    *p;
                ...
            }
        }        
    

17.1.1.1: The keyword 'typename'

As illustrated in section 17.1.1 The keyword typename can be used to disambiguate members and typenames in cases where the template type parameter represents a class type. It can also be used instead of the class keyword indicating a template type. So, instead of

    template <class T>
    void function(T type)
    {
        ...
    }
        

    template <typename T>
    void function(T type)
    {
        ...
    }
        

17.1.2: Instantiations of template functions

For example, in the following code assumes that the function sumVector has been defined in the header file sumvector.h. In the function main() the function sumVector() is called once for the int array x, once for the double array y, and once the address is taken of a sumVector() function. By taking the address of a sumVector function the type of the argument is defined by the type of the pointer variable, in this case a pointer to a function processing a array of unsigned long values. Since such a function wasn't available yet (we had functions for ints and doubles, it is constructed once its address is required. Here is the function main():

    #include "sumvector.h"

    int main()
    {
        int
            x[] = {1, 2};
        double
            y[] = {1.1, 2.2};
    
        cout << sumVector(x, 2) << endl     // first instantiation
            << sumVector(y, 2) << endl;     // second instantiation
    
        unsigned long                       // third instantiation
            (*pf)(unsigned long *, unsigned) = sumVector;
    
        return (0);
    }
        

    #include "template.h"

    unsigned fun(unsigned (*f)(unsigned *p, unsigned n));
    double fun(double (*f)(double *p, unsigned n));
    
    int main()
    {
        cout << fun(sumVector) << endl;
        return (0);
    }
        

    In function `int main()':
    call of overloaded `fun ({unknown type})' is ambiguous
    candidates are: fun(unsigned int (*)(unsigned int *, unsigned int))
                    fun(double (*)(double *, unsigned int))
        

    #include "template.h"

    unsigned fun(unsigned (*f)(unsigned *p, unsigned n));
    double fun(double (*f)(double *p, unsigned n));
    
    int main()
    {
        cout << fun(static_cast<double (*)(double *, unsigned)>(sumVector)) 
            << endl;
        return (0);
    }
        

If the same template function definition was included in different source files, which are then compiled to different object files which are thereupon linked together, there will, per type of template function, be only one instantiation of the template function in the final program.

This is illustrated by the following example, in which the address of a function sumVector() for int arrays is written to cout. The first part defines a function fun() in which the address of a sumVector() function is written to cout. The second part defines a function main(), defined in a different sourcefile, in which the address of a similar sumVector() function is written to cout, and in which fun() is called:

    // This is source file 1: fun.cc
    #include "template.h"
    void fun()
    {
        cout << static_cast<void *>
                (
                    static_cast<int (*)(int *, unsigned)>
                    (sumVector)
                )
            << endl;
    }

    // This is source file 2: main.cc
    #include "template.h"

    void fun();

    int main()
    {
        fun();
        
        cout << static_cast<void *>
                (
                    static_cast<int (*)(int *, unsigned)>
                    (sumVector)
                ) 
            << endl;

        return (0);
    }
        

    0x8048760
    0x8048760
        

Knowing this, it is also understandable that it is possible to declare a template function, if it is known that the required instantiation is available in another sourcefile. E.g., the function fun() in the above example could be defined as follows:

    template<class T>
    T sumVector(T *tp, unsigned n);

    void fun()
    {
        cout << static_cast<void *>
                (
                    static_cast<int (*)(int *, unsigned)>
                    (sumVector)
                )
            << endl;
    }
        

A third approach, is to declare template functions in header files, keeping the definition in a template source file. In the template source file the functions are instantiated by pointers to the appropriate functions. For example, define sumvector.cc as follows:

    template<class T>
    T sumVector(T *tp, unsigned n)
    {
        return (*tp);
    }

    static void
        *p1 = static_cast<int (*)(int *, unsigned)>(sumVector);
        

Finally, as the structure of the void * definitions is always the same, a macro definition might come in handy here. E.g., the sumvector.cc source file in which three sumVector() functions are instantiated could be written as follows:

    template<class T>
    T sumVector(T *tp, unsigned n)
    {
        return (*tp);
    }
                        // NOTE: the next line ends at the backslash
    #define instantiate(type)   \  
        static_cast<type (*)(type *, unsigned)>(sumVector)

    static void                 
        *p[] =
        {
            instantiate(int),
            instantiate(double),
            instantiate(unsigned)
        };

    #undef instantiate
        

17.1.3: Argument deduction

For example, consider once again the function

        template <class T, unsigned size>
        T sumVector(const T (&array)[size])
        {
            T
                sum(0);        
            for (int idx = 0; idx < size; ++idx)
                sum += array[idx];
            return (sum);
        }        

    #include "sumvector.t"  // define the template function

    int main()
    {
        int
            iArray[] = {1, 2, 3},
            *iPtr = iArray;

        sumVector(iArray);  // succeeds: size of iArray is known
        sumVector(iPtr);    // fails: size of array pointed to by 
                            // iPtr is unknown 
        return (0);
    }
        

It is not necessary for a template function's argument to match exactly the type of the template function's corresponding parameter. Three kinds of conversions are allowed here:

• lvalue transformations
• qualification conversions
• conversion to a base class instantiated from a class template

17.1.3.1: Lvalue transformations

There are three types of lvalue transformations:

• lvalue-to-rvalue conversions
• array-to-pointer conversions
• function-to-pointer conversions

• lvalue-to-rvalue conversions. Simply stated, an lvalue is an expression that may be used to the left of an assignment operator. It is an object whose address may be determined, and which contains a value. In contrast, an rvalue is an expression that may be used to the right of an assignment operator: it represents a value that does not have an address and that cannot be modified.
  In a statement like x = y; (in which x and y are variables of comparable types), the value of y is determined. Then this value is assigned to x. Determining the value of y is called an lvalue-to-rvalue conversion. An lvalue-to-rvalue conversion takes place in situations where the value of an lvalue expression is required. This also happens when a variable is used as argument to a function having a value parameter.
• array-to-pointer conversions. An array-to-pointer conversion occurs when the name of an array is assign to a pointervariable. This if frequently seen with functions using parameters that are pointer variables. When calling such functions, an array is often specified as argument to the function. The address of the array is then assigned to the pointer-parameter. This is called an array-to-pointer conversion.
• function-to-pointer conversions. This conversion is most often seen with functions defining a parameter which is a pointer to a function. When calling such a function the name of a function may be specified for the parameter which is a pointer to a function. The address of the function is then assigned to the pointer-parameter. This is called a function-to-pointer conversion.

In the first sumVector() function (section 17.1.1) the first parameter is defined as a T *. Here an array-to-pointer conversion is allowed, as it is an lvalue transformation, which is one of the three allowed conversions. Therefore, the name of an array may be passed to this function as its first argument.

17.1.3.2: Qualification conversions

A qualification conversion adds const or volatile qualifications to pointers. Assume the function sumVector() in section 17.1.1 was defined as follows:

    template <class T>
    T sumVector(T const *array, unsigned n)
    {
        T
            sum(0);        
        for (int idx = 0; idx < n; ++idx)
            sum += array[idx];
        return (sum);
    }        
        

17.1.3.3: Conversion to a base class

In section 17.2 template classes are formally introduced. However, they were already used earlier: abstract containers (covered in chapter 8) are actually defined as template classes. Like `normal' classes, template classes can participate in the construction of class hierarchies. In section 17.2.7 it is shown how a template class can be derived from another template class.

Assume that the template class Pipe is derived from the class queue. Furthermore, assume our function sumVector() was written to return the sum of the elements of a queue:

    template <class T>
    T sumVector(queue<T> &queue)
    {
        T
            sum(0);        

        while (!queue.empty())
        {
            sum += gueue.front();
            queue.pop();
        }
        return (sum);
    }        
        

• Pipe<xxx> has queue<xxx> as its base class, and
• queue<xxx> is a possible first argument of the above template function sumVector(), and
• a function argument which is of a derived class type may be used with a base class parameter of a template function.

This conversion is called a conversion to a base class instantiated from a class template. In the above example, the class template is Pipe, the base class is queue.

17.1.3.4: Summary: the template argument deduction algorithm

The following algorithm is used with template argument deduction when a template function is called with one or more arguments:

• In turn, the template parameters are identified in the parameters of the called function.
• For each template parameter, the template's type is deduced from the template function's argument (e.g., int if the argument is a Pipe<int> object).
• The three allowed conversions (see section 17.1.3) for template arguments are applied where necessary.
• If the same template parameter is used with multiple function parameters, the template types of the arguments must be the same. E.g., with template function twoVectors(vector<Type> &v1, vector<Type> &v2) the arguments used with twoVectors() must have equal types. E.g.,

  
      vector<int>
          v1,
          v2;
      ...
      twoVectors(v1, v2);
          
  

17.1.4: Explicit arguments

    #include "sumvector.h"

    int main()
    {
        int
            x[] = {1, 2};
        double
            y[] = {1.1, 2.2};
    
        cout << sumVector(x, 2) << endl
            << sumVector(y, 2) << endl;
        ...
    }
        

In section 17.1.2, a cast was used to disambiguate. Rather than using a static_cast, the type of the required function can be made explicit using another syntax: the function name may be followed by the types of the arguments, surrounded by pointed brackets. Here is the example of section 17.1.2 using explicit template argument types:

    #include "template.h"

    unsigned fun(unsigned (*f)(unsigned *p, unsigned n));
    double fun(double (*f)(double *p, unsigned n));
    
    int main()
    {
        cout << fun(sumVector<double, unsigned>) 
            << endl;
        return (0);
    }
        

Explicit template arguments may be partially specified. Like the specification of arguments of functions for which default arguments are defined, trailing template arguments may be omitted from the list of explicit template argument types. When they are omitted, the types mentioned in the template<> line preceding the template's function definition are used. So, in the above example the explicit argument type unsigned may be omitted safely, as the type of the second template's argument is already known from the argument type list. The function main() can therefore also be written as:

    int main()
    {
        cout << fun(sumVector<double>)
            << endl;
        return (0);
    }
        

    template<class T>
    T sumVector(T *tp, unsigned n)
    {
        return (*tp);
    }
    static void                 
        *p[] =
        {
            &sumVector<int>,
            &sumVector<double>,
            &sumVector<unsigned>
        };
        

17.1.4.1: Template explicit instantiation declarations

The explicit instantiations that were defined in the previous section were all embedded in the array of void pointers p[], which array was used to have a target for the addresses of the instantiated function.

This is, admittedly not too elegant, but it works well. However, it is also possible to declare a template providing explicit types of the template's arguments with the purpose of instantiating the corresponding template functions. An explicit instantiation declaration starts with the keyword template, to be followed by an explicit template function declaration. Although this is a declaration, it is considered by the compiler as a request to instantiate that particular variant of the function.

Using explicit instantiation declarations the final example of the previous section can be rewritten as follows:

    template<class T>
    T sumVector(T *tp, unsigned n)
    {
        return (*tp);
    }

    template      int sumVector<int>(int *, unsigned);
    template   double sumVector<double>(double *, unsigned);
    template unsigned sumVector<unsigned>(unsigned *, unsigned);
        

17.1.5: Template explicit specialization

The template's implementation of the sumVector() is not suited for variables of type char *, like the argv parameter of main(). If we want to be able to use sumVector() with variables of type char * as well, we can define the following special form of sumVector():

    #include <string>
    #include <numeric>

    template <> char *sumVector<char *>(char **argv, unsigned argc)
    {
        string
            s = accumulate(argv, argv + argc, string());

        return (strcpy (new char[s.size() + 1], s.c_str()));
    }
        

The template explicit specialization is normally included in the same file as the standard implementation of the template function.

If the template explicit specialization is to be used in a different file than the file in which it is defined, it must be declared. Of course, being a template function, the definition of the template explicit specialization can also be included in every file in which it is used, but that will also slow down the compilation of those other files.

The declaration of a template explicit specialization obeys the standard syntax of a function declaration: the definition is replaced by a semicolon. Therefore, the declaration of the above template explicit specialization is

In the declaration of the template explicit specialization the explicit specification of the template arguments (in the < ... > list following the name of the function) can be omitted if the types of the arguments can be deduced from the types of the arguments. With the above declaration this is the case. Therefore, the declaration can be simplified to:

Comparably, the template <> part of the template explicit specialization may be omitted. The result is an ordinary function or ordinary function declaration. This is not an error: template functions and non-template functions may overload each other. Ordinary functions are less restrictive in the type conversions that are allowed for their arguments than template functions, which might be a reason for using an ordinary function. On the other hand, a template explicit specialization must obey the form of the general template function of which it is a specialization. If the template function head is

17.1.6: Overloading template functions

    #include <vector>
    #include <numeric>

    template <class T>
    T sumVector(vector<T> &array)
    {
        return (accumulate(array.begin(), array.end(), T(0)));
    }        
        

    void fun(vector<int> &vi)
    {
        cout << sumVector(vi) << endl;
    }
        

Apart from defining overloaded versions, the overloaded versions can of course also be declared. E.g.,

    template <class T>
    T sumVector(vector<T> &array);
        

Using templates may result in ambiguities which overloading can't solve. Consider the following template function definition:

    template<class T>
    bool differentSigns(T v1, T v2)
    {
        return
        (
            v1 < 0 && v2 >= 0
            ||
            v1 >= 0 && v2 < 0
        );
    }
        

    template<class T1, class T2>
    bool differentSigns(T1 v1, T2 v2);
        

On the other hand, if one overloaded version can be interpreted as a more specialized variant of another version of a template function, then in principle the two variants of the template function could be used if the arguments are of the more specialized types. In this case, however, there is no ambiguity, as the compiler will use the more specialized variant if the arguments so suggest.

So, assume an overloaded version of sumVector() is defined having the following prototype and a snippet of code requiring the instantiation of sumVector:

    template <class T>
    T sumVector(T, unsigned);

    extern int
        iArray[];

    void fun()
    {
        sumVector(iArray, 12);
    }
        

In situations like this there is no ambiguity if both declarations are identical but for the fact that one version is able to accept a superset of the possible arguments that are acceptable for the other version. The original sumVector() template can accept only a pointer type as its first argument. The version declared here can accept a pointer type as well as any non-pointer type. A pointer type iArray is passed, so both template functions are candidates for instantiation. However, the original sumVector() template function can only accept a pointer type as its first argument. It is therefore more specialized than the one given here, and it is therefore selected by the compiler. If, for some reason, this is not appropriate, then an explicit template argument can be used to overrule the selection made by the compiler. E.g.,

17.1.7: Selecting an overloaded (template) function

• First, a set of candidate functions is constructed. This set contains all functions that are visible at the point of the call, having the same name as the function that is called. For a template function to be considered here, depends on the actual arguments that are used. These arguments must be acceptable given the standard template argument deduction process described in section 17.1.3. For example, assuming all of the following declarations were provided, an instantiation of

  
      template <class T, class U>
      bool differentSigns(T t, U u);
          
  

  and the functions

  
      bool differentSigns(double i, double j);
      bool differentSigns(bool i, bool j);
      bool differentSigns(int (&i)[2]);
          
  

  will all be elements of the set of possible functions in the following code fragment, as all of the four functions have the same name of the function that is called:

  
      void fun(int arg1, double arg2)
      {
          differentSigns(arg1, arg2);
      }
          
  

• 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 parameters of the functions and the types of the actual arguments. This removes the last two function declarations from the initial set: the third function is removed as there is no standard conversion from double to int, and the fourth function is removed as there is a mismatch in the number of arguments between the called function and the declared function.

• Third, the remaining functions are ranked in order of preference, and the first one is going to be used. Let's see what this boils down to:

  For the template function, the function differentSign<int, double> is instantiated. For this function the types of the two parameters and arguments for a pairwise exact match: score two points for the template function.

  For the function bool differentSigns(double i, double j) the type of the second parameter is exactly matches the type of the second argument, but a (standard) conversion int -> double is required for the first argument: score one point for this function.

  Consequently, the template function is selected as the one to be used. As an exercise, feed the abouve four declarations and the function fun() to the compiler and wait for the linker errors: ignoring the undefined reference to main(), the linker will complain that the (template) function

  bool differentSigns<int, double>(int, double) is an undefined reference.

If the template would have been declared as

    template <class T>
    bool differentSigns(T t, T u);
        

As we've seen, a template function in which all type parameters exactly match the types of the arguments prevails over an ordinary function in which a (standard) type conversion is required. Correspondingly, a template explicitly specialized function will prevail over an instantiation of the general template if both instantiations show an exact match between the types of the parameters and the arguments. For example, if the following template declarations are available:

    template <class T, class U>
    bool differentSigns(T t, U u);

    template <> bool differentSigns<double, int>(double, int);
        

Another situation in which an apparent ambiguity arises is when both an ordinary function is available and a proper instantiation of a template can be generated, both exactly matching the types of the arguments of the called function. In this case the compiler does not flag an ambiguity as the oridinary function is considered the more specialized function, which is therefore selected.

As a rule of thumb consider that when there are multiple viable functions sharing the top ranks of the set of viable functions, then the function template instantiations are removed from the set. If only one function remains, it is selected. Otherwise, the call is ambiguous.

17.1.8: Name resolution within template functions

    template <class T>
    T sumVector(T *array, unsigned n)
    {
        T
            sum = accumulate(array, array + n, T(0));        

        cout << "The array has " << n << " elements." << endl;
        cout << "The sum is " << sum << endl;

        return (sum);
    }        
        

Names (variables) whose type depend on a template parameter are resolved when the template is instantiated: at that point the relevant declarations must be available. The location where this happens is called the template's point of instantiation. As a rule of thumb, make sure that the necessary declarations (usually: header files) are available at every instantiation of the template.

17.2: Template classes

In the upcoming sections the construction of such a template class is discussed. In a sense, template classes compete with object oriented programming (cf. chapter 16), where a similar mechanism is seen. Polymorphism allows the programmer to separate algorithms from data, by deriving classes from the base class in which the algorithm is implemented, while implementing the data in the derived class, together with member functions that were defined as pure virtual functions in the base class to handle the data.

Generally, template classes are easier to use. It is certainly easier to write stack<int> istack to create a stack of ints than it is to derive a new class Istack: public stack and to implement all necessary member functions to be able to create a similar stack of ints using object oriented programming. On the other hand, for each different type that is used with a template class the complete class is reinstantiated, whereas in the context of object oriented programming the derived classes use, rather than copy, the functions that are already available in the base class.

Below a simple version of the template class vector is constructed: the essential characteristics of a template class are illustrated, without attempting to redo the existing vector class completely.

17.2.1: Template class definitions

The construction of a template class can normally begin with the construction of a normal class interface around a hypothetical type Type. If more hypothetical types are required, then hypothetical types U, V, W, etc. can be used as well. Assume we want to construct a class bvector, that can be used to store values of type Type. We want to provide the class with the following members:

• Constructors to create an object of the class bvector, possibly of a given size, as well as a copy constructor, since memory will be allocated by the object to store the values of type Type.
• A destructor.
• An overloaded operator= operator.
• A operator[] to retrieve and reassign the elements giving their indices.
• Forward and backward iterators to be able to visit all elements sequentially, either from the first to the last or from the last to the first.
• A sort() member to sort the elements of type Type.
• A member push_back() to add a new element at the end of the vector.

Now that we have decided which members we want, the class interface can be constructed. Like template functions, a template class definition begins with the keyword template, to be followed by a non-empty list of template type and/or non-type parameters, surrounded by angular brackets. This template announcement is then followed by the class interface, in which the template parameters may be used to represent types and constants. Here is initial class interface of the bvector template class, already showing member functions construct and destroy which are used in the implementation of the copy constructor, the destructor, and the overloaded assignment operator. The class also already contains an iterator type: it's defined simply as a pointer to an element of the vector. The reverse-iterator will be added later. Note that the bvector template class contains only a template type parameter, and no non-type parameter.

    template <class Type>
    class bvector
    {
        public:
            typedef reverse_iter<Type> reverse_iterator;

            bvector();
            bvector(unsigned n);
            bvector(bvector<Type> const &other);
            ~bvector();
            bvector<Type> const &operator=(bvector<Type> const &other);
            Type &operator[](int index);
            bvector<Type> &sort();
            void push_back(Type const &value);
            Type *begin();
            Type *end();
            reverse_iterator rbegin();
            reverse_iterator rend();
            unsigned size();
        private:
            void construct(bvector<Type> const &other);
            Type 
                *start,
                *finish,
                *end_of_storage;
    };
            

Different from template functions, template class parameters can have default arguments. This holds true both for template type- and template non-type parameters. If a template class is instantiated without specifying arguments for the template parameters, and if default template parameters were defined, then the defaults are used. Such defaults should be suitable for a majority of instantiations of the class. E.g., for the template class bvector the template announcement could have been altered to specify int as the default type:

Template class declarations are constructed by removing the template interface definition (the part between the curly braces), replacing the definition by a semicolon:

    template <class Type>
    class bvector;
        

In section 17.3 the full implementation of the bvector template class is given.

17.2.2: Template class instantiations

    bvector<int>
        bvInt;
        

    bvector<string>
        bvString;
        

In combination with the keyword extern these variables are declared rather than defined. E.g.,

    extern bvector<int>
        bvInt;
        

A template (type) parameter can be used to designate a type within another template. In the following function the template function manipulateVector() is defined, using type parameter T. It receives, defines, and returns bvector references and objects:

    template <class T>
    bvector<T> &manipulateVector(bvector<T> &vector)
    {
        bvector<T>
            extra(vector);
        ...
        return (vector);
    }
        

A template class is not instantiated if a reference or pointer to the class template is used. In the above example, the bvector<int> extra(...) results in a template instantiation, but the parameter and the return value of the function manipulateVector(), being references, don't result in template instantiations. However, if a member function of a template class is used with a pointer or reference to a template class object, then the class is instantiated. E.g., in the following code

    template <class T>
    void add(bvector<T> &vector, int value)
    {
        vector.push_back(value);
    }
        

17.2.3: Nontype parameters

    template <class Type, unsigned size>
    class Buffer
    {
        ...
        Type
            buffer[size];
    };
        

    Buffer<int, 20>
        buffer;
        

• Global variables have constant addresses, that can be used as arguments for nontype parameters
• Local and dynamically allocated variables have addresses that are not known by the compiler when the source file is compiled. These addresses can therefore not be used as arguments for nontype parameters.
• Lvalue transformations are allowed: if a pointer is defined as a nontype parameter, an arrayname may be specified.
• Qualification conversions are allowed: a pointer to a non-const object may be used with a non-type parameter defined as a const pointer.
• Promotions are allowed: a constant of a narrower datatype may be used for a nontype parameter of a wider type (e.g., short when an int is called for, long when a double is called for).
• Integral conversions are allowed: if an unsigned parameter is specified, an int may be used.

17.2.4: Template class member functions

Template member functions must be known to the compiler when the template is instantiated. The current GNU g++ compiler does not allow precompiled template classes, therefore the member functions of templates are inline functions. They can be defined inside the template interface or outside the template interface. Template member functions are defined as the inline member functions of any other class. However, for the member functions that are defined outside of the template's interface

• No inline keyword is required in the interface,
• A template <template parameter list> definition is required.

In the bvector template class a member function

    template <class T>
    void bvector<T>::push_back(T const &t)
    {
        if (finish == end_of_storage)
        {
            end_of_storage <<= 1;
            T
                *tmp = copy(start, finish, new T[max]);
            delete [] start;
            finish = tmp + (finish - start);
            finish = tmp;
        }
        *finish++ = t;
    }
        

17.2.5: Template classes and friend declarations

• A nontemplate friend function or class. This is a well-known friend declaration.
• A bound friend template class or function. Here the template parameters of the current template are used to bind the types of another template class or function, so that a one-to-one correspondence between the template's parameters and the template parameters of the friend template class or function is obtained.
• A unbound friend template class or function. Here the template parameters of the friend template class or function remain to be specified, and are not related in some predefined way to the current template's parameters.

17.2.5.1: Nontemplate friends

A template class may declare another function or class or class member function as its friend. Such a friend may access the private members of the template. Friend classes and ordinary friend functions can be declared as friends, but a class interface must have been seen by the compiler before one of its members can be declared a friend of a template class (in order to verify the name of the friend function against the interface.

For example, here are some friend declarations:

    class Friend
    {
        public:
            void member();
    };

    template <class T>
    class bvector
    {
        friend class AnotherFriend;     // declaration only is ok here
        friend void anotherMember();    // declaration is ok here
        friend Friend::member();        // Friend interface class required.
        ...
    };
        

17.2.5.2: Bound friends

With bound friend template classes or functions there is a one-to-one mapping between the types that are used with the instantiations of the friends and the template class declaring them as friends. Here the friends are themselves templates. For example:

    template <class T>
    class Friend;                   // declare a template class        

    template <class T>
    void function(Friend<T> &t);    // declare a template function

    template <class T>
    class AnotherFriend
    {
        public:
            void member();
    }

    template <class T>
    class bvector
    {
        friend class Friend<T>;                     // 1
        friend void function<T>(Friend<T> t);       // 2
        friend void AnotherFriend<T>::member();     // 3
    };
        

• At 1, the class Friend is declared a friend of bvector if it is instantiated for the same type T as bvector itself.
• At 2, the function funciont is declared a friend of bvector if it is instantiated for the same type T as bvector itself. Note that the template type parameter T appears immediately following the function name in the friend declaration. Here the correspondence between the function's template parameter and bvector's template parameter is defined. After all, function() could have been a parameterless function. Without the <T> affixed to the function name, it is an ordinary function, expecting an (unrestricted) instantiation of the class bvector for its argument.
• At 3, a specific member function of the class AnotherFriend, instantiated for type T is declared as a friend of the class bvector.

Assume we would like to be able to insert the elements of a bvector into an ostream object, using the insertion operator <<. For such a situation the copy() generic algorithm in combination with the ostream_iterator comes in handy. However, the latter iterator is a template function, depending on type T. If we can assume that start and finish are iterators of bvector, then the implementation is quickly realized by defining operator<< as a template function, and by declaring this operator as a friend of the class bvector():

    #include <iterator>
    #include <algorithm>
    #include <iostream>

    template<class T>
    class bvector
    {
        friend ostream &operator<< <T> (ostream &str, 
                                            bvector<T> const &vector);
        private:
            Iterator
                *start,
                *finish;
    };        

    template <class T>
    ostream &operator<<(ostream &str, bvector<T> const &vector)
    {
        ostream_iterator<T *>
            out(str, " ");
        return (copy(bvector.start, bvector.finish, out));
    }
        

17.2.5.3: Unbound friends

By prepending the friend declarations by the template<typelist> phrase, the friends received their own template parameter list. The template types of these friends are completely independent from the type of the template class declaring the friends. Such friends are called unbound friends. Every instantiation of an unbound friend has unrestricted access to the private members of every instantiation of the template class declaring the friends.

Here is the syntactic convention for declaring an unbound friend function, an unbound friend class and an unbound friend member function of a class:

    template <class Type>
    class bvector
    {
        template <class T>
        friend void function(); // unbound friend function

        template <class T>
        friend class Friend;    // unbound friend class

        template <class T>      // unbound friend member function
        friend void AnotherFriend<T>::member();

        ...
    };
        

17.2.6: Template classes and static data

    template <class Type>
    class TheClass
    {
        ...
        private:
            static int
                objectCounter;        
    };
        

    TheClass<int>
        theClassOne,
        theClassTwo;
        

    template <class Type>
    class TheClass
    {
        ...
        private:
            static int
                objectCounter;        
    };

    template <class Type>
    int 
        TheClass<Type>::objectCounter = 0;
        

    template <class Type>
    class TheClass
    {
        ...
        private:
            static TheClass
                *objectPtr;
    };

    template <class Type>
    TheClass<Type> 
        *TheClass<Type>::objectPtr = 0;
        

17.2.7: Derived Template Classes

    template<class T>
    class Base
    {
        public:
            Base(T const &t)
            :
                t(t)
            {}
            // and other members
        private:
            T const &t;
    };
        

    template<class T>
    class Derived: public Base<T>
    {
        public:
            Derived(T const &t)
            :
                Base(t)
            {}
            // and other members
    };
        

    class Ordinary: public Base<int>
    {
        public:
            Ordinary(int x)
            :
                Base(x)
            {}
    };

    // With the following object definition:
    Ordinary
        o(5);
        

17.2.8: Nesting and template classes

    #include <vector>

    template<class Type>
    class TheVector
    {
        public:
            class Enumeration
            {
                public:
                    Enumeration(vector<Type> const &vector)
                    :
                        vp(&vector),
                        idx(0)
                    {
                    }                    
                    Type const &nextElement()   // uses 'Type'
                    {
                        if (idx == vp->size())
                            throw NoSuchElementException(index);
                        return ((*vp)[idx++]);
                    }
                    bool hasMoreElements()
                    {
                        return (idx < vp->size());
                    }
                private:
                    vector<Type>
                        const *vp;
                    unsigned
                        idx;
            };

            TheVector<Type>::Enumeration getEnumeration()
            {
                return (Enumeration(vector));
            }
        private:
            vector<Type>
                vector;
    };

    int main()
    {
        TheVector<int>
            theVector;

        TheVector<int>::Enumeration
            en = theVector.getEnumeration();

        cout << (en.hasMoreElements() ? "has more elements" : 
                                        "no more elements") << endl;

        return (0);
    }

(Parts of) the nested class are instantiated once used. E.g., in the above example, the function nextElent() is not used. This is why the example can be compiled to a working program, as the NoSuchElementException() exception was never defined!

Enumerations and typedefs can be defined nested in template classes as well. For example, with arrays the distinction between the last index that can be used and the number of elements frequently causes confusion in people who are first exposed to the C-array types. The following construction automatically provides a valid last and nElements definition:

    template<class Type, int size>
    class Buffer
    {
        public:
            enum Limits
            {
                last = size - 1,
                nElements
            };
            typedef Type elementType;

            Buffer()
            :
                b(new Type [size])
            {}
        private:
            Type
                *b;
    };
        

Of course, the above represents the template form of these values and declarations. They must be instantiated before they can be used. E.g,

Note that a construction like Buffer::elementType is illegal, as the type of the Buffer class remains unknown.

17.2.9: Template members

    template <class T>
    class Outer
    {
        public:
            ...
            template <class T2>     // template class
            class Inner
            {
                public:
                    T
                        tVariable;
                    T2
                        t2Variable;
            };
            template <class Type>
            Type process(Type const &p1, Type const &p2)
            {
                Type
                    result;
                ...
                return (result);
            }
            ...
    };
        

Normall access rules apply: the function process() can be used by the general program, given an instantiated Outer object. Of course, this implies that a large number of possible instantiations of process() are possible. Actually, an instantiation is only then constructed when a process() function is in fact used. In the following code the function member function int process(int const &p1, int const &p2) is instantiated, even though the object is of the class Outer<double>:

    Outer<double>
        outer;

    outer.process(10, -3);
        

The template member function allows the processing of any other type by an object of the class Outer, which becomes important if the other type can be converted to the type that's used by the outer template class.

Any function can be defined as a template function, not just an ordinary member function. A constructor can be defined as a template as well:

    template <class T>
    class Outer
    {
        public:
            template <class T2>     // template class
            Outer(T2 const &initialValue)
            {
                ...
            }
            ...
    };
        

    Outer<int>
        t(12.5);    // uses Outer(double const &initialvalue)            
        

Template members can be defined inline or outside of their containing class. When a member is defined outside of its surrounding class, the template parameter list must precede the template parameter list of the template member. E.g.,

    template <class T>
    class Outer
    {
        public:
            template <class T2>     // template class
            class Inner;

            template <class Type>
            Type process(Type const &p1, Type const &p2);
    };

    template <class T> template <class Type>    // template class member
    class Outer<T>::Inner<Type>
    {
        public: 
            T
                tVariable;
            T2
                t2Variable;
    };  

    template <class T> template <class Type>    // template function member
    Type Outer<T>::process(Type const &p1, Type const &p2)
    {
        Type
            result;
        ...
        return (result);
    }
        

Not all compilers fully support member templates yet. E.g., the current GNU g++ compiler (2.95.2) does not support the member template classes, but it does support the member template functions.

17.2.10: Template class specializations

Assume we have a template class which supports the insertion of its type parameter into an ostream. E.g.,

    template <class Type>
    class Inserter
    {
        public:
            Inserter(Type const &t)
            :
                object(t)
            {}
            ostream &insert(ostream &os) const
            {
                return (os << object);
            }
        private:
            Type 
                object;
    };
        

    int main()
    {
        Inserter<int>
            ins(5);
    
        ins.insert(cout) << endl;
        return (0);    
    }
        

    class Person
    {
        public:
            ostream &insert(ostream &ostr) const;
    };
        

    int main()
    {
        Person 
            person;
        Inserter<Person>
            p2(person);
    
        p2.insert(cout) << endl;
    }
        

For this situation multiple solutions exist. One would be to define an operator<<(Person const &p) function which calls the Person::insert() function. But in the context of the Inserter class, this might not what we want. Instead, we might want to look for a solution that is closer to the class Inserter.

Such a solution exists in the form of a template class specialization. Such an explicit specialization definition starts with the wordt template, then two angular brackets (<>), which is then followed by the function definition for the instantiation of the template class for the particular template parameter(s). So, with the above function this yields the following function definition:

    template<>
    ostream  &Inserter<Person>::insert(ostream &os) const
    {
        return (object.insert(os));
    }
        

Note that the explicit specialization definition is a true definition: it should not be given in the header file of the Inserter template class, but it should have its own sourcefile. However, in order to inform the compiler that an explicit specialization is available, it can be declared in the template's header file. The declaration is straightforward: the code-block is replaced by the semicolon:

    template<>
    ostream  &Inserter<Person>::insert(ostream &os) const;
        

It is even possible to specialize a complete template class. For the above class Inserter which would boil down to the following for the class double:

    template <>
    class Inserter
    {
        public:
            Inserter<double>(double const &t);
            ostream &insert(ostream &os) const;
        private:
            double
                object;
    };
        

    Inserter<double>(double const &t)   // NO template<> prefix !
    :
        object(t)
    {}
        

17.2.11: Template class partial specializations

Let's assume we are working on a image processing program. A class defining an image receives two int template parameters, e.g.,

    template <int columns, int rows>
    class Image        
    {
        public:
            Image()
            {
                // use 'columns' and 'rows'
            }
            ...
    };
        

    template <int rows>
    class Image<320, rows>
    {
        public:
            Image()
            {
                // use 320 columns and 'rows' rows.
            }
            ...
    };
        

    Image<320, 240>
        image;
        

Every template parameter can be used for the specialization. In the last example the columns were specialized, but the rows could have been specialized as well. The following partial specialization of the template class Image specializes the rows parameter and leaves the columns open for later specification:

    template <int columns>
    class Image<columns, 200>
    {
        public:
            Image()
            {
                // use 'columns' columns and 200 rows.
            }
            ...
    };
        

    Image<1024, 768>
        generic;
    Image<320, 240>
        columnSpecialization;
    Image<480, 200>
        rowSpecialization;
        

One might wonder what happens if we want to construct a

    Image<320, 200>
        superSpecialized;
        

    template <>
    class Image<320, 200>
    {
        public:
            Image()
            {
                // use 320 columns and 200 rows.
            }
            ...
    };
        

17.2.12: Name resolution within template classes

On the other hand, if a template defines a <class Type> template parameter, which is the returntype of some template function, e.g.,

    Type returnValue();
        

    template <class Type>
    class Resolver
    {
        public:
            Resolver();
            Type result();
        private:
            Type
                datum;
            static int
                value;
    };
        

    // ----------------------- example 1: define the static variable
    int Resolver<string>::value = 12;   

    // ----------------------- example 2: define a Resolver object
    int main()
    {
        Resolver<string>
            resolver;
    }

    // ----------------------- example 3: declare a Resolver object
    extern Resolver<string>
        resolver;
        

17.3: An example: the implementation of the bvector template

The implementation of the bvector is generally straightforward: the basic constructors initialize the data members of the bvector, using an auxiliary private function init():

    bvector()
    {
        init(0);
    };
    bvector(unsigned n)
    {
        init(n);
    }
    void init(unsigned n)
    {
        if (n)
        {
            start = new Type[n];
            finish = start + n;
            end_of_storage = start + n;
        }
        else
        {
            start = 0;
            finish = 0;
            end_of_storage = 0;
        }
    }                    
        

Here are the destructor, the copy constructor, the overloaded assignment operator and the private construct() function:

    ~bvector()
    {
        delete [] start;
    }            

    bvector(bvector<Type> const &other)
    {
        construct(other);
    }

    bvector<Type> const &operator=(bvector<Type> const &other)
    {
        if (this != &other)
        {
            delete [] start;
            construct(other);
        }
        return (*this);
    }

    void construct(bvector<Type> const &other)
    {
        init(other.finish - other.start);
        copy(other.start, other.finish, start);
    }
        

The operator[] first checks the validity of the index that's passed to the function. If out of bounds a simple exception is thrown. Otherwise the function is completely standard. Note that the current implementation of bvector does not allow for bvector<Type> const objects to use the operator[]. Here is the implementation of the operator[] function:

    Type &operator[](unsigned index) throw(char const *)
    {
        if (index > (finish - start))
            throw "bvector array index out of bounds";
        return (start[index]);
    }
        

The sort() function uses the available sort() generic algorithm. The ::sort() notation is required to prevent confusion: without the scope resolution operator the compiler complains about us having specified the wrong arguments for the function sort(). Here is the implementation of sort():

    bvector<Type> &sort()
    {
        ::sort(start, finish);
        return (*this);
    }
        

    void push_back(Type const &value)
    {
        if (!finish)
        {
            init(1);
            finish = start;
        }
        else if (finish == end_of_storage)
        {
            bvector<Type>
                enlarged((end_of_storage - start) << 1);
            copy(start, finish, enlarged.start);
            delete [] start;
            finish = enlarged.start + (finish - start);
            start = enlarged.start;
            end_of_storage = enlarged.end_of_storage;
            enlarged.start = 0;
        }
        *finish++ = value;
    }
        

    typedef Type *iterator;
    typedef reverse_iter<Type> reverse_iterator;

    iterator begin()
    {
        return (start);
    }
    iterator end()
    {
        return (finish);
    }
    reverse_iterator rbegin()
    {
        return (reverse_iterator(finish));
    }
    reverse_iterator rend()
    {
        return (reverse_iterator(start));
    }
        

17.3.1: The reverse_iter template class

Given the data type Type to which a reverse iterator points, the reverse iterator must support the following operations:

• It must be possible to construct a reverse iterator from an iterator.
• A dereference operator Type &operator*(), returning the data item to which the reverse iterator points.
• A pointer operator Type *operator->() returning the address of the data element, to be used when the data element is an object having members.
• A prefix and postfix increment operator returning a reverse iterator pointing to the previous data element.

    Type &operator*() const 
    {
        Type  
            *tmp = current;
        return (*--tmp);
    }
        

    reverse_iter<Type>& operator++() 
    {
        --current;
        return (*this);
    }
        

    reverse_iter<Type> operator++(int) 
    {
        reverse_iter<Type>
            tmp(current--);
        return (tmp);
    }
        

17.3.2: The final implementation

    #include <algorithm>

    template <class Type>
    class reverse_iter 
    {
        public:
            explicit reverse_iter(Type *x) 
            : 
                current(x) 
            {}
            Type &operator*() const 
            {
                Type  
                    *tmp = current;
                return (*--tmp);
            }
            Type *operator->() const 
            { 
                return &(operator*()); 
            }
            reverse_iter<Type>& operator++() 
            {
                --current;
                return (*this);
            }
            reverse_iter<Type> operator++(int) 
            {
                reverse_iter<Type>
                    tmp(current--);
                return (tmp);
            }
            bool operator!=(reverse_iter<Type> const &other) 
            {
                return (current != other.current);
            }
        private:
            Type 
                *current;
    }; 

    template <class Type>
    class bvector
    {
        typedef Type *iterator;
        typedef reverse_iter<Type> reverse_iterator;
    
        public:
            bvector()
            {
                init(0);
            };
            bvector(unsigned n)
            {
                init(n);
            }
            bvector(bvector<Type> const &other)
            {
                construct(other);
            }
            ~bvector()
            {
                delete [] start;
            }            
            bvector<Type> const &operator=(bvector<Type> const &other)
            {
                if (this != &other)
                {
                    delete [] start;
                    construct(other);
                }
                return (*this);
            }
            Type &operator[](unsigned index) throw(char const *)
            {
                if (index >= (finish - start))
                    throw "bvector array index out of bounds";
                return (start[index]);
            }
            bvector<Type> &sort()
            {
                ::sort(start, finish);
                return (*this);
            }
            void push_back(Type const &value)
            {
                if (!finish)
                {
                    init(1);
                    finish = start;
                }
                else if (finish == end_of_storage)
                {
                    bvector<Type>
                        enlarged((end_of_storage - start) << 1);
                    copy(start, finish, enlarged.start);
                    delete [] start;
                    finish = enlarged.start + (finish - start);
                    start = enlarged.start;
                    end_of_storage = enlarged.end_of_storage;
                    enlarged.start = 0;
                }
                *finish++ = value;
            }
            iterator begin()
            {
                return (start);
            }
            iterator end()
            {
                return (finish);
            }
            reverse_iterator rbegin()
            {
                return (reverse_iterator(finish));
            }
            reverse_iterator rend()
            {
                return (reverse_iterator(start));
            }
            unsigned size()
            {
                return (finish - start);
            }
        private:
            void init(unsigned n)
            {
                if (n)
                {
                    start = new Type[n];
                    finish = start + n;
                    end_of_storage = start + n;
                }
                else
                {
                    start = 0;
                    finish = 0;
                    end_of_storage = 0;
                }
            }                    
            void construct(bvector<Type> const &other)
            {
                init(other.finish - other.start);
                copy(other.start, other.finish, start);
            }
                    
            Type 
                *start,
                *finish,
                *end_of_storage;
    };
            

A small main() function using the bvector data type is given next:

#include <iostream>
#include <string>
#include "bvector.h"

int main()
{
    bvector<int>
        bv(5),
        b2;

    b2 = bv;

    bv[0] = 3;
    bv[1] = 33;
    bv[2] = 13;
    bv[3] = 6;
    bv[4] = 373;

    copy(bv.begin(), bv.end(), ostream_iterator<int>(cout, " "));
    cout << endl;

    bvector<int>::reverse_iterator
            rit  = bv.rbegin();

    while (rit != bv.rend())
        cout << *rit++ << ", ";
    cout << endl;

    bv.push_back(12);
    bv.push_back(5);

    copy(bv.begin(), bv.end(), ostream_iterator<int>(cout, " "));
    cout << endl;

    bv.sort();
    copy(bv.begin(), bv.end(), ostream_iterator<int>(cout, " "));
    cout << "bv has " << bv.size() << " elements\n";

    bvector<string>
        bstr;

    bstr.push_back("bravo");
    bstr.push_back("delta");
    bstr.push_back("foxtrot");
    bstr.push_back("echo");
    bstr.push_back("charley");
    bstr.push_back("alpha");

    bstr.sort();
    copy(bstr.begin(), bstr.end(), ostream_iterator<string>(cout, " "));
    cout << endl;
}

• Next chapter
• Previous chapter
• Table of contents