Writing Overloaded Templates

As an example, we’ll build a set of functions that might be useful during debugging. We’ll name our debugging functions debug_rep, each of which will return a string representation of a given object. We’ll start by writing the most general version of this function as a template that takes a reference to a const object:

// print any type we don't otherwise handle
template <typename T> string debug_rep(const T &t)
{
    ostringstream ret; // see § 8.3 (p. 321)
    ret << t; // uses T's output operator to print a representation of t
    return ret.str(); // return a copy of the string to which ret is bound
}

Next, we’ll define a version of debug_rep to print pointers:

// print pointers as their pointer value, followed by the object to which the pointer points
// NB: this function will not work properly with char*; see § 16.3 (p. 698)
template <typename T> string debug_rep(T *p)
{
    ostringstream ret;
    ret << "pointer: " << p;         // print the pointer's own value
    if (p)
        ret << " " << debug_rep(*p); // print the value to which p points
    else
        ret << " null pointer";      // or indicate that the p is null
    return ret.str(); // return a copy of the string to which ret is bound
}

As another example, consider the following call:

const string *sp = &s;
cout << debug_rep(sp) << endl;

Here both templates are viable and both provide an exact match:

• debug_rep(const string* &), the instantiation of the first version of the template with T bound to const string*

• debug_rep(const string*), the instantiation of the second version of the template with T bound to const string

In this case, normal function matching can’t distinguish between these two calls. We might expect this call to be ambiguous. However, due to the special rule for overloaded function templates, this call resolves to debug_rep(T*), which is the more specialized template.

The reason for this rule is that without it, there would be no way to call the pointer version of debug_rep on a pointer to const. The problem is that the template debug_rep(const T&) can be called on essentially any type, including pointer types. That template is more general than debug_rep(T*), which can be called only on pointer types. Without this rule, calls that passed pointers to const would always be ambiguous.

Nontemplate and Template Overloads

For our next example, we’ll define an ordinary nontemplate version of debug_rep to print strings inside double quotes:

// print strings inside double quotes
string debug_rep(const string &s)
{
    return '"' + s + '"';
}

Now, when we call debug_rep on a string,

string s("hi");
cout << debug_rep(s) << endl;

there are two equally good viable functions:

• debug_rep<string>(const string&), the first template with T bound to string

• debug_rep(const string&), the ordinary, nontemplate function

Overloaded Templates and Conversions

There’s one case we haven’t covered so far: pointers to C-style character strings and string literals. Now that we have a version of debug_rep that takes a string, we might expect that a call that passes character strings would match that version. However, consider this call:

cout << debug_rep("hi world!") << endl; // calls debug_rep(T*)

Here all three of the debug_rep functions are viable:

• debug_rep(const T&), with T bound to char[10]

• debug_rep(T*), with T bound to const char

• debug_rep(const string&), which requires a conversion from const char* to string

template <typename T> string debug_rep(const T &t);
template <typename T> string debug_rep(T *p);
// the following declaration must be in scope
// for the definition of debug_rep(char*) to do the right thing
string debug_rep(const string &);
string debug_rep(char *p)
{
    // if the declaration for the version that takes a const string& is not in scope
    // the return will call debug_rep(const T&) with T instantiated to string
    return debug_rep(string(p));
}

Ordinarily, if we use a function that we forgot to declare, our code won’t compile. Not so with functions that overload a template function. If the compiler can instantiate the call from the template, then the missing declaration won’t matter. In this example, if we forget to declare the version of debug_rep that takes a string, the compiler will silently instantiate the template version that takes a const T&.