why C++ template function Implementations should be in the header?

In C++, templates are a powerful feature that allows you to create functions and classes that operate with any data type. However, they come with specific rules regarding how and where to define their implementations.

Why Template Implementations Should Be in the Header

1. Compile-Time Instantiation:

   • Templates are instantiated at compile time. This means that when you use a template (like NaryTree<T>) with a specific type (like NaryTree<DigitalModelNodeData>), the compiler needs to see the full definition of all the methods of the template class.
   • If the implementation is in a separate .cpp file, the compiler won't be able to instantiate that template for the specific type unless it can see the implementation during compilation. This often leads to linker errors.

2. Separation of Declaration and Definition:

   • In traditional function and class definitions, you can separate declarations (in headers) from implementations (in .cpp files) because the compiler does not need to know the actual implementation until the function is called.
   • For templates, however, since the actual type is not known until it is instantiated, the compiler must have both the declaration and the implementation visible in the same file.

3. Example of Linker Issues:

   • If you declare a template method in a header file but define it in a .cpp file, any translation unit that includes the header but does not link against the .cpp will fail to find the definition.
   • For instance, if you have static std::shared_ptr<NaryTree<T>>::BuildDigitalModelTreeFromDFSJson(QTreeView&, T, const QString&) defined in a .cpp but called from another .cpp, it results in a linker error because the definition is not found.

4. Best Practices:

   • As a best practice, template class and method definitions are typically placed in the header file itself. This convention ensures that all relevant code for instantiation is in a single file, making template usage simpler and reducing potential compiler and linker errors.

Example Clarification

Here’s a simple example to illustrate:

NaryTree.h:

cpp

#pragma once

#include <memory>
#include <QVector>
#include <QString>
#include <QTreeView>

template <typename T>
class NaryTree {
public:
    T nodeData;
    QVector<std::shared_ptr<NaryTree<T>>> children;

    NaryTree(const T& val) : nodeData(val) {}

    static std::shared_ptr<NaryTree<T>> BuildDigitalModelTreeFromDFSJson(QTreeView& oneTreeView, T tmpData, const QString& jsonFilePath) {
        // Implementation directly in the header
        return std::make_shared<NaryTree<T>>(tmpData);
    }
};

cpp

In this case, if you tried to define BuildDigitalModelTreeFromDFSJson in a separate .cpp file, you would end up with linker errors when trying to use that method, as the specific instantiation cannot be resolved.

Summary

To avoid these issues, place the full definition of template classes and methods in the header files. That way, when the template is instantiated with a specific type, the compiler has access to everything it needs to generate the correct code. This is why you often find template implementations in headers rather than in separate .cpp files.