A template declaration looks somewhat like a function declaration. It opens with the template keyword, followed by an identifier, a parameter list, and then a pair of braces for the body. The body may contain any valid D declaration except module declarations, as the following example demonstrates:

template MyTemplate(T) {
  T val;
  void printVal() {
    import std.stdio : writeln;
    writeln("The type is ", typeid(T));
    writeln("The value is ", val);
  }
}

The first line declares a template named MyTemplate that takes one parameter, T. This isn't the same as a function parameter. There are different kinds of template parameters, but in this case T is intended to refer to a type. It can be any type: int, float, a user-defined type, and so on. Most templates are parameterized.

After the template parameter list, multiple declarations can appear inside a pair of braces. This example declares a variable of type T named val and a function called printVal that uses val. If compiled at this point, neither val nor printVal would be present in the binary. For that to happen, the template must be instantiated at least once.

When a template is instantiated, any declarations inside it are compiled, with the given template arguments replacing its parameters. The following snippet instantiates two instances of MyTemplate using two different types and two different approaches:

MyTemplate!(int).val = 20;
MyTemplate!int.printVal();
alias mtf = MyTemplate!float;
mtf.printVal();

Taken together, the two snippets yield the following output:

The type is int
The value is 20
The type is float
The value is nan

The first line of main instantiates MyTemplate with int. This is accomplished by putting the template instantiation operator, !, after the template name, followed by the type argument list. In the same line, val is set to 20. MyTemplate!(int) acts as a namespace for each declaration in the body. Both members are accessed with the dot operator.

The second line demonstrates two points. First, the parentheses around the type parameter have been dropped. When a template declaration takes only one parameter, the parentheses are usually optional in the instantiation, though sometimes they are required; for example, the brackets in an array type such as int[] make the parentheses mandatory. Second, when printVal is called, it shows that the type of T is int and its value is 20. This verifies that it refers to the same instance of the template that was instantiated in the first line, where val is set to 20. If this were part of a larger program, then any usage of MyTemplate!int, in any module, is referring to the same instance of val and the same implementation of printVal.

The third line sets up for a different approach to instantiation by creating an alias. This both instantiates the template and makes mtf a synonym for MyTemplate!float. The very next line calls printVal through the alias. This prints the type as float and the value as nan, since val was never set for the float version of MyTemplate.

Template instantiation happens in the same scope as the declaration, not that of the instantiation. Consider this module, declscope, with its addTwo function:

module declscope;
int addTwo(int x) {
  return x + 2;
}
template NumTemplate() {
  enum constant = addTwo(10);
}

It should be obvious that addTwo(10) is calling the function declared here, but what happens when NumTemplate is instantiated in the following intscope module, which has its own addTwo?:

module intscope;
int addTwo(int x) {
  // We lied, we're adding 20
  return x + 20;
}
void main() {
  import declscope, std.stdio;
  writeln(NumTemplate!().constant);
}

It's easy to believe that the body of the template is being pasted somewhere around the instantiation, but that isn't the case. Compiling this and running it results in 12, not 20, meaning declscope.addTwo is being called inside the template. Remember, a template is only instantiated once for each set of arguments and the same instantiation can be repeated in multiple modules throughout a program. If each instantiation were scoped locally, the template would no longer work as expected.

It's also worth noting that the template in the previous example takes no parameters. When it's instantiated, the instantiation operator and parentheses are required and the parentheses have to be empty. It may appear to be pointless to have a typeless template; after all, supporting multiple types with a single block of code is a major benefit of generic programming. We'll see later that typeless templates can be put to good use.

If one instance of val per instantiation is not sufficient, the template body can be rewritten so that val and printVal are wrapped inside a struct or class:

template MyTemplate(T) {
  struct ValWrapper {
    T val;
    void printVal() {
      import std.stdio : writeln;
      writeln("The type is ", typeid(T));
      writeln("The value is ", val);
    }
  }
}
void main() {
  MyTemplate!int.ValWrapper vw1;
  MyTemplate!int.ValWrapper vw2;
  vw1.val = 20;
  vw2.val = 30;
  vw1.printVal();
  vw2.printVal();
}

