Document

Template Classes

Templates Review

We've seen templates used with functions to save us time and typing. Templates are used to make something work with many different data types without us having to overload anything.

We'll first see an example without templates.

class A{
  private:
    int m_a{};

  public:
    A(int a) : m_a{a} 
    {}

    int getA() const { return m_a; }
};

// Usage
A a{ 23.23 };
std::cout << a.getA(); // 23

As you see, we used a double when the constructor takes an int. Doubles are integral types, so this works (some compilers may throw "narrowing conversion" errors, if not, apply the -Wnarrowing flag).

To fix this, we can just add a double-type member, constructor that takes a double, and accessor that returns a double.

class A{
  private:
    int m_a{};
    double m_b{};

  public:
    A(int a) : m_a{ a } 
    {}
    A(double b) : m_b{ b } 
    {}

    int getA() const { return m_a; }
    double getB() const { return m_b; }
};

// Usage
A b{ 23.23 };
std::cout << b.getB(); // 23.23

Yes we fixed it! But there's a lot of unused code just sitting there. m_a, A(int a), and int getA() are unused if we use a double-type, and same for using an int-type (double-type stuff aren't used).

So that's why we use templates. Unused code = trash!

Let's refactor the above.

/*
  REVIEW
  typename identifiers
  conventionally start with
  'T' and the next is 'U'
  then 'V' etc.
  'S' is used for size_t.
 */

/*
  All we really do is change
  the types to the appropriate 
  template identifier. 
  We can have more than 
  one "typename" so be 
  cautious when changing.

  For this example, I changed
  all the "int" to 'T' and
  removed everything that 
  dealt with "double."
 */
template<typename T>
class A{
  private:
    T m_a{};

  public:
    A(T a) : m_a{ a } 
    {}

    T getA() const { return m_a; }
};

// Usage
A<int> a_int{ 23 };
a_int.getA(); // 23

A<double> a_double{ 23.23 };
a_double.getA(); // 23.23

A<char> a_char{ 97 };
a_char.getA(); // 'a'

/*
  Using direct initialization () 
  to overcome narrowing conversion
  error.

  We specified int so
  the class gets converted to
  int-type during compilation
 */
A<int> a_idouble(23.23);
a_idouble.getA(); // 23



/*
  We can also use
  objects.

  Use direct initialization
  for objects if you get errors.

  requires <string>
 */
A<std::string> a_string("HELLO " "WORLD\n");
a_string.getA(); // HELLO WORLD

We can also omit the <type> and let the compiler guess, but it's not recommended to do so. For one, using the chevrons tells anyone reading the code that that class is a template class, and sometimes the compiler may choose whatever is most optimal, not what we truly wanted (compiler always goes for "double" when using floating point numbers, but what if we don't want all that extra space used by a double).

And there is also one issue in the code snippet, can you spot it?

The issue is that we used a std::string with a class that doesn't modify a string, so we're using heavy objects when we shouldn't (string_view is better when not modifying strings). That is the major problem with templates; we don't really know what the programmer will use it for.

You can also change behavior based on the typename for functions (known as function template specialization) and templates (known as class template specialization).

/*
  Function Specialization
 */
template<typename T>
class A{
  private:
    T m_a{};

  public:
    A(T a) : m_a{ a } 
    {}

    void say() const {
      std::cout << "int\n";
    }
};

/*
  Defined outside the class.
  leave the parameter-list empty
  and specify the type.

  The parameter-list doesn't have 
  to be empty (we'll see parameter-lists
  in more detail in the next section)
  depending on your program of course,
  but this is enough to let the compiler 
  know this is a "templated type."
 */
template<>
void A<double>::say() const {
  std::cout << "This is";
  std::cout << " a double\n";
}

// Usage
A<int> a_int{3};
a_int.say(); // int

A<double> a_double{3.14};
a_double.say(); // This is a double






/*
  Class Specialization
 */
#include <string_view>

template<>
class A<std::string> {
  private:
    std::string_view m_a{};

  public:
    A(T a) : m_a{ a } 
    {}

    std::string_view getA() const { return m_a; }
}

// Exact same usage; nothing special needed

Useful for dynamic memory and heavy objects.

