Templates and Header Files

Previously, we’ve seen how we can split a class and its members into separate declarations and definitions:

1// Resource.h
2#pragma once
3#include <iostream>
4
5class Resource {
6 public:
7  int Value;
8  
9  // Declaration
10  void Log();
11};
12
13// Definition
14void Resource::Log() {
15  std::cout << "Resource Value: " << Value;
16}

This additionally allows us to split these components across two files - a header file and an implementation file - which can be helpful for project organisation and keeping compile times fast.

In this lesson, we’ll see how to use this technique when we’re creating a class template rather than a basic class. We’ll encounter a linker problem that can crop up in this context, and our options for working around it.

Separating Class Template Implementations

Let’s say we have the following template class, which declares a Log() function, but hasn’t implemented it:

1// Resource.h
2#pragma once
3
4template <typename T>
5class Resource {
6 public:
7  T Value;
8  void Log();
9};

Implementing a member function of a template class broadly follows the same idea as implementing a member function of a regular class. We just have some additional template-based syntax added above the function and to its signature:

1// Resource.h
2#pragma once
3#include <iostream>
4
Resource Class Template|Show
5class Resource {/*...*/};
12
13template <typename T>
14void Resource<T>::Log() {
15  std::cout << "Resource Value: " << Value;
16}

The need for the additional syntax here is because class templates can be used to create any number of classes, and we can provide different implementations of their member functions depending on the specific template arguments. We’ll see examples of this later in the chapter.

Instantiating our template and then creating an object of that type confirms we have the expected behaviour:

1// main.cpp
2#include "Resource.h"
3
4int main() {
5  Resource<int> Object{42};
6  Object.Log();
7}

1Resource Value: 42

A slightly more complex example, where our class template has multiple parameters, might look like this:

1// Pair.h
2#pragma once
3
4template <typename T1, typename T2>
5class Pair {
6 public:
7  Pair(T1 first, T2 second)
8    : mFirst(first), mSecond{second} {}
9
10  // Declarations
11  T1 GetFirst() const;
12  T2 GetSecond() const;
13
14 private:
15  T1 mFirst;
16  T2 mSecond;
17};
18
19// Definitions
20template <typename T1, typename T2>
21T1 Pair<T1, T2>::GetFirst() const {
22  return mFirst;
23}
24
25template <typename T1, typename T2>
26T2 Pair<T1, T2>::GetSecond() const {
27  return mSecond;
28}

One of the main reasons we separate declaration and definition in this way is that it allows our definition to be in a different file entirely. For example, we’d often have all our declarations in a header file whilst definitions are in a separate implementation file.

If we try to do this with templates, we can run into some problems.

Moving Implementations to a Different File

Let’s split our Pair class template across a header file and implementation file, in much the same way we’ve done with regular classes in the past:

1// Pair.h
2#pragma once
3
4template <typename T1, typename T2>
5class Pair {
6 public:
7  Pair(T1 first, T2 second)
8    : mFirst(first), mSecond{second} {}
9
10  // Declarations
11  T1 GetFirst() const;
12  T2 GetSecond() const;
13
14 private:
15  T1 mFirst;
16  T2 mSecond;
17};

1// Pair.cpp
2#include "Pair.h"
3
4// Definitions
5template <typename T1, typename T2>
6T1 Pair<T1, T2>::GetFirst() const {
7  return mFirst;
8}
9
10template <typename T1, typename T2>
11T2 Pair<T1, T2>::GetSecond() const {
12  return mSecond;
13}

In isolation, this will compile. However, once we try to use our member functions in some other source file, we’ll encounter linker errors:

1// main.cpp
2#include <iostream>
3#include "Pair.h"
4
5int main() {
6  Pair<int, bool> MyPair{42, true};
7
8  std::cout << "First: " <<  MyPair.GetFirst();
9}

1error LNK2019: unresolved external symbol Pair<int,bool>::GetFirst() referenced in function main
2fatal error LNK1120: 1 unresolved externals

Because templates are instantiated at the compilation step (i.e., before linking), our program cannot compile in this form. Our main.cpp source file is trying to create a class from our Pair template but it doesn’t have the implementation, so it can’t.

Our Pair.cpp file has the implementation so it could create a Pair<int, bool>, but it doesn’t know it needs to. The invocation of the template with that particular set of arguments is in another source file.

Our solutions to solve this problem therefore fall into two categories:

1. Provide the source files that use the template access to its implementation
2. Give the template’s implementation the required arguments

Option 1: Provide the Implementation

Variations of this option involve simply providing the implementation within the header that is included by files that use our template. For example, we can just provide implementations at the same time we declare the methods:

1// Pair.h
2#pragma once
3
4template <typename T1, typename T2>
5class Pair {
6 public:
7  Pair(T1 first, T2 second)
8    : mFirst(first), mSecond{second} {}
9
10  T1 GetFirst() const {
11    return mFirst;
12  };
13  
14  T2 GetSecond() const {
15    return mSecond;
16  };
17
18 private:
19  T1 mFirst;
20  T2 mSecond;
21};

We could alternatively provide declarations separately, but within the same header file:

1// Pair.h
2#pragma once
3
Pair Class Template|Show
4class Pair {/*...*/};
18
19template <typename T1, typename T2>
20T1 Pair<T1, T2>::GetFirst() const {
21  return mFirst;
22}
23
24template <typename T1, typename T2>
25T2 Pair<T1, T2>::GetSecond() const {
26  return mSecond;
27}

A variation of this idea involves us providing declarations in a different file, but then including that file at the bottom of our header. By convention, we give files that provide implementations for templates .ipp or .tpp extensions:

1// Pair.h
2#pragma once
3
Pair Class Template|Show
4class Pair {/*...*/};
18
19#include "Pair.ipp"

1// Pair.ipp
2#pragma once
3#include "Pair.h"
4
Class Member Definitions (Unchanged)|Show

Option 2: Provide the Arguments

If we know what instances of our template are going to be required elsewhere in our code, we can proactively create those instances within the files that implement our template.

The syntax looks like the following:

1// Pair.cpp
2#include "Pair.h"
3
Class Member Definitions (Unchanged)|Show
13
14template class Pair<int, bool>;
15template class Pair<bool, bool>;
16template class Pair<float, int>;

After compiling this code, the Pair<int, bool>, Pair<bool, bool> and Pair<float, int> types will be created, and available to other source files through the linker. If we find ourselves needing a different type, we can return to this file and add another instantiation.

In practice, providing arguments in this way is less common than simply providing the full implementation of our template in the header file. It is particularly impractical if we’re writing library code to be used by other developers, as we have no way of knowing what types their project is going to be using with our template.

Summary

In this lesson, we've expanded on class templates, particularly focusing on how to separate their declarations from definitions. The key takeaways include:

• Much like regular classes, class templates can be split into declarations and definitions
• However, separating the declaration and definition of a class template into separate files can lead to linker errors due to the way templates are instantiated at compile time.
• A common solution to this problem is to provide the template definitions within the header file directly, or through an included .ipp or .tpp file to ensure the compiler has access to them when needed.
• An alternative, less commonly used method involves explicitly instantiating templates in a source file for each required type combination, which helps in cases where the template types are known in advance, and limited in quantity.

Next Lesson

Compile-Time Evaluation

Learn how to implement functionality at compile-time using constexpr and consteval

ContinueView Course