Although it looks like MyTemplate is instantiated twice here, that's not what's happening. The template is still instantiated only once. Instead, two instances of MyTemplate!int.ValWrapper are declared. The instantiation effectively creates a new ValWrapper declaration as if the following had been explicitly declared:

struct ValWrapper {
  int val;
  void printVal() {...}
}

If the template is instantiated with a different type, it creates a new declaration of ValWrapper. If it's never instantiated, then ValWrapper never exists as a type. Although multiple declarations can go inside a template body, it's quite common to declare a single struct, class, function, or even a manifest constant. In that case, we can do away with the tediousness of the dot operator and take some shortcuts.

In 1975, Fleetwood Mac released an album titled Fleetwood Mac. Six years later, it was in reference to that album that the 10-year-old me first made the connection between the words eponymous and self-titled while listening to the radio. In D, self-titled templates are a thing. Let's rewrite MyTemplate once more, this time making it eponymous:

template ValWrapper(T) {
  struct ValWrapper {
    T val;
    void printVal() {
      writeln("The type is ", typeid(T));
      writeln("The value is ", val);
    }
  }
}

Now that the template and struct declarations have the same name, the dot operator can be dropped from instantiations and instances of ValWrapper declared directly:

ValWrapper!int vw;

That's much nicer syntax, isn't it? The language also allows for a shortcut in the template declaration. By simply adding the parameter list to the struct declaration, the template block is eliminated completely. The declaration then becomes:

struct ValWrapper(T) {
  T val;
  void printVal() {
    writeln("The type is ", typeid(T));
    writeln("The value is ", val);
  }
}

This is a struct template. The instantiation syntax is the same as it was for the first version of the eponymous template. If it is expected to be used often, alias declarations can be added at module scope to help make the instantiation syntax even cleaner:

alias ValWrapperI = ValWrapper!int;
alias ValWrapperF = ValWrapper!float;

A class template is similar:

class ValClass(T) {
private:
  T _val;
public:
  this(T val) {
    _val = val;
  }
  T val() @property {
    return _val;
  }
}

It can be instantiated like this:

auto vc = new ValClass!int(10);

When multiple type parameters are involved, the parentheses in the instantiation are no longer optional and two pairs are needed when invoking the constructor. The following partial implementation of a wrapper for associative arrays demonstrates:

class HashMap(K,V) {
  V[K] _map;
  string _name;
  this(string name) {
    _name = name;
  }
}

When instantiating one of these, it's going to look a bit more cluttered:

auto map = new HashMap!(string, int)("NameMap");

Always remember that the first pair of parentheses contains the template arguments and the second the constructor arguments.

It's also possible to inherit from a template class or interface:

interface Transformation(T) {
  T transform(T t);
}
class Double(T) : Transformation!T {
  T transform(T t) {
    return t * 2;
  }
}

When an instance of Double is instantiated, it in turn instantiates the Transformation interface with the same type. Then, a Double!int can be passed anywhere a Transformation!int is expected:

struct Value(T) {
  T val;
  Transformation!T transformation;
  T transform() {
    val = transformation.transform(val);
    return val;
  }
}
void main() {
  import std.stdio : writeln;
  auto = Value!int(10, new Double!int);
  writeln(intVal.transform());
}

When Value is instantiated with int, its member transformation is expected to be of type Transformation!int, which is exactly what it is initialized with when new Double!int is used in the struct literal. Note that, since Value is a template, the literal form must also be a template instantiation. Though not covered here, it's also possible to declare union templates.

An enum template is a templated manifest constant. Let's look at the long form first:

template isLongOrInt(T) {
  enum isLongOrInt = is(T == long) || is(T == int);
}

Dig around the source for Phobos and you'll find several declarations like this, all written before the shortened syntax was introduced for enum templates. Now we can do this:

enum isLongOrInt(T) = is(T == long) || is(T == int);

Instantiating an enum template causes the value of the manifest constant in the template body to be substituted at the point it is used at:

writeln(isLongOrInt!long);
writeln(isLongOrInt!float);

In this snippet, the first instantiation will be replaced at compile time by true and the second by false. It's conceptually the equivalent of the following:

enum isLongOrInt_Long = true;
enum isLongOrInt_Float = false;
writeln(isLongOrInt_Long);
writeln(isLongOrInt_Float);

