C++ Core Guidelines: Surprise included with the Specialisation of Function Templates

Today, I finish the C++ core guidelines rules to templates with a big surprise for many C++ developers. I write about the specialisation of function templates.

Let's start simple. Here is a template specialisation from a bird-eyes perspective.

Template Specialisation

Templates define the behaviour of families of classes and functions. Often it is necessary that special types or non-types may be treated special. To support this use case, you fully specialise in templates. Class templates can even be partially specialised.

Here is a code snippet to get a general idea.

template <typename T, int Line, int Column>     // (1)
class Matrix;

template <typename T>                           // (2)
class Matrix<T, 3, 3>{};

template <>                                     // (3)
class Matrix<int, 3, 3>{};

Line 1 is the primary or general templates. This template must be declared at least and has to be declared before the partially or fully specialised templates. Line 2 follows with the partial specialisation. Line 3 is the full specialisation. 

To better understand partially and fully specialisation, I want to present a visual explanation. Think about an n-dimensional space of template parameters. In the primary template (line 1) you can choose an arbitrary type, and two arbitrary int's. In the case of the partial specialisation in line 2, you can only choose the type. This means the 3-dimensional space is reduced to a line. Fully specialisation means that you have one point in a 3-dimensional space. 

What is happening when you invoke the templates?

Matrix<int, 3, 3> m1;          // class Matrix<int, 3, 3>

Matrix<double, 3, 3> m2;       // class Matrix<T, 3, 3> 

Matrix<std::string, 4, 3> m3;  // class Matrix<T, Line, Column> => ERROR

m1 uses the full specialisation, m2 uses the partial specialisation and m3 the primary template which causes an error because the definition is missing.

Here are three rules which the compiler uses to get the right specialisation:

1. The compiler finds only one specialisation. The compiler uses specialisation.
2. The compiler finds more than one specialisation. The compiler uses the most specialised one. If this process ends in more than one specialisation, the compiler throws an error.
3. The compiler finds no specialisation. It uses the primary specialisation.

Okay, I have to explain what A is a more specialised template than B means. Here is the informal definition of cppreference.com: "A accepts a subset of the types that B accepts".

After the first overview, I can dig a little bit deeper into function templates.

Specialisation and Overloading of Function Templates

Function templates make the job of template specialisation easier but also more difficult at the same time.

• Easier, because the function template only supports full specialisation.
• More difficult, because function overloading comes into play.

From the design perspective, you can specialise a function template with template specialisation or overloading.

// functionTemplateSpecialisation.cpp

#include <iostream>
#include <string>

template <typename T>             // (1)
std::string getTypeName(T){
    return "unknown type";
}

template <>                       // (2)
std::string getTypeName<int>(int){
    return "int";
}

std::string getTypeName(double){  // (3)
    return "double";
}

int main(){
    
    std::cout << std::endl;
    
    std::cout << "getTypeName(true): " << getTypeName(true) << std::endl;
    std::cout << "getTypeName(4711): " << getTypeName(4711) << std::endl;
    std::cout << "getTypeName(3.14): " << getTypeName(3.14) << std::endl;
    
    std::cout << std::endl;
    
}

Line 1 has the primary template, line 2 the full specialisation for int, and line 3 the overload for double. Because I'm not interested in the values for the function or function templates, I skipped them: std::string getTypeName(double) for example. The usage of the various functions is quite comfortable. The compiler deduces the types and the correct function or function template is invoked. In the case of the function overloading the compiler prefers the function overloading to the function template when the function overloading is a perfect fit.

But, where is the big surprise, I mentioned in the title of my post? Here it is.

T.144: Don’t specialize function templates

The reason for the rules is quite short: function template specialisation doesn't participate in overloading. Let's see what that means. My program is based on the program snippet from Demiov/Abrahams.

// dimovAbrahams.cpp

#include <iostream>
#include <string>

// getTypeName

template<typename T>            // (1) primary template
std::string getTypeName(T){
    return "unknown";
}

template<typename T>            // (2) primary template that overloads (1)
std::string getTypeName(T*){
    return "pointer";
}

template<>                      // (3) explicit specialization of (2)
std::string getTypeName(int*){
    return "int pointer";
}

// getTypeName2

template<typename T>            // (4) primary template
std::string getTypeName2(T){
    return "unknown";
}

template<>                      // (5) explicit specialization of (4)
std::string getTypeName2(int*){
    return "int pointer";
}

template<typename T>            // (6) primary template that overloads (4)
std::string getTypeName2(T*){
    return "pointer";
}

int main(){
    
    std::cout << std::endl;
    
    int *p;
    
    std::cout << "getTypeName(p): " << getTypeName(p) << std::endl;   
    std::cout << "getTypeName2(p): " << getTypeName2(p) << std::endl; 
    
    std::cout << std::endl;
    
}

Admittedly, the code looks quite boring but bear with me. I defined inline (1) the primary template getTypeName. Line 2 is an overload for pointers and line 3 a full specialisation for an int pointer. In the case of getTypeName2, I made a small variation. I put the explicit specialisation (line 5) before the overload for pointers (line 6).

This reordering has surprising consequences.

In the first case, the full specialisation for the int pointer is called and in the second case, the overload of pointers. What?  The reason for this non-intuitive behaviour is that overload resolution ignores function template specialisation. Overload resolution operates on primary templates and functions. In both cases, overload resolutions found both primary templates. In the first case (getTypeName), the pointer variant is the better fit and, therefore, the explicit specialisation for the int pointer was choosen. In the second variant (getTypeName2), also the pointer variant was choosen but the full specialisation belongs to the primary template (line 4). Consequently, it was ignored.

What's next?

While proofreading this lines I had an idea. Templates are good for more surprises. Therefore, I make a short detour from the core guidelines and I will present you a few of them. My hope is that you will remember this lines if you encounter them. 

The future of C++ speaks templates. Therefore, it's good to know more about their language.