Another issue with template classes is that they must be defined in the same file. This is because the preprocessor first includes the headers (remember, preprocessors don't know anything about C++), the headers will all have 'T' and no type, so all the source files that include a template class will have their types, but the source file for the template class doesn't exactly know what types we used before so it won't instantiate those template functions used in other source files. It's a "compile order" issue.

// template.h
template<typename T>
class A{
  private:
    T m_a{};

  public:
    A(T a) : m_a{ a } 
    {}

    T getA() const;
};

// template.cpp
#include "template.h"
#pragma once

/*
  When we compile this file,
  the compiler knows this
  is a template, but doesn't
  know what to replace 'T'
  with.

  It should NOT just make
  one for every existing type!

  That's where the error comes
  in.
 */
template<typename T>
T A<T>::getA() const {
  return m_a;
}

// main.cpp
/*
  Preprocessor includes
  everything from template.h
  knowing nothing about types
  or templates
 */
#include "template.h"

int main() {
  /*
    Compiler knows you 
    want an int,
   */
  A<int> a{ 23 };

  /*
    but never made an 
    int version when it 
    compiled template.cpp
    so this doesn't exist
   */
  a.getA(); // ERROR unresolved external symbol

  return 0;
}

The general conventional solution is to add the definitons in the header file. You can also rename the extension of the template's source file from cpp to inl then include that inl file at the very bottom of the template's header file (don't #include cpp files). Finally, there is the "three-file" approach: same as using a .cpp and .h file, but we use a third cpp file that includes both files and contains all the instantiated template classes you'll need.

/*
  three-file approach

  conventionally named "templates.cpp"
 */
// templates.cpp
/*
  Include ALL templates
  you'll be using
 */
#include "templateA.h"
#include "templateA.cpp" // Only time this is okay
#include "templateB.h"
#include "templateB.cpp" // Only time this is okay

/*
  Explicitally instantiate 
  what you'll be using
 */
template class templateA<int>;
template class templateA<double>;
template class templateB<char>;
template class templateB<unsigned>;
template class templateB<float>;

This method allows for the compiler to prematurely instantiate the template classes, therefore bringing them to existence earlier than expected. Now that they are resolved, there won't be any issues.

It's pretty efficient, but may be annoying and require extra typing and management. Your choice, these solutions don't really have negative effects code and community wise, as far as I know.

Template Parameter Lists

Type Template Parameters

"typename" and what we've seen so far is known as a type template parameter.

We can also use "class" in place of "typename," but it's recommended to use "typename" (because using "class" is the old way) so I won't be using "class."

Non-type Template Parameters

In the previous section (above), I mentioned 'S' is for std::size_t, that implied we aren't restricted to using "typename" in our parameter-lists.

We can use

>lvalue reference (to object or function)

>integral types

>pointers (to object or function)

>pointers to members (member object or function)

>enumerations

>nullptr type (std::nullptr_t) (C++11)

>floating-point type (C++20)

>literal class type (has restrictions) (C++20)

>placeholder such as auto (C++20)

Using them is the same as typename, but if you want to use more than one, use the comma operator.

You can also set default parameters just like functions (even with type template parameters).

template<typename T=int, std::size_t S=21>
class A{
  private:
    T m_value{};
    std::size_t m_size {S};

  public:
    /*
      'S' is NOT a type,
      it's a value
     */
    std::size_t getSize() const {
      return m_size;
    }
};

A<int, 5> a_int;
a.getSize(); // 5

/*
  Displaying default
  parameters
 */
A<double> a_double;
a.getSize(); // 21

Template Template Parameters (C++17)

These are just templates inside template parameter-lists.

Can have default values

template<typename T, typename U, template<typename> typename V=std::array>
class TemplateTemplate {
  private:
    V<T> key;
    V<U> value;
};

These can have their own parameter lists as well!

Parameter Packs (C++11)

It's just an argument pack but for template arguments; and like argument packs, these must be the last parameter in the list. We use the ellipsis operator.

It accepts non-types, types, or template templates.

They are complex feature-wise and require a lot to work and can be their own chapter (couldn't even come up with a non-overly complicated example), so if you're interested in more, look up "parameter pack cppreference" and research "std::forward".

Or if someone can show a clean example that'd be nice too!

Constraints and Concepts (C++20)

Constraints specify requirements on template arguments; useful for overloads and specialization.

Constraints are evaluated at compile-time.

These use the <concepts> header for evaluation. I believe all of its functionality requires C++20. I recommend you look up the concepts library on the cppreference website to see all the available concepts and what they mean.

This is also a huge topic with many other sub-topics so I'll go over it briefly.

This is also overly-complicated but think of it as "our template needs to have these requirements or else throw an error."

Concepts

A concept is a named set of requirements (like an identifier). It is convention to capitalize concepts.

The requirements evaluate to either true or false (they can be concepts from the concepts library, expressions, or even functions).

The syntax is concept [concept-name] = [constraint-expression]

#include <concepts>

template<typename T>
concept FloatingPoint = std::floating_point<T>

All that did is create a named constant that requires the typename 'T' to be floating-point type. If it's not, we will get an error.

ERROR

You do not put any template class or function under a concept and reuse the 'T', the 'T' only belongs to the concept!

Constraints

Constraints are the actual usage of the concepts. They appear within requires-expressions which we'll see.

These should be used within the same template<typename T> as your function or class.

#include <concepts>

template<typename T>
concept FloatingPoint = std::floating_point<T>

/*
  This typename T has
  nothing to do with the
  above.
 */
template<typename T>
requires FloatingPoint<T>
class A {
  private:
    T m_a{};
};

// Usage
A<bool> a; // ERROR constraints not satisfied

/*
  Changing bool to
  float will satisfy the
  constraints.
 */

Constraints have three types

Conjunctions

If ALL the constraints are satisfied, the concept evaluates to true. This uses the && operator.

Evaluated left-to-right and are short-circuted (if one is false, nothing else gets evaluated and the entire clause is false).

Disjunctions

If ANY constraint is satisfied, the entire clause is true. Uses the || operator.

Evaluated left-to-right and are short-circuted (if one is false, nothing else gets evaluated and the entire clause is false).

Atomic

This one was a bit harder to understand (wording is all over the place) so I could be wrong.

I understood that atomic constraints just use boolean primary expressions rather than the logical AND and OR. If that expression evaluates to true, then the constraint is satisfied.

Example of all three (requires C++20).

/*
  Conjunction
 */
#include <concepts>

template<typename T>
concept Integral = std::is_integral<T>::value;
template<typename T>
concept SignedInt = std::is_signed<T>::value;

/*
  You can also do this

  concept SignedInt = Integral<T> && std::is_signed<T>::value;

  but change requires to
  requires SignedInt
 */

template<typename T>
requires Integral<T> && SignedInt<T>
class A {
  private:
    T m_a{};
};

// Usage
A<unsigned int> a; // ERROR constraints not satisfied



/*
  Disjunction
 */
#include <concepts>

template<typename T>
concept Integral = std::is_integral<T>::value;
template<typename T>
concept SignedInt = std::is_signed<T>::value;

/*
  You can also do this

  concept SignedInt = Integral<T> || std::is_signed<T>::value;

  but change requires to
  requires SignedInt
 */

template<typename T>
requires Integral<T> || SignedInt<T>
class A {
  private:
    T m_a{};
};

// Usage
A<unsigned int> a; // OK unsigned int is still integral



/*
  Atomic
 */
#include <concepts>
#include <iostream>

template<typename T>
constexpr bool is_true = 5 < 6;

template<typename T>
constexpr bool is_false = 5 > 6;

// Disjunction
template<typename T>
concept Ok = is_true<T> || is_false<T>;

template<Ok T>
void f1(T t) {
  std::cout << t;
}

// Usage
f1(0); // 0
f1(1); // 1
f1(2); // 2

Play with the less-than and greater-than sign to see the errors flow in!

There are more tricks to constraints, I only put enough to understand at least what they do and how to use them. Look up "constraints cppreference" for more. I use that website to write these tutorials (and I look elsewhere (nowhere specific, but prioritize S.O) if something doesn't make sense).

C++ Tutorial | 13.7 Classes - Template Classes