These really come in handy when working with repetitive static if conditions or, as we'll see later in this chapter, template constraints. When a compile-time condition needs frequent use, consider turning it into an enum template.

We've already made use of a few function templates in the book, such as std.conv.to and, believe it or not, std.stdio.writeln. Before we look into why the former requires the template instantiation operator and the latter doesn't, let's first take a look at what a function template declaration looks like. First, the long form:

template sum(T) {
  T sum(T lhs, T rhs) {
    return lhs + rhs;
  }
}

And now, the more common short form:

T sum(T)(T lhs, T rhs) {
  return lhs + rhs;
}

There are two pairs of parentheses in the declaration. As is obvious in the long form, the first pair holds the template parameters and the second is for the function parameters. Instantiating and calling a function template can be done in two ways, as seen here:

auto doubles = sum!double(2.0, 3.0);
auto floats = sum(2.0f, 3.0f);
writeln(typeid(floats));

The first line instantiates the template in the same way we've seen for every case we've examined so far, by specifying the types in the argument list. Again, the parentheses are optional on a single argument, but are required if there are more. The second line is more interesting in this example. Notice that there is neither an instantiation operator nor a template argument anywhere to be found (the same is true for writeln). This is because the compiler is able to infer T from the function arguments, so there's no need to specify them. This is called Implicit Function Template Instantiation (IFTI). IFTI is quite convenient, but isn't always possible. Consider this example that wraps std.conv.to in order to convert a struct member variable into a different type:

struct Value {
  private int _val;
  T getAs(T)() {
    import std.conv : to;
    return to!T(val);
  }
}

First, note that the member function getAs is a template, but Value itself is not. Member function templates are instantiated like any other function template, except that they must be called through the dot operator on the type instance like a normal member function:

auto value = Value(100);
auto valstr = value.getAs!string();

Take out the !string bit and there is no way for the compiler to know that value.val should be converted to a string and not a double, a bool, or anything else. In that case, IFTI will fail with a compiler error. Modify getAs to take an argument to use as a default value, then the situation changes:

T getAs(T)(T defVal) {
  import std.conv : to;
  try {
    return to!T(val);
  } catch(Exception e) {
    return defVal;
  }
}

Now the compiler has enough information to implicitly deduce the type of T from the type of defVal in the function call, for example value.getAs("DefaultVal").

int addTwo()(int x) {
  return x + 2;
}
int addTwoInt(int x) nothrow {
  return addTwo(x);
}

void printLargeStruct (const(LargeStruct) p) {…}
void printLargeStruct(ref const(LargeStruct) p) {…}

void printLargeStruct()(auto ref const(LargeStruct) p) {…}

While types are perhaps the most common form of template parameter, there are others. We're going to examine three of them, beginning with value parameters.

struct Array(T, size_t size = 0) {
  static if(size > 0)
    T[size] elements;
  else
    T[] elements;
  enum isDynamic = Size == 0;
}

Array!int arr1;
assert(arr1.isDynamic);
Array!(float, 10) arr2;
assert(!arr2.isDynamic);

double getADouble() { return 100.0; }

Array!(float, cast(size_t)getADouble()) arr3;

void printSymbol(alias Name)() {
  writeln(Name.stringof);
}

int x;
printSymbol!x();               // Variable name
printSymbol!printSymbol();     // Function template name
printSymbol!(std.conv.to)();   // FQN of function template
printSymbol!(std.stdio)();     // Module name

x
printSymbol(alias Name)()
to(T)
module stdio

enum number = 10;
printSymbol!number();
printSymbol!(1+3)();
printSymbol!"Hello"();
printSymbol!(addTwo(3))();

int addTwo(int x) { return x + 2; }

10
4
"Hello"
5

class Base {
  void printType() { writeln(typeid(this)); }
}
class Derived : Base {}

Derived deri = new Derived;
Base base = new Derived;
deri.printType();
base.printType();

class Base {
  void printType(this T)() { writeln(typeid(T)); }
}

struct TypeMe {
  void printType(this T)() const {
    writeln(T.stringof);
  }
}

const(TypeMe) ct;
immutable(TypeMe) it;
TypeMe t;
ct.printType();
it.printType();
t.printType();