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.

animal 1821737 1280

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 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 the 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 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 case of the function overloading the compiler prefers the function overloading to the function template when the function overloading is a perfect fit.

functionTemplateSpecialisationBut, 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 don'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 in line (1) the primary template getTypeName. Line 2 is an overload for pointers and line 3 a full specialisation for an int pointer. In 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.



Thanks a lot to my Patreon Supporters: Matt Braun, Roman Postanciuc, Tobias Zindl, Marko, G Prvulovic, Reinhold Dröge, Abernitzke, Frank Grimm, Sakib, Broeserl, António Pina, Sergey Agafyin, Андрей Бурмистров, Jake, GS, Lawton Shoemake, Animus24, Jozo Leko, John Breland, espkk, Wolfgang Gärtner,  Louis St-Amour, Stephan Roslen, Venkat Nandam, Jose Francisco, Douglas Tinkham, Kuchlong Kuchlong, Avi Kohn, Robert Blanch, Truels Wissneth, Kris Kafka, Mario Luoni, Neil Wang, Friedrich Huber, lennonli, Pramod Tikare Muralidhara, Peter Ware, Tobi Heideman, Daniel Hufschläger, Red Trip, Alexander Schwarz, and Tornike Porchxidze.


Thanks in particular to Jon Hess, Lakshman, Christian Wittenhorst, Sherhy Pyton, Dendi Suhubdy, Sudhakar Belagurusamy, and Richard Sargeant.

My special thanks to Embarcadero CBUIDER STUDIO FINAL ICONS 1024 Small



I'm happy to give online-seminars or face-to-face seminars world-wide. Please call me if you have any questions.

Bookable (Online)



Standard Seminars 

Here is a compilation of my standard seminars. These seminars are only meant to give you a first orientation.


Contact Me

Modernes C++,


Tags: templates

My Newest E-Books

Course: Modern C++ Concurrency in Practice

Course: C++ Standard Library including C++14 & C++17

Course: Embedded Programming with Modern C++

Course: Generic Programming (Templates)

Course: C++ Fundamentals for Professionals

Subscribe to the newsletter (+ pdf bundle)

Blog archive

Source Code


Today 2888

Yesterday 7909

Week 10797

Month 85848

All 6106912

Currently are 220 guests and no members online

Kubik-Rubik Joomla! Extensions

Latest comments