templates_basics.tex

\newpage
\part{Basics}\label{basics}

A template is a recipe, a blueprint that will generate code at your command and according to compile-time parameters you'll give. Templates are \emph{parameterized code}. Each template definition is written once in a module and can then be instantiated many times with different parameters, possibly resulting in quite different code, depending on the arguments you used.

\section{Template Declarations}\label{declarations}

Here is the syntax for a template declaration:

\index{template!declaration}
\index{syntax!template declaration}
\begin{dcode}
template templateName(list, of, parameters)
{
  // Some syntactically correct declarations here
  // The arguments are accessible inside the template scope.
}
\end{dcode}


\DD{templateName} is your usual D identifier and the list of parameters is a comma-separated list of zero or more template parameters. These can be:

\begin{description}

\item[Types:]\index{template!parameters!type} 

An \DD{identifier} alone by itself is considered a type name. The common D style is to use identifiers beginning with a capital letter (\DD{Range}, \DD{Rest}), as for any user-defined types. Many D templates use the C++\index{C++} tradition of one-capital-letter names for types, starting from \DD{T} (\DD{U}, \DD{V}, \ldots). Do not feel constrained by this, use what makes your templates most easy to understand.

\item[Aliases: ]\index{template!parameters!alias} 

These will capture symbols: variable names, class names, even other template names. They will also accept many compile-time literals: strings, arrays, function literals, \ldots Mostly, if you need a widely-accepting template, use an alias parameter. They will \emph{not} accept built-in types as arguments, however. You declare them with \D{alias} \DD{identifier}.

\item[Literal values:]\index{template!parameters!literal value} 

They can be integral values (\D{int}, \D{ulong}, \ldots), enum-based, strings, chars, floating-point values or boolean values. I think the rule is that any expression that can be evaluated at compile-time is OK. They are all declared like this: \D{typeName} \DD{iden\-ti\-fier}. For example : \D{int} \DD{depth} or \D{string} \DD{name}.

\item[Template parameters tuples:]\index{template!parameters!tuple} 

Template parameters tuples will capture un\-der one id\-en\-ti\-fier an en\-ti\-re list of tem\-plate pa\-ra\-me\-ters (types, names, literals, \ldots). Tuples will store any template argument you will throw at them. If no argument is passed, you will just get a zero-length tuple. Really, as they can deal with types as well as symbols, these tuples are a bit of a mongrel type but they are wonderfully powerful and easy to use, as you will see in section \ref{tuples}. The syntax is \DD{identifier...} (yes, three dots) and the tuple must be the last parameter of a template. 
\end{description}

Of those, types and aliases are the most common, while floating point values are fairly rare (their use as arguments for compile-time calculations have been superseded by D's Compile-Time Function Evaluation, aka CTFE\index{Compile-Time Function Evaluation|see{CTFE}}\index{CTFE}, described in section \ref{ctfe}). You'll see different uses of these parameters in this document.

Note that pointers, arrays, objects (instantiated classes), structs or functions are not part of this list. But as I said, alias parameters\index{template!parameters!alias} allow you to capture and use array, class, function or struct \emph{names} and then access their capacities.

\aparte{Aliases, Symbols and Names}{There is big difference between built-in types (like \D{int} or \D{double}\DD{[3]}) and user-defined types. A user-defined type, say a class called \DD{MyClass}, is a type name. So, it's \emph{both} a type (the class \DD{MyClass}, accepted by type templates arguments) and a name (\DD{MyClass}, accepted by \D{alias} template parameters). On the other hand, \D{int}, being a D keyword is not a symbol nor a name. It's just a type. You cannot pass it to an alias template parameter.}
The template body can contain any standard D declarations: variable, function, class, interface, other templates, alias declarations,\ldots The only exception I can think of is declaring a \D{module}\index{module}, as this is done at the top-level scope\index{scope!top-level}. 

\aparte{Syntax and Semantics} {And then there is a catch: code inside a \D{template} declaration must only be syntactically correct D code (that is: code that looks like D code). The semantics are not checked until instantiation. That means you can code happily, writing templates upon templates and the compiler won't bat an eye if you do not exercise your templates by instantiating them.}

Inside the template body, the parameters are all accessible as placeholders for the future arguments. Also, the template's own name refers to its current instantiation when the code is generated. This is mostly used in struct (see section \ref{structtemplates}) and class (\ref{classtemplates}) templates.

Here are some template declaration examples:\index{template!definition}\label{templatedeclarationexamples}

\begin{ndcode}
module declaration;

template ArrayOf(T) // T is a type
{
    alias T[] ArrayType;
    alias T ElementType;
}

template Transformer(From, To) // From and To are types, too
{
    To transform(From from) 
    { 
        import std.conv;
        return to!(To)(from);
    }

    class Modificator
    {
        From f;
        To t;
        this(From f) { /*...*/ }
    }
}

template nameOf(alias a)
{
    enum string name = a.stringof; // enum: manifest constant
                                   // determined at compile-time
}

template ComplicatedOne(T, string s, alias a, bool b, int i)
{ /* some code using T, s, a, b and i */ }

template Minimalist() {} // Zero-parameter template declaration.

template OneOrMore(FirstType, Rest...) // Rest is a tuple.
{ /*...*/ }

template ZeroOrMore(Types...) // Types is a tuple.
{ /*...*/ }

template Multiple(T)     { /*...*/ } // One arg version.
template Multiple(T,U)   { /*...*/ } // Two args,
template Multiple(T,U,V) { /*...*/ } // and three.
\end{ndcode}

The real syntax for template declarations is slightly more complex, I'll introduce more of it in the next sections (you'll see for example type restrictions in section \ref{specializations}, default values in section \ref{default}, instantiation constraints in \ref{constraints}, and more on tuples in section \ref{tuples}).

There is a limitation that's interesting to keep in mind: templates can be declared in almost any scope\index{scope}, except inside a (regular) function.

\aparte{\D{enum}}{In the previous code, see line 23? It defines a \D{string} called \DD{name} as a member of \DD{nameOf}. The \D{enum} placed right before means \DD{name} is a compile-time constant.\index{compile-time!constant (\D{enum})} You can see it as a kind of storage class,\index{storage class!enum as a kind of@\D{enum} as a kind of} in the line of \D{immutable} or \D{const}, one that means the value is totally defined and fixed at runtime. You'll see numerous examples of \D{enum} in this document.}

\section{Instantiating a Template}\label{instantiating}

To instantiate a template, use the following syntax:

\index{syntax!template instantiation}
\begin{dcode}
templateName!(list, of, arguments)
\end{dcode}


Note the `\DD{!}' before the comma-separated argument list. If the argument list contains only one argument (one token), you can drop the parenthesis:

\index{syntax!template instantiation}
\begin{dcode}
templateName!argument
\end{dcode}

\aparte{Templates as templates arguments\index{template!arguments!templates as}}{Arguments can themselves be the result of another template instantiation. If a template returns a type upon instantiation, it's perfectly OK to use it inside another template argument list. In this document you'll regularly see Matrioshka calls like this: \DD{firstTemp!(secondTempl!(Arguments), OtherArguments).}}


The compiler will have a look at the declarations (if more than one template were declared with the called name) and select the one with the correct number of arguments and the correct types to instantiate. If more than one template can be instantiated, it will complain  and stop there (though, have a look on template specializations in section \ref{specializations} and template constraints in section \ref{constraints}).

When you instantiate a template, the global effect is that a new named scope\index{scope!named} is created in the template declaration scope\index{scope!template declaration}. The name of this new scope is the template name with its argument list: \DD{templateName!(args)}. Inside the scope, the parameters are now 'replaced' with the corresponding arguments (storage classes get applied, variables are initialized, \ldots). Here's what possible instantiations of the templates declared in section \ref{declarations} might look like:
\index{template!instantiation}
\begin{dcode}
module instantiation;
import declaration;

void main()
{
    ArrayOf!(int).ArrayType myArray;

	 // From is an alias for the type double
	 // To for the type int
    alias Transformer!(double,int) transfo; 

    struct MyStruct { /*...*/ }
    
    // "MyStruct" is a identifier -> captured by alias
    auto name = nameOf!(MyStruct).name; 
    
    alias   
    ComplicatedOne!( int[]   // a type
                   , "Hello" // a string literal
                   , ArrayOf // a name (here the ArrayOf template)
                   , true    // a boolean literal
                   , 1+2     // calculated to be the integral '3'.
                   ) complicatedExample;

    alias Minimalist!() min1;

    alias
    OneOrMore!( int                   // FirstType is int.
              , double, string, "abc" // Rest is (double,string,"abc")
              ) oneOrMore;

    alias ZeroOrMore!(int) zero1; // Types is a 1-element tuple: (int)
    alias ZeroOrMore!(int,double,string) zero2; // Types is (int,double,string)
    alias ZeroOrMore!() zero3;                  // Types is the empty tuple: ()

    alias Multiple!(int) mult1;               // Selects the one-arg version
    alias Multiple!(int,double,string) mult2; // The three args version.
    //alias Multiple!() mult3;                // Error! No 0-arg version
}
\end{dcode}

Outside the scope\index{scope!template instantiation} (that is, where you put the template instantiation in your own code), the internal declarations are accessible by fully qualifying them:

\begin{dcode}
module internaldeclarations1;
import declaration;

// ArrayType is accessible (it's int[])
// array is a completly standard dynamic array of ints.
ArrayOf!(int).ArrayType array; 
ArrayOf!(int).ElementType element; // the same, element is an int.

void main()
{
    // the transform function is accessible. Instantiated like this, 
    // it's a function from double to string.
    auto s = Transformer!(double,string).transform(3.14159);
    assert(is(typeof(s) == string)); // s is a string
}
\end{dcode}

Obviously, using templates like this, with their full name, is a pain. The nifty D \D{alias} declaration is your friend:

\begin{dcode}
module internaldeclarations2;
import declaration;

alias Transformer!(double, string) StoD;

void main()
{
    auto s = StoD.transform(3.14159);
    auto m = new StoD.Modificator(1.618); // StoD.Modificator is a class
                                          // storing a double and a string.
}
\end{dcode}

You must keep in mind that instantiating a template means generating code. Using different arguments at different places in your code will instantiate \emph{as many differently named scopes}\index{scope!multiple templates instantiations}. This is a major difference with \emph{generics}\index{generics} in languages like Java\index{Java} or C\#\index{C\#}, where generic code is created only once and type erasure is used to link all this together. On the other hand, trying to instantiate many times the `same' template (ie: with the same arguments) will only create one piece of code.

\begin{dcode}
module differentinstantiations;
import declaration;

alias Transformer!(string,double) StoD;
alias Transformer!(double,string) DtoS;
alias Transformer!(string,int)    StoI;
// Now we can use three different functions and three different classes.
\end{dcode}

\aparte{\D{void}}{Note that \D{void}\index{void@\D{void}!as a template parameter}\index{template!parameters!void@\D{void}} is a D type and, as such, a possible template argument for a type parameter. Take care: many templates make no sense when \D{void} is used as a type. In the following sections and in the appendix, you'll see ways to restrict arguments to only certain types.}

\section{Template Building Blocks}\label{buildingblocks}

Up to now, templates may not seem that interesting to you, even with a simple declaration and instantiation syntax. But wait! D introduced a few nifty tricks that both simplify and greatly expand templates use. This section will introduce you to your future best friends, the foundations on which your templates will be built.

\subsection{The Eponymous Trick}\label{eponymous}
\index{eponymous trick}

If a template declares only one symbol with the same name (greek: \emph{epo-nymous}) as the enclosing template, that symbol is assumed to be referred to when the template is instantiated. This one is pretty good to clean your code:
\begin{dcode}
module pair;

template pair(T)
{
    T[] pair(T t) { return [t,t];} // declares only pair
}

auto array = pair!(int)(1);  // no need to do pair!(int).pair(1)
\end{dcode}

\begin{dcode}
module nameof1;

template nameOf(alias name)
{
    enum string nameOf = name.stringof;
}

struct Example { int i;}

void main()
{
    Example example;

    auto s1 = nameOf!(Example);
    auto s2 = nameOf!(example);

    assert(s1 == "Example");
    assert(s2 == "example");
}
\end{dcode}

A limitation is that the eponymous trick works \emph{only} if you define one (and only one) symbol. Even if the other symbols are private, they will break the eponymous substitution. This may change at a latter time, as the D developers have shown interest for changing this, but for the time being, you cannot do:

\begin{dcode}
module manyalias_error;

template ManyAlias(T, U)
{
    T[] firstArray;
    U[] secondArray;
    T[U] ManyAlias; // Alas, ET substitution doesn't work here
}

void main()
{
    // Error: Hoping for ManyAlias!(int,string).ManyAlias
    ManyAlias!(int, string) = ["abc":0, "def":1]; 

    ManyAlias!(int, string).firstArray = [0,1,2,3];
}
\end{dcode}

But, you will ask, what if I want client code to be clean and readable by using the eponymous trick, when at the same time I need to internally create many symbols in my template? In that case, create a secondary template with as many symbols as you need, and expose its final result through a (for example) \DD{result} symbol. The first template can instantiate the second one, and refer only to the \DD{.result} name:

\index{secondary template}
\label{impltrick}
\begin{dcode}
module record;

// primary template
template Record(T, U, V)
{
    // eponymous trick activated!     
    alias RecordImpl!(T,U,V).result Record;
}

// secondary (hidden) template
template RecordImpl(T, U, V)
{
    import std.typecons: Tuple, tuple;
    
    // The real work is done here 
    // Use as many symbols as you need.
    alias Tuple!(T,U) Pair;
    alias Pair[V] AssocArray;
    alias AssocArray[] result;
}
\end{dcode}

\begin{dcode}
module using_record;
import record;

Record!(int,string,double[]) recordslist;
/* ... */
\end{dcode}

You can find an example of this two-templates idiom\index{idiom!two templates} in Phobos, for example in \stdanchor{functional}{unaryFun} or \stdanchor{functional}{binaryFun}.

\subsection{\texorpdfstring{Inner \D{alias}}
                           {Inner alias}}
\label{inneralias}

A common use for templates is to do some type magics: deducing types, assembling them in new way, etc. Types are not first-class entities in D (there is no `\D{type}' type), but they can easily be manipulated as any other symbol, by aliasing them. So, when a template has to expose a type, it's done by aliasing it to a new name.
\index{exposing a type through an alias}
\begin{dcode}
module allarrays;

template AllArraysOf(T)
{
    alias T    Element;
    alias T*   PointerTo;
    alias T[]  DynamicArray;
    alias T[1] StaticArray;
    alias T[T] AssociativeArray;
}
\end{dcode}

\aparte{Exposing Template Parameters}{Though they are part of a template's name, its parameters are \emph{not} directly accessible externally. Keep in mind that a template name is just a scope name\index{scope}. Once it's instantiated, all the \DD{T}s and \DD{U}s and such do not exist anymore. If you need them externally, expose them through a template member, as is done with \DD{AllArraysOf.Element}. You will find other examples of this in section \ref{structtemplates} on struct templates and section \ref{classtemplates} on class templates.}

\subsection{\texorpdfstring{\D{static if}}
                           {static if}}
\label{staticif}

\subsubsection{Syntax}

The \D{static if} construct\footnote{ It's \emph{both} an statement and a declaration, so I'll call it a construct.}
lets you decide between two code paths at compile time. It's not specific to templates (you can use it in other part of your code), but it's incredibly useful to have your templates adapt themselves to the arguments. That way, using compile-time-calculated predicates based on the template arguments, you'll generate different code and customize the template to your need.

The syntax is:
\index{syntax!static if}
\begin{dcode}
static if (compileTimeExpression)
{
     /* Code created if compileTimeExpression is evaluated to true */
}
else /* optional */
{
     /* Code created if it's false */
}
\end{dcode}

Something really important here is a bit of compiler magic: once the code path is selected, the resulting code is instantiated in the template body, but without the curly braces. Otherwise that would create a local scope\index{scope!static if@\D{static if}}, hiding what's happening inside to affect the outside and would drastically limit the power of \D{static if}. So the curly braces are only there to group the statements together. 

If there is only one statement, you can get rid of the braces entirely, something you'll see frequently in D code. For example, suppose you need a template that `returns' \D{true} if the passed type is a dynamic array and \D{false} otherwise (this kind of predicate template\index{template!predicate templates} is developed a bit more in section \ref{predicates}).

\begin{dcode}
module isdynamicarray;

template isDynamicArray(T)
{
    static if (is(T t == U[], U))
        enum isDynamicArray = true;
    else
        enum isDynamicArray = false;
}
\end{dcode}

As you can see, with no curly braces after \D{static if} and the eponymous trick\index{eponymous trick} (\DD{isDynamicArray} is the only symbol defined by the template and its type is automatically deduced by the compiler), results in a very clean syntax. The \D{is}\DD{()}\index{is expression@\D{is} expression} part is a way to get compile-time introspection\index{compile-time!introspection} which goes hand in hand with \D{static if}. There is a crash course on it at the end of this document (see \autoref{isexpression}).

\subsubsection{Optional Code}

A common use of \D{static if} is to enable or disable code: a single \D{static if} without an \D{else} clause will generate code only when the condition is true. You can find many examples of this idiom\index{idiom!enabling/disabling code} in \std{range}\index{range!higher-level ranges} where higher-level ranges (ranges wrapping other ranges) will activate some functionality if and only if the wrapped range can support it, like this:\index{enabling/disabling code}\index{optional code}


\begin{dcode}
/* We are inside a MyRange templated struct, wrapping a R. */

    R innerRange;

/* Code that exists in all instantiations of MyRange */
(...)

/* optional code */
static if (hasLength!R) // does innerRange have a .length() method?
    auto length()       // Then MyRange has one also.
    {
        return innerRange.length;
    }

static if (isInfinite!R)     // Is innerRange an infinite range?
    enum bool empty = false; // Then MyRange is also infinite.
// And so on...
\end{dcode}

\subsubsection{\texorpdfstring{Nested \D{static if}s}
                              {Nested static ifs}}

\D{static if}s can be nested: just put another \D{static if} after \D{else}. Here is a template selecting an alias:

\index{syntax!nested \D{static if}s}
\index{static if@\D{static if}!nested}
\begin{dcode}
module selector;
import std.traits: isIntegral, isFloatingPoint;

template selector(T, alias intFoo, alias floatFoo, alias defaultFoo)
{
    static if (isIntegral!T)
       alias intFoo selector;
    else static if (isFloatingPoint!T)
       alias floatFoo selector; 
    else // default case
        alias defaultFoo selector;
}
\end{dcode}

If you need a sort of \D{static switch} construct, see section \ref{examples:staticswitch}.

\subsubsection{\texorpdfstring{Recursion with \D{static if}}
                              {Recursion with static if}}
\label{staticifrecursion}

\paragraph{Rank:}\label{rank}

Now, let's use \D{static if} for something a bit more complicated than just dispatching between code paths: recursion\index{recursion}.  What if you know you will receive n-dimensional arrays\index{arrays} (simple arrays, arrays of arrays, arrays of arrays of arrays, \ldots), and want to use the fastest, super-optimized numerical function for the 1-dim array, another one for 2D arrays and yet another one for higher-level arrays. Abstracting this away, we need a template doing some introspection\index{compile-time!introspection} on types, that will return 0 for an element (anything that's not an array), 1 for a 1-dim array (\DD{T[]}, for some \DD{T}), 2 for a 2-dim array (\DD{T[][]}), and so on. Mathematicians call this the \emph{rank}\index{rank} of an array, so we will use that. The definition is perfectly recursive: 
\index{rank!definition}
\index{template!recursion}
\begin{ndcode}
module rank1;

template rank(T)
{
    static if (is(T t == U[], U)) // is T an array of U, for some type U?
        enum rank = 1 + rank!(U); // then let's recurse down.
    else                          
        enum rank = 0;            // Base case, ending the recursion.
}
\end{ndcode}

Line 6 is the most interesting: with some \D{is} magic, \DD{U} has been deduced by the compiler and is accessible inside the \D{static if} branch. We use it to peel one level of `\DD{[]}' off the type and recurse\index{recursion} downward, using \DD{U} as a new type for instantiating \DD{rank}. Either \DD{U} is itself an array (in which case the recursion will continue) or it will hit the base case and stop there.

\begin{dcode}
module using_rank1;
import rank1;

static assert(rank!(int)       == 0);
static assert(rank!(int[])     == 1);
static assert(rank!(int[][])   == 2);
static assert(rank!(int[][][]) == 3);

/* It will work for any type, obviously */
struct S {}

static assert(rank!(S)  == 0);
static assert(rank!(S[])== 1);
static assert(rank!(S*) == 0);
\end{dcode}

\aparte{\D{static assert}}{Putting \D{static} before an \D{assert} forces the \D{assert} execution at compile-time. Using an \D{is} expression as the test clause gives assertion on types. 
One common use of \D{static assert} is to stop the compilation, for example if we ever get in a bad code path, by using \D{static assert}\DD{(0, someString)}. The string is then emitted as a compiler error message.}

\paragraph{Rank for Ranges:}\label{rankforranges}

D has an interesting sequence concept that's called \emph{range}\index{range} and comes with predefined testing templates in \std{range}. Why not extend \DD{rank}\index{rank} to have it deal with ranges and see if something is a range of ranges\index{range!of ranges} or more? A type can be tested to be a range with \DD{isInputRange} and its element type (the `\DD{U}') is obtained by applying \DD{ElementType} to the range type. Both templates are found in \std{range}. Also, since arrays are included in the range concept, we can entirely ditch the array part and use only ranges. Here is a slightly modified version of \DD{rank}:

\index{rank!for ranges}
\begin{dcode}
module rank2;
import std.range;

template rank(T)
{
    static if (isInputRange!T)                // is T a range?
        enum rank = 1 + rank!(ElementType!T); // if yes, recurse
    else                                      
        enum rank = 0;                        // base case, stop there
}

unittest
{
    auto c = cycle([[0,1],[2,3]]); // == [[0,1],[2,3],[0,1],[2,3],[0,1]...
    assert(rank!(typeof(c)) == 2); // range of ranges
}
\end{dcode}

\paragraph{Base Element Type:}\index{array!base element type}\index{range!base element type}

With \DD{rank}, we now have a way to get the number of \DD{[]}'s in an array type (\DD{T[][][]}) or the level of nesting in a range of ranges. The complementary query would be to get the base element type, \DD{T}, from any array of arrays \ldots of \DD{T} or the equivalent for a range. Here it is:

\begin{ndcode}
module baseelementtype;
import std.range;
import rank2;

template BaseElementType(T)
{
    static if (rank!T == 0)      // not a range
        static assert(0, T.stringof ~ " is not a range.");
    else static if (rank!T == 1) // simple range
        alias ElementType!T                     BaseElementType;
    else                         // at least range of ranges
        alias BaseElementType!(ElementType!(T)) BaseElementType;
}        
\end{ndcode}

Line 8 is an example of \D{static assert} stopping compilation if we ever get into a bad code path. Line 12 is an example of a Matrioshka call: a template using another template's call as its parameter.

\paragraph{Generating Arrays:}

Now, what about becoming more generative by inverting the process? Given a type \DD{T} and a rank \DD{r} (an \D{int}), we want to obtain \DD{T[][]...[]}, with \DD{r} levels of \DD{[]}'s. A rank of 0 means producing \DD{T} as the result type.

\begin{ndcode}
module ndim;

template NDimArray(T, int r)
{
    static if (r < 0)
        static assert(0, "NDimArray error: the rank must be positive.");
    else static if (r == 0)
        alias T NDimArray;
    else // r > 0
        alias NDimArray!(T, r-1)[] NDimArray;
}
\end{ndcode}

Here, recursion\index{recursion} is done on line 8: we instantiate \DD{NDimArray!(T,r-1)}, which is a type, then create an array\index{arrays} of them by putting \DD{[]} at the end and expose it through an alias. This is also a nice example of using an integral value\index{template!parameters!integral value} as a template parameter.

\begin{dcode}
module using_ndim;
import ndim;

alias NDimArray!(double, 8) Level8;
static assert(is(Level8 == double[][][][][][][][]));
static assert(is(NDimArray!(double, 0) == double));
\end{dcode}

\paragraph{Repeated composition:} 

As a last example, we will use an alias template parameter\index{template!parameters!alias} in conjunction with some \D{static if} recursion\index{recursion}\index{static if@\D{static if}} to define a template that creates the `exponentiation' of a function, its repeated composition. Here is what I mean by this:

\begin{dcode}
module using_power;
import repeatedcomposition;

string foo(string s) { return s ~ s;}
Arr[] makeArray(Arr)(Arr array) { return [array,array];}

void main()
{
   // power!(foo, n) is a function.
   assert(power!(foo, 0)("a") == "a");                // identity function
   assert(power!(foo, 1)("a") == foo("a"));           // "aa"
   assert(power!(foo, 2)("a") == foo(foo("a")));      // "aaaa"
   assert(power!(foo, 3)("a") == foo(foo(foo("a")))); // "aaaaaaaa"
	
   // It's even better with function templates:
   assert(power!(makeArray, 0)(1) == 1);
   assert(power!(makeArray, 1)(1) == [1,1]);
   assert(power!(makeArray, 2)(1) == [[1,1],[1,1]]);
   assert(power!(makeArray, 3)(1) == [[[1,1],[1,1]],[[1,1],[1,1]]]);
}
\end{dcode}

First, this is a template that `returns' (becomes, rather) a function. It's easy to do with the eponymous trick:\index{eponymous trick} just define inside the template a function with the same name. Secondly, it's clearly recursive in its definition, with two base cases: if the exponent is zero, then we shall produce the identity function and if the exponent is one, we shall just return the input function itself. That being said, \DD{power} writes itself:

\index{function composition}
\begin{ndcode}
module repeatedcomposition;

template power(alias fun, uint exponent)
{
    static if (exponent == 0) // degenerate case -> id function
        auto power(Args)(Args args) { return args; }
    else static if (exponent == 1) // end-of-recursion case -> fun
        alias fun power;
    else
        auto power(Args...)(Args args) 
        {
            return .power!(fun, exponent-1)(fun(args));
        }
}
\end{ndcode}

\aparte{.power}{If you are wondering what's with the \DD{.power} syntax on line 12, it's because by defining an eponymous template, we hide the parent template's name. So inside \DD{power(Args...)} it refers to \DD{power(Args...)} and not \DD{power(}\D{alias}\DD{ fun, }\D{uint}\DD{ exponent)}. Here we want a new \DD{power} to be generated so we call on the global \DD{power} template with the `global scope'\index{scope!global scope operator}\index{operator!global scope operator (\DD{.})} operator (\DD{.}).}

In all three branches of \D{static if}, \DD{power} exposes a \DD{power} member, activating the eponymous template trick\index{eponymous trick} and allowing for an easy use by the client. Note that this template will work not only for unary (one argument) functions but also for n-args functions\footnote{ Except for the degenerate, $n = 0$ case, since the identity function defined above accepts only one arg. A version with more than one argument is possible, but would need to return a tuple.}, for delegates and for structs or classes that define the \DD{()}(ie, \D{opCall}) operator\index{operator!opCall, ()@\DD{opCall}, \DD{()}} and for function templates\ldots\footnote{ I cheated a little bit there, because the resulting function accepts any number of arguments of any type, though the standard function parameters checks will stop anything untowards to happen. A cleaner (but longer, and for template functions, more complicated) implementation would propagate the initial function parameter typetuple.}

Now, are you beginning to see the power of templates?

\aparte{Curried Templates?}{\index{template!curried templates}No, I do not mean making them spicy, but separating the template's arguments, so as to call them in different places in your code. For \DD{power}, that could mean doing \D{alias }\DD{power!2 square;} somewhere and then using \DD{square!fun1}, \DD{square!fun2} at your leisure: the \DD{exponent} parameter and the \DD{fun} alias are separated. In fact, \DD{power} is already partially curried: \DD{fun} and \DD{exponent} are separated from \DD{Args}. For more on this, see section \ref{templatesintemplates}. 

Given a template \DD{temp}, writing a \DD{curry} template that automatically generates the code for a curried version of \DD{temp} is \emph{also} possible, but outside the scope of this document.\index{scope!outside the scope of this document}}

\subsection{Templates Specializations}\label{specializations}

\index{template!specialization}
Up to now, when we write a \DD{T} in a template parameter list, there is no constraint on the type that \DD{T} can become during instantiation. Template specialization is a small `subsyntax', restricting templates instantiations to a subset of all possible types and directing the compiler into instantiating a particular version of a template instead of another. If you've read \autoref{isexpression} on the \D{is} expression, you already know how to write them. If you didn't, please do it now, as it's really the same syntax. These specializations are a direct inheritance from C++\index{C++} templates, up to the way they are written and they existed in D from the very beginning, long before \D{static if} or templates constraints were added. 

The specializations are added in the template parameter list, the \DD{(T, U, V)} part of the template definition. \index{syntax!templates specialization}\DD{Type : OtherType} restricts \DD{Type} to be implicitly convertible into \DD{OtherType}. 

\index{template!specialization}
\begin{dcode}
module specialization1;

template ElementType(T : U[], U) // can only be instantiated with arrays
{
    alias U ElementType;
}

template ElementType(T : U[n], U, size_t n) // only with static arrays
{
    alias U ElementType;
}

class Array { alias int ElementType;}

template ElementType(T : Array) 
{
    alias Array.ElementType ElementType;
}
\end{dcode}

Now, the idea may seem strange to you: if you know you want to restrict \DD{Type} to be \DD{AnotherType}, why make it a template parameter? It's because of templates specializations' main use: you can write different implementations of a template (with the same name, obviously), and when asked to instantiate one of them, the compiler will automatically decide which one to use, taking the `most adapted' to the provided arguments. `Most adapted' obeys some complicated rules you can find on the D Programming Language website, but they act in a natural way most of the time. The neat thing is that you can define the most general template \emph{and} some specialization. The specialized ones will be chosen when it's possible. For 

\index{template!specialization}
\begin{dcode}
module specialization2;

template InnerType(T : U*, U) // Specialization for pointers
{
    alias U InnerType;
}

template InnerType(T : U[], U) // Specialization for dyn. arrays
{ /*...*/ }

template InnerType(T) // Standard, default case
{ /*...*/ }

void main()
{
    int* p;
    int i; 
    alias InnerType!(typeof(p)) Pointer; // pointer spec. selected
    alias InnerType!(typeof(i)) Default; // standard template selected
}
\end{dcode}

This idiom\index{idiom!template specialization} is used frequently in C++\index{C++}, where there is no (built-in) \D{static if} construct or template constraints. Oldish D templates used it a lot, too, but since other ways have been around for some years, recent D code seems to be more constraint-oriented: have a look at heavily templated Phobos modules, for example \std{algorithm} or \std{range}.

\aparte{Specializations or \D{static if} or Templates Constraints?}{Yes indeed. Let's defer this discussion for when we have seen all three subsystems.} 

\subsection{Default Values}\label{default}

Like functions parameters, templates parameters can have default values. The syntax is the same: \DD{Param = defaultValue}. The default can be anything that makes sense with respect to the parameter kind: a type, a literal value, a symbol or another template parameter.

\begin{dcode}
module def;

template Default(T = int, bool flag = false)
{
    static if (flag)
        alias T Default;
    else
        alias void Default;
}

alias Default!(double) D1;       // Instantiate Default!(double, false)
alias Default!(double, true) D2; // Instantiate Default!(double, true) (Doh!)
alias Default!() D3;             // Instantiate Default!(int, false)
\end{dcode}

In contrast to function parameters, thanks to specializations (\ref{specializations}) or IFTI (\ref{ifti}), some template parameters can be automatically deduced by the compiler. So, default template parameters are not required to be the final parameters in the list:

\begin{dcode}
module deduced;
import std.typecons: Tuple;

template Deduced(T : U[], V = T, U)
{
    alias Tuple!(T,U,V) Deduced;
}

alias Deduced!(int[], double) D1; // U deduced to be int. Force V to be a double.
alias Deduced!(int[]) D2; // U deduced to be int. V is int, too.
\end{dcode}


\aparte{Specialization and Default Value?}{Yes you can. Put the specialization first, then the default value. Like this: \DD{(T : U[] = int[], U)}. It's not commonly used, though.}

As for functions, well-chosen defaults can greatly simplify standard calls. See for example the \stdanchor{algorithm}{sort}. It's parameterized on a predicate and a swapping strategy, but both are adapted to what most people need when sorting. That way, most client uses of the template will be short and clean, but customization to their own need is still possible.


\TODO{Maybe something on template dummy parameters, like those used by \stdanchor{traits}{ReturnType}. Things like \DD{dummy == }\D{void}.}

\section{Function Templates}\label{functiontemplates}

\index{template!function templates}
\subsection{Syntax}\label{functiontemplatessyntax}

If you come from languages with generics\index{generics}, maybe you thought D templates were all about parameterized classes and functions and didn't see any interest in the previous sections (acting on types?). Fear not, you can also do type-generic functions and such in D, with the added generative power of templates.

As we have seen in section \ref{eponymous}, if you define a function inside a template and use the template's own name, you can call it easily:

\index{syntax!function templates}
\begin{dcode}
module function_declaration1;
import std.conv : to;

// declaration:
template myFunc(T, int n)
{
    auto myFunc(T t) { return to!int(t) * n;}
}

void main()
{
    // call:
    auto result = myFunc!(double,3)(3.1415);

    assert(result == to!int(3.1415)*3);
}
\end{dcode}

Well, the full story is even better. First, D has a simple way to declare a function template: just put a template parameter list before the argument list:

\index{syntax!function templates}
\index{function template}
\begin{dcode}
module function_declaration2;
import std.conv:to;

string concatenate(A,B)(A a, B b)
{
    return to!string(a) ~ to!string(b);
}

Arg select(string how = "max", Arg)(Arg arg0, Arg arg1)
{
    static if (how == "max")
        return (arg0 < arg1) ? arg1 : arg0;
    else static if (how == "min")
        return (arg0 < arg1) ? arg0 : arg1;
    else
        static assert(0, 
        "select: string 'how' must be either \"max\" or \"min\".");
}      
\end{dcode}

Nice and clean, uh? Notice how the return type can be templated too, using \DD{Arg} as a return type in \DD{select}. 

\subsection{\texorpdfstring{\D{auto} return}
                           {auto return}}
\label{autoreturn}

Since you can select among code paths, the function return type can vary widely, depending on the template parameters you passed it. Use \D{auto} to simplify your code:\footnote{ \D{auto} return functions used to have some limitations, like for example not appearing in docs. I remember having to code type-manipulating templates to get correct the return type.}

\index{auto return@\D{auto} return}
\begin{dcode}
module morph;

// What morph will return will heavily depend on T and U
auto morph(alias f, T, U)(U arg)
{
    static if (is(T == class))
        return new T(f(arg));
    else static if (is(T == struct))
        return T(f(arg));
    else
        return; // void-returning function.    
}
\end{dcode}

\aparte{\D{auto ref}}{ A function template can have an \D{auto ref} return type. That means that for templates where the returned values are lvalues, the template will get the \D{ref}ed version. And the non-\D{ref} version if not.}

\subsection{IFTI}\label{ifti}

Even better is Implicit Function Template Instantiation (IFTI)\index{IFTI}\index{Implicit Function Template Instantiation|see{IFTI}}, which means that the compiler will generally be able to automatically determine a template's parameters\index{template!parameters!IFTI} by studying the function arguments. If some template arguments are pure compile-time parameters, just provide them directly:

\begin{dcode}
module ifti;
import function_declaration2;

struct Foo {}

void main()
{
    string res1 = concatenate(1, 3.14); // A is int and B is double
    string res2 = concatenate("abc", Foo()); // A is string, B is Foo

    auto res3 = select(3,4); // how is "max", Arg is int.
    auto res4 = select!"min"(3.1416, 2.718); // how is "min", Arg is double.
}
\end{dcode}

As you can see, this results in very simple calling code. So we can both declare function templates and call them with a very clean syntax. The same can be done with structs or classes and such, as you will see in the next sections. In fact, the syntax is so clean that, if you are like me, you may forget from time to time that you are \emph{not} manipulating a function (or a struct, etc.): you are manipulating a template, a parameterized piece of code. 

\aparte{A Mantra}{\label{mantra}\index{mantra}\DD{XXX} templates are not \DD{XXX}s, they are templates. With \DD{XXX} being any of (function, struct, class, interface, union). Templates are parameterized scopes\index{scope!scopes are not first-class in D} and scopes are not first-class in D: they have no type, they cannot be assigned to a variable, they cannot be returned from functions. That means, for example, that you \emph{cannot} return function templates, you cannot inherit from class templates and so on. Of course, \emph{instantiated} templates are perfect examples of functions, classes, and such. Them you can inherit, return\ldots}

We may encounter The Mantra again in this tutorial.

\subsection{Example: Flattening Arrays and Ranges}\label{functionflatten}

Let's use what we have just seen in a concrete way. In D, you can manipulate 2D and 3D arrays\index{arrays}, but sometimes need to process them linearly. As of this writing, neither \std{algorithm} nor \std{range} provide a \DD{flatten} function. Beginning with simple arrays, here is what we want:

\begin{dcode}
module using_flatten1;
import flatten1;

void main()
{
    assert( flatten([[0,1],[2,3],[4]]) == [0,1,2,3,4] );
    assert( flatten([[0,1]]) == [0,1] );
    assert( flatten([0,1]) == [0,1] );
    assert( flatten(0) == 0 );

    assert( flatten([[[0,1],[]], [[2]], [[3], [4,5]], [[]], [[6,7,8]]])
            == [0,1,2,3,4,5,6,7,8] );
}
\end{dcode}

So, studying the examples, we want a simple array (rank == 1) or a non-array (rank == 0) to be unaffected by \DD{flatten}: it just returns them. For arrays of rank\index{rank} 2 or higher, it collapses the elements down to a rank-1 array. It's classically recursive:\index{recursion} we will apply \DD{flatten} on all sub-arrays with \stdanchor{algorithm}{map} and concatenate the elements with \stdanchor{algorithm}{reduce}:

\begin{dcode}
module flatten1;
import std.algorithm;
import rank2;

auto flatten(Arr)(Arr array)
{
    static if (rank!Arr <= 1)
        return array;
    else
    {
        auto children = map!(.flatten)(array);
        return reduce!"a~b"(children); // concatenate the children
    }
}
\end{dcode}

We make good use of D \D{auto} return parameter for functions there. In fact, a single call to \DD{flatten} will create one instance per level, all with a different return type. 

Note that \DD{flatten} works perfectly on ranges\index{range} too, but is not lazy: it eagerly concatenates all the elements down to the very last one in the innermost range. Ranges being lazy, a good \DD{flatten} implementation for them should itself be a range that delivers the elements one by one, calculating the next one only when asked to (and thus, would work on infinite or very long ranges too, which the previous simple implementation cannot do). Implementing this means creating a struct template (\ref{structtemplates}) with a factory function (\ref{factory}). You will find this as an example in section \ref{structflatten}.

From our current \DD{flatten}, it's an interesting exercise to add another parameter: the number of levels you want to flatten. Only the first three levels or last two innermost, for example. Just add an integral template parameter that gets incremented (or decremented) when you recurse and is another stopping case for the recursion. Positive levels could mean the outermost levels, while a negative argument would act on the innermost ones. A possible use would look like this:

\begin{dcode}
flatten!1([[[0,1],[]], [[2]], [[3], [4,5]], [[]], [[6,7,8]]]);
     // == [[[0,1],[],[2],[3], [4,5],[],[6,7,8]]
flatten!2([[[0,1],[]], [[2]], [[3], [4,5]], [[]], [[6,7,8]]]);
     // == [0,1,2,3,4,5,6,7,8]
flatten!0([[[0,1],[]], [[2]], [[3], [4,5]], [[]], [[6,7,8]]]);
     // ==[[[0,1],[]], [[2]], [[3], [4,5]], [[]], [[6,7,8]]]
flatten!(-1)([[[0,1],[]], [[2]], [[3], [4,5]], [[]], [[6,7,8]]]);
     // ==[[[0,1]], [[2]], [[3,4,5]], [[]], [[6,7,8]]]
\end{dcode}

\subsection{Anonymous Function Templates}\label{anonymousfunctions}

In D, you can define anonymous functions\index{anonymous!functions} (delegates even, that is: closures):

\begin{dcode}
module anonymous_function1;

auto adder(int a)
{
    return (int b) { return a+b;};
}

unittest
{
    auto add1 = adder(1); // add1 is an int delegate(int)
    assert(add1(2) == 3);
}
\end{dcode}

In the previous code, \DD{adder} returns an anonymous delegate. Could \DD{Adder} be templated? Ha! Remember The Mantra (page \pageref{mantra}):\index{mantra} function templates are templates and cannot be returned. For this particular problem, there are two possible solutions. Either you do not need any new type and just use \DD{T}:

\index{returning a function}
\begin{dcode}
module anonymous_function2;

auto adder(T)(T a)
{
    return (T b) { return a+b;};
}

unittest
{
    auto add1f = adder(1.0); // add1f is an float delegate(float)
    assert(add1f(2.0) == 3.0);

    import std.bigint;

    // addBigOne accepts a BigInt and returns a BigInt
    auto addBigOne = adder(BigInt("1000000000000000"));
    assert(addBigOne(BigInt("1")) == BigInt("1000000000000001"));

    // But:
    // auto error = add1(3.14); // Error! Waiting for an int, getting a double.
}
\end{dcode}

In the previous example, the returned anonymous delegate\index{anonymous!delegates} is \emph{not} templated. It just happens to use \DD{T}, which is perfectly defined once instantiation is done. If you really need to return something that can be called with any type, use an inner struct (see section \ref{innerstructs}).

Now, it may come as a surprise to you that D \emph{does} have anonymous function templates\index{function templates!anonymous function templates}\index{template!function templates!anonymous function templates}\index{anonymous!function templates}. The syntax is a purified version of anonymous functions:

\index{syntax!anonymous function templates}
\begin{dcode}
(a,b) { return a+b;} 
\end{dcode} 

Yes, the previous skeleton of a function is an anonymous template. But, remember The Mantra:\index{mantra} you cannot return them. And due to (to my eyes) a bug in \D{alias} grammar, you cannot alias them to a symbol:

\begin{dcode}
alias (a){ return a;} Id; // Error
\end{dcode}

So what good are they? You can use them with template alias parameters, when these stand for functions and function templates:

\begin{dcode}
module calltwice;

template callTwice(alias fun)
{
    auto callTwice(T)(T t)
    {
        return fun(fun(t));
    }
}

unittest
{
    alias callTwice!( (a){ return a+1;}) addTwo;
    assert(addTwo(2) == 4);
}
\end{dcode}

Since they are delegates, they can capture local symbols:

\begin{dcode}
module using_calltwice;
import calltwice;

unittest
{
    enum b = 3; // Manifest constant, initialized to 3
    alias callTwice!( (a){ return a+b;}) addTwoB;
    assert(addTwoB(2) == 2 + 3 + 3);
}
\end{dcode}

\subsection{Closures are a Poor Man's Objects}\label{closuresareapoormansobjects}

D closures can wrap runtime environment and keep them near their hot little hearts. We can of course create them with a template. To obtain the equivalent of an object, let's create a function that returns a tuple (a \stdanchor{typecons}{Tuple}) with named arguments.

\begin{dcode}
module makecounter;
import std.traits;
import std.typecons;

auto makeCounter(T)(T _counter = T.init) if (isNumeric!T)
{
    bool sense = true;
    auto changeSense = () { sense = !sense;};
    auto inc = (T increment) { _counter += (sense ? increment : -increment); };
    auto dec = (T decrement) { _counter += (sense ? -decrement : decrement); };
    auto counter = () { return _counter;};
    
    return Tuple!( typeof(changeSense), "changeSense"
                 , typeof(inc), "inc"
                 , typeof(dec), "dec"
                 , typeof(counter), "counter")(changeSense, inc, dec, counter);
}
\end{dcode}

The \D{if} part after the argument list is just sanity-check template constraint (they are described in \autoref{constraints}). The returned \DD{Tuple} is a bit heavy for my taste, but using named tuple fields gives us a nice object-like call syntax.\footnote{ See the example in section \ref{namedfieldstuples} for a way to extend Phobos' \DD{tuple}.} Otherwise, a simple \D{return }\DD{tuple(changeSense, inc, dec, counter);} could have been used but then the inner closures would have to be accessed by their index and not a name.

Here is how it's used:

\begin{dcode}
module using_makecounter;
import makecounter;

void main()
{
    auto c = makeCounter(0); // T is int.
    auto c2 = makeCounter!int; // The very same.

    c.inc(5);
    assert(c.counter() == 5);
    c.inc(10);
    assert(c.counter() == 15);
    c.changeSense(); // now each increment will in fact decrement
    c.inc(5);
    assert(c.counter() == 10);
}
\end{dcode}

\subsection{Function Overloading}\label{functionsoverloading}

\unfinished{OK, I need to write something on this.}

\subsection{Storage Classes}\label{storageclasses}

As seen in section \ref{instantiating}, storage classes get applied to types during instantiation.\index{template!parameters!storage class} It also works for function templates arguments:

\index{storage class!function parameters}
\begin{dcode}
module storage;

void init(T)(ref T t)
{ 
    t = T.init;
}

unittest
{
    int i = 10;
    init(i);
    assert(i == 0);
}
\end{dcode}

Should the need arise, this means you can customize your storage classes according to template arguments. There is no built-in syntax for that, so you'll have to resort to our good friend \D{static if}\index{static if@\D{static if}!functions storage classes} and the eponymous trick:\index{eponymous trick!functions storage classes}

\index{storage class}
\index{is expression@\D{is} expression!type specialization}
\index{static if@\D{static if}!nested}
\begin{dcode}
// Has anyone a better example?
module init;

template init(T)
{
    static if (is(T == immutable) || is(T == const))
        void init(T t) {} // do nothing
    else static if (is(T == class))
        void init(ref T t)
        {
            t = new T();
        }
    else 
        void init(ref T t)
        {
            t = T.init;
        }
}
\end{dcode}

\subsection{Properties are Automatically Deduced}\label{autodeduce}

In D, a function can have the following properties:

\begin{itemize}
\item A function can be tagged with the \D{pure} property, which means it does not have side-effects: the value you get back is the only thing that matters. 
\item They can also be tagged with \D{@safe}, \D{@trusted} and \D{@system}. \D{@safe} means a function cannot corrupt memory. A \D{@trusted} function can call \D{@safe} ones, but offers no other guaranty concerning memory. And a \D{@system} function may do whatever it wants.
\item The last property is \D{nothrow} which means the function will not throw any exceptions.
\end{itemize}

As the compiler gets complete access to a function template code, it can analyze it and automatically deduce properties for you. This feature is still quite new as of this writing, but it seems to work. So, \emph{all} of your function templates will get a smattering of properties when they are instantiated (these properties will of course vary with the template parameters).

\subsection{\texorpdfstring{\D{in} and \D{out} Clauses}
                           {in and out Clauses}}
\label{inandoutclauses}

The \D{in} and \D{out} clauses for a function are given full access to a template's parameters. As for other parameterized code, that means you can use \D{static if} to enable or disable code, depending on the template arguments.

\index{in and out clauses@\D{in} and \D{out} clauses}
\index{static if@\D{static if}!enabling/disabling code}
\begin{dcode}
module inoutclauses;
import std.complex, std.math, std.traits;

auto squareRoot(N)(N n) if (isNumeric!N || isComplex!N)
in 
{
    // no need to do that for a complex.
    static if (isNumeric!N)
        enforce(n > 0);
    
}
body
{
    return sqrt(n);
}
\end{dcode}

\subsection{Modifying Functions}\label{modifyingfunctions}

This section will show you how to use wrapper templates to add new functionalities to pre-defined functions. More powerful examples are shown in \autoref{funwithfunctions}, but they use templates we have not seen yet. Be sure to have a look at them when you can, though.


\unfinished{I want to put some small function-wrapping templates: 
\begin{itemize}
\item making a function accept tuples
\item making a function have named parameters (sort of)
\item making a function have default values for its args
\item making a function accept more args than the original
\item making a function accept arguments of a different type (that's useful when mapping on tuples, like in section \ref{tuplesassequences})

\end{itemize}
}
\subsubsection{Accepting a Tuple}


\begin{dcode}
module acceptingtuple;

template tuplify(alias fun)
{
    auto tuplify(T...)(Tuple!T tup)
    {
        return fun(tup.expand);
    }
}
\end{dcode}

Another interesting (and much more complicated) example is \DD{juxtapose} (see section \ref{juxtapose}).

\subsubsection{Mapping n ranges in parallel}\label{parallelmapping}

\begin{dcode}
module nmap;
import std.algorithm;
import std.typetuple: allSatisfy;
import acceptingtuple;

// Very easy to do, now:
auto nmap(alias fun, R...)(R ranges) if (allSatisfy!(isInputRange,R))
{
    return map!(tuplify!fun)(zip(ranges));
}
\end{dcode}

More complicated: \stdanchor{algorithm}{map} accepts more than one function as template arguments. In that case, the functions are all mapped in parallel on the range, internally using \stdanchor{functional}{adjoin}.
Here we can extend \DD{nmap} to accept $n$ functions in parallel too. There is a first difficulty:

\begin{dcode}
auto nmap(fun..., R...)(R ranges) if (allSatisfy!(isInputRange, R))
{ ... }   ^^^^^^^^^^^^ Uh?
\end{dcode}

See the problem? We need both a variable list of functions and a variable list of ranges. But template parameters tuples must be the last parameter of a template: there can be only one. Double-stage templates (see section \ref{templatesintemplates}) come to the rescue:

\begin{dcode}
template nmap(fun...) if (fun.length >= 1)
{
    auto nmap(R...)(R ranges) if (allSatisfy!(isInputRange, R))
    {...}
}
\end{dcode}

Now the two parts are well separated. Which gives us the final code:

\begin{dcode}
module nmap2;
import std.algorithm;
import std.functional : adjoin;
import std.range;
import std.typetuple : allSatisfy;
import acceptingtuple; // tuplify

template nmap(fun...) if (fun.length >= 1)
{
    auto nmap(R...)(R ranges) if (allSatisfy!(isInputRange, R))
    {
        alias adjoin!(staticMap!(tuplify, fun)) _fun;
        return map!(_fun)(zip(ranges));
    }
}
\end{dcode}

\TODO{Give an example with \DD{max}, it works!}

And here is the $n$-ranges version of \stdanchor{algorithm}{filter}:

\begin{dcode}
module nfilter;
import std.algorithm;
import std.range;
import std.typetuple : allSatisfy;

import acceptingtuple; // tuplify

auto nfilter(alias fun, R...)(R ranges) if (allSatisfy!(isInputRange, R))
{
    return filter!(tuplify!fun)(zip(ranges));
}
\end{dcode}

\TODO{Examples, lots of examples.}

\section{Struct Templates}\label{structtemplates}
\subsection{Syntax}\label{structsyntax}

As you might have guessed, declaring a struct template is done like this:

\index{syntax!struct templates}
\index{struct template}
\begin{dcode}
module tree1;
import std.array;

struct Tree(T)
{
    T value;
    Tree[] children;

    bool isLeaf() @property { return children.empty;}
    /* More tree functions: adding children, removing some,... */
}     
\end{dcode}

\aparte{\DD{Tree[]} or \DD{Tree!(T)[]}?}{Remember that inside a template declaration, the template's name refers to the current instantiation. So inside \DD{Tree(T)}, the name \DD{Tree} refers to a \DD{Tree!T}.}

This gives us a run-of-the-mill generic tree, which is created like any other template:

\begin{dcode}
module using_tree;
import tree1;

void main()
{
    auto t0 = Tree!int(0);
    auto t1 = Tree!int(1, [t0,t0]);
    Tree!int[] children = t1.children;
}
\end{dcode}

As with all previous templates, you can parametrize your structs using much more than simple types:

\index{struct template}
\begin{dcode}
module heap1;

bool lessThan(T)(T a, T b) { return a<b;}

struct Heap(Type, alias predicate = lessThan, float reshuffle = 0.5f)
{
    // predicate governs the internal comparison
    // reshuffle deals with internal re-organizing of the heap
    Type[] values;
/*...*/
}
\end{dcode}

Struct templates are heavily used in \std{algorithm} and \std{range} for lazy evaluation, have a look there.

\subsection{Factory Functions}\label{factory}

Now, there is one limitation: struct constructors do not do activate IFTI (\ref{ifti}) like template functions do. In the previous subsection to instantiate \DD{Tree(T)} I had to explicitly indicate \DD{T}:

\begin{dcode}
auto t0 = Tree!int(0); // Yes.

auto t1 = Tree(0); // Error, no automatic deduction that T is int.
\end{dcode}

This is because templated constructors are possible (see \ref{constructortemplates}) and may have template parameters differing from that of the global struct template. But honestly that's a pain, even more so for struct templates with many template arguments. There is a solution, of course: use a template function to create the correct struct and return it. Here is an example of such a factory function for \DD{Tree}:

\index{factory function}
\begin{dcode}
module tree2;
import tree1;

auto tree(T)(T value, Tree!T[] children = null) 
{
    return Tree!(T)(value, children);
}

void main()
{
    auto t0 = tree(0); // Yes!
    auto t1 = tree(1, [t0,t0]); // Yes!

    static assert(is( typeof(t1) == Tree!int ));

    auto t2 = tree(t0); // Yes! typeof(t2) == Tree!(Tree!(int))
}
\end{dcode}

Once more, have a look at \std{algorithm} and \std{range}, they show numerous examples of this idiom.\index{idiom!factory function}

\subsection{Giving Access to Inner Parameters}\label{givingaccess}

As was said in section \ref{inneralias}, template arguments are not accessible externally once the template is instantiated. For the \DD{Tree} example, you might want to get an easy access to \DD{T}. As for any other templates, you can expose the parameters by aliasing them. Let's complete our \DD{Tree} definition:

\index{struct template!inner alias parameters}
\begin{dcode}
module tree3;
import std.array;

struct Tree(T)
{
    alias T Type;
    T value;
    Tree[] children;

    bool isLeaf() @property { return children.empty;}
}     

void main()
{
    Tree!string t0 =Tree!string("abc");
    alias typeof(t0) T0;

    static assert(is( T0.Type == string ));
}
\end{dcode}

\subsection{Templated Member Functions}\label{membertemplates}

A struct template is a template like any other: you can declare templates inside, even function templates. Which means you can have templated member functions. 

\aparte{Crippled D}{Okay, since I haven't introduce some powerful D features such as mixin templates (\ref{mixintemplates}) and string mixins (\ref{stringmixins}), I'll have to do some code duplication here. Sorry for that, but that's the condition for having all named code sample compile.}

\paragraph{Mapping on a Tree} Let us use that to give our \D{Tree} a mapping ability. For a range,\index{range} you can use \stdanchor{algorithm}{map} to apply a function in turn to each element, thus delivering a transformed range. The same process can be done for a tree, thereby keeping the overall \emph{shape} but modifying the elements.\footnote{ We could easily make that a free function, but this \emph{is} the member function section.}

Let's think a little bit about it before coding. \DD{map} should be a function template that accepts any function name as a template alias parameter\index{template!parameters!alias} (like \stdanchor{algorithm}{map}). Let's call this alias \DD{fun}. The \DD{value} member should be transformed by \DD{fun}, that's easy to do. We want to return a new \DD{Tree}, which will have for type parameter the result type of \DD{fun}. If \DD{fun} transforms \DD{A}s into \DD{B}s, then a \DD{Tree!A} will be mapped to a \DD{Tree!B}. However, since \DD{fun} can be a function template, it may not have a pre-defined return type that could be obtained by \stdanchor{traits}{ReturnType}. We will just apply it on a \DD{T} value (obtained by \DD{T.init} and take this type. So \DD{B} will be \DD{typeof(fun(T.init))}.

What about the children? We will map \DD{fun} on them too and collect the result into a new children array. They will have the same type: \DD{Tree!(B)}. If the mapped \DD{Tree} is a leaf (ie: if it has no children), the process will stop.

Since this is a recursive template,\index{recursion} we have to help the compiler a bit with the return type. Here we go:\footnote{ The difference with Phobos\index{Phobos} \DD{map} is that our version isn't lazy.}

\index{templated method}
\begin{dcode}
module tree4;
import std.array;

auto tree(T)(T value, Tree!T[] children = null) 
{
    return Tree!(T)(value, children);
}

struct Tree(T)
{
    alias T Type;
    T value;
    Tree[] children;

    bool isLeaf() @property { return children.empty;}

    Tree!(typeof(fun(T.init))) map(alias fun)()
    {
        alias typeof(fun(T.init)) MappedType;
        MappedType mappedValue = fun(value);
        Tree!(MappedType)[] mappedChildren;
        foreach(child; children) mappedChildren ~= child.map!(fun);
        return tree(mappedValue, mappedChildren);
    }
}
\end{dcode}

Let's use it:

\begin{dcode}
module using_tree4;
import std.conv;
import tree4;

int addOne(int a) { return a+1;}

void main()
{
    auto t0 = tree(0);
    auto t1 = tree(1, [t0,t0]);
    auto t2 = tree(2, [t1, t0, tree(3)]);

/* t2 is       2
             / | \
            1  0  3
           / \
          0   0
*/

    // t2 is a Tree!(int)
    static assert(is( t2.Type == int ));

    // Adding one to all values
    
    auto t3 = t2.map!(addOne);
    
/* t3 is       3
             / | \
            2  1  4
           / \
          1   1
*/

    assert(t3.value == 3);

    // Converting all values to strings
    auto ts = t2.map!(to!string); // we convert every value into a string;
    
/* ts is      "2"
             / | \
           "1""0""3"
           / \
         "0"  "0"
*/

    assert(is( ts.Type == string ));
    assert(ts.value == "2");
}
\end{dcode}

\paragraph{Folding a Tree} You may feel \DD{map} is not really a member function: it does not take any argument. Let's make another transformation on \DD{Tree}s: folding them, that is: collapsing all values into a new one. The range equivalent is \stdanchor{algorithm}{reduce} which collapses an entire (linear) range\index{range} into one value, be it a numerical value, another range or what have you

For a tree, folding can for example generate all values in pre-order or post-order, calculate the height of the tree, the number of leaves\ldots As for ranges, folding is an extremely versatile function. It can in fact be used to convert a \DD{Tree} into an array or another \DD{Tree}. We will do just that.

Taking inspiration from \DD{reduce}, we need an seed value and \emph{two} folding functions. The first one, \DD{ifLeaf}, will be called on childless nodes, for \DD{fold} to return \DD{ifLeaf(value, seed)}. The second one, \DD{ifBranch}, will be called nodes with children. In this case, we first apply \DD{fold} on all children and then return \DD{ifBranch(value, foldedChildren)}. In some simple cases, we can use the same function, hence a default case for \DD{ifBranch}. Here is the code:\footnote{ Technically, \stdanchor{algorithm}{reduce} is a \emph{left fold}, while what is shown here is a \emph{right fold}. The difference is not essential to this document.} 

\index{templated method}
\begin{dcode}
module tree5;
import std.array;

auto tree(T)(T value, Tree!T[] children = null) 
{
    return Tree!(T)(value, children);
}

struct Tree(T)
{
    alias T Type;
    T value;
    Tree[] children;

    bool isLeaf() @property { return children.empty;}

    auto fold(alias ifLeaf, alias ifBranch = ifLeaf, S)(S seed)
    {
        if (isLeaf)
        {
            return ifLeaf(value, seed);
        }
        else
        {
            typeof(Tree.init.fold!(ifLeaf, ifBranch)(seed))[] foldedChildren;
            foreach(child; children) 
                foldedChildren ~= child.fold!(ifLeaf, ifBranch)(seed);
            return ifBranch(value, foldedChildren);
        }
    }
}
\end{dcode}

Let's play a bit with it. First, we want to sum all values of a tree. For leaves, we just return the node's \DD{value} plus \DD{seed}. For branches, we are given \DD{value} and an array containing the sums of values for all children. We need to sum the values of this array, add it to the node's \DD{value} and return that. In that case, we do not about the seed value.

\begin{dcode}
module summingtree;
import std.algorithm;
import tree5;

auto sumLeaf(T, S)(T value, S seed)
{
    return value + seed;
}

auto sumBranch(T)(T value, T[] summedChildren)
{
    return value + reduce!"a+b"(summedChildren);
}

import std.stdio;

void main()
{
    auto t0 = tree(0);
    auto t1 = tree(1, [t0,t0]);
    auto t2 = tree(2, [t1, t0, tree(3)]);

    auto sum = t2.fold!(sumLeaf, sumBranch)(0);
    assert(sum == 2 + (1 + 0 + 0) + (0) + (3));
}
\end{dcode}

In the same family, but a bit more interesting is getting all values for in-order iteration: given a tree node, return an array containing the local value and then the values for all nodes, recursively.

\begin{dcode}
module inordertree;
import std.algorithm;
import tree5;

T[] inOrderL(T, S)(T value, S seed)
{
    return [value] ~ seed;
}

T[] inOrderB(T)(T value, T[][] inOrderChildren)
{
    return [value] ~ reduce!"a~b"(inOrderChildren);
}

void main()
{
    auto t0 = tree(0);
    auto t1 = tree(1, [t0,t0]);
    auto t2 = tree(2, [t1, t0, tree(3)]);

    int[] seed; // empty array
    auto inOrder = t2.fold!(inOrderL, inOrderB)(seed);
    assert(inOrder == [2, 1, 0, 0, 0, 3]);
}
\end{dcode}

And as a last use, why not build a tree? 

\TODO{Write just that.}

\subsection{Templated Constructors}\label{constructortemplates}

Struct constructors are member function, so they can be templated too. They need not have the same template parameters as the struct definition:

\index{syntax!templated constructors}
\begin{dcode}
module templatedconstructors;

struct S(T)
{
    this(U)(U u) { /*...*/ }
}

void main()
{
    auto s = S!string(1); // T is string, U is int.
}
\end{dcode}

As you can see, IFTI (\ref{ifti})\index{IFTI!for constructors} works for constructors. \DD{U} is automatically deduced, though you have to indicate \DD{T} in this case. However, this example is drastically limited: you cannot have any value of type \DD{U} in the struct, because \DD{U} does not exist outside the constructor. A bit more useful would be to collect an alias (a function, for example) and use it to initialize the struct. If it's used only for initialization, it can be discarded afterwards. But then, IFTI is not activated by an alias\ldots

The most interesting use I've seen is to make conversions during the struct's construction:

\index{templated constructor}
\index{constructor}
\begin{dcode}
module holder;
import std.conv;

struct Holder(Type)
{
    Type value;

    this(AnotherType)(AnotherType _value)
    {
        value = to!Type(_value);
    }
}

void main()
{
    Holder!int h = Holder!int(3.14);
    assert(h.value == 3);
}
\end{dcode}

That way, a \DD{Holder!int} can be constructed with any value, but if the conversion is possible, it will always hold an \D{int}.

\subsection{Inner Structs}\label{innerstructs}

You can create and return inner structs and use the local template parameters in their definition. We could have a factory function for \DD{Heap} like this:

\index{inner struct}
\index{template!parameters!alias}
\begin{dcode}
module heap2;

auto heap(alias predicate, Type)(Type[] values)
{
    struct Heap
    {
        Type[] values;
        this(Type[] _values)
        {
            /* some code initializing values using predicate */
        }
        /* more heapy code */
    }

    return Heap(values); // alias predicate is implicit there
}
\end{dcode}

In that case, the \DD{Heap} struct is encapsulated inside \DD{heap} and uses the \DD{predicate} alias inside its own engine, but it's not a templated struct itself. I did not use \DD{Tree} as an example, because with recursive types it becomes tricky.

By the way, strangely enough, though you cannot declare `pure' templates inside functions, you can declare struct templates. Remember the \DD{adder} function in section \ref{anonymousfunctions}? It didn't need to be templated with one type for each argument, as most of the time when you add numbers, they have more or less the same type. But what about a function that converts its arguments to \D{string}s before concatenating them?

\begin{dcode}
module anonymous_error;

auto concatenate(A)(A a)
{
    /* !! Not legal D code !! */
    return (B)(B b) { return to!string(a) ~ to!string(b);};
}
\end{dcode}

The previous example is not legal D code (remember \ref{mantra}).\index{mantra} Of course, there is a solution: just return a struct with a template member function (\ref{membertemplates}), in that case the \DD{opCall} operator:

\index{inner struct}
\index{templated method}
\index{opCall, ()@\DD{opCall}, \DD{()}}
\index{operator!opCall, ()@\DD{opCall}, \DD{()}}
\begin{dcode}
module innerconcatenate;
import std.conv;

auto concatenate(A)(A a)
{
    struct Concatenator 
    {
        A a;

        auto opCall(B)(B b) @trusted
        {
            return to!string(a) ~ to!string(b);
        }
    }

    Concatenator c;
    c.a = a; // So as not to activate opCall()

    return c;
}

void main()
{
    auto c = concatenate(3.14);
    auto cc = c("abc");
    assert(cc == "3.14abc");
}
\end{dcode}

See section \ref{operatoroverloading} for more on operator overloading.

What about templated inner structs inside struct templates? It's perfectly legal:

\index{inner struct!templated}
\begin{dcode}
module templatedinner;

struct Outer(O)
{
    O o;

    struct Inner(I)
    {
        O o;
        I i;
    }

    auto inner(I)(I i) { return Inner!(I)(o,i);}
}

auto outer(O)(O o) { return Outer!(O)(o);}
    
void main()
{
    auto o = outer(1); // o is an Outer!int;
    auto i = o.inner("abc"); // Outer.Outer!(int).Inner.Inner!(string)
}
\end{dcode}

\subsection{Template This Parameters}\label{this}

\unfinished{Some kind of example would be great here.}

Inside a struct or class template, there is another kind of template parameter: the template this parameter,\index{template!parameters!template this parameter} declared with \D{this} \DD{identifier}. \DD{identifier} then gets the type of the \D {this} reference. It's useful mainly for two uses:

\begin{itemize}
\item mixin templates (\ref{mixintemplates}), where you do not know the enclosing type beforehand. Please see this section for some examples.
\item to determine how the type of the \D{this} reference is qualified (\D{const}, \D{immutable}, \D{shared}, \D{inout} or unqualified).
\end{itemize}

\subsection{Example: a Concat / Flatten Range}\label{structflatten}

We will use what we've learned about struct templates to create a lazy range\index{range} that flattens ranges of ranges\index{range!of ranges} into linear ranges. Remember the \DD{flatten} function from section \ref{functionflatten}? It worked quite well but was \emph{eager}, not \emph{lazy}: given an infinite range (a cycle, for example) it would choke on it. We will here make a lazy flattener.

If you look at the ranges defined in \std{range}, you will see that most (if not all) of them are structs. That's the basic way to get laziness in D: the struct holds the iteration state and exposes the basic range primitives. At the very least to be an \emph{input range}---the simplest kind of range---a type must have the following members\index{range!members} (be they properties, member functions or manifest constants):

\begin{description}
\item[front:] returns the range's first element.
\item[popFront:] discards the first element and advances the range by one step.
\item[empty:] returns \D{true} if the range has no more elements, \D{false} otherwise.
\end{description}

From this simple basis, powerful algorithms can be designed that act on ranges. D defines more refined range concepts by adding other constraints. A \emph{forward range} adds the \DD{save} member that's used to store a range internal state and allows an algorithm to start again from a saved position. A \emph{bidirectional range} also has the \DD{back} and \DD{popBack} primitives for accessing the end of the range, and so on.

Here we will begin by creating a simple input range\index{range} that takes a range of ranges\index{range!of ranges} and iterates on the inner elements. Let's begin with the very basics:

\index{range}
\index{struct template}
\index{factory function}
\begin{dcode}
module flatten2;

import std.range;
import rank2;

struct Flatten(Range)
{
    Range range;
    /*...*/
}

auto flatten(Range)(Range range)
{ 
    static if (rank!Range == 0)
        static assert(0, "flatten needs a range.");
    else static if (rank!Range == 1)
        return range;
    else
        return Flatten!(Range)(range);
}
\end{dcode}

So we have a struct template and its associated factory function. It doesn't make sense to instantiate \DD{Flatten} with any old type, so \DD{Range} is checked to be a range, using the \DD{rank}\index{range} template we saw on page \pageref{rankforranges}. We haven't seen template constraints yet (they are described in section \ref{constraints}), but they would be a good fit here too.

A range of ranges\index{range!of ranges} can be represented like this:

\begin{dcode}
[ subRange1[elem11, elem12,...]
, subRange2[elem21, elem22,...] 
, ... ]
\end{dcode}

We want \DD{Flatten} to return elements in this order: \DD{elem11}, \DD{elem12}, \ldots  \DD{elem21}, \DD{elem22}, \ldots Note that for ranges of rank higher than 2, the \DD{elemxy}s are themselves ranges. At any given time, \DD{Flatten} is working on a sub-range, iterating on its elements and discarding it when it's empty. The iteration will stop when the last subrange has been consumed, that is when \DD{range} itself is empty.

\index{struct template}
\index{range}
\index{inner member alias}
\begin{ndcode}
module flatten3;
import std.range;

import rank2;

struct Flatten(Range)
{
    alias ElementType!Range    SubRange;
    alias ElementType!SubRange Element;

    Range range;
    SubRange subRange;

    this(Range _range) {
        range = _range;
        if (!range.empty) subRange = range.front;
    }

    Element front() { return subRange.front;}

    bool empty() { return range.empty;}

    void popFront() {
        if (!subRange.empty) subRange.popFront;
        while(subRange.empty && !range.empty) {
            range.popFront;
            if (!range.empty) subRange = range.front;
        }
    }
}
\end{ndcode}

\begin{itemize}
\item I cheat a little bit with D standard bracing style, because it eats vertical space like there is no tomorrow.
\item We begin on line 8 and 9 by defining some new types used by the methods. They are not strictly necessary but make the code easier to understand and expose these types to the outer world, if they are needed.
\item A constructor is now necessary to initialize the struct.
\item \DD{front} returns a subrange element.
\end{itemize}

But then, this only works for ranges of ranges\index{rank!of ranges} (of rank $\leq$ 2). We want something that flattens ranges of any rank down to a linear range. This is easily done, we just add recursion\index{recursion} in the factory function:\index{factory function}

\index{factory function}
\index{recursion}
\index{static if@\D{static if}}
\index{static if@\D{static if}!nested}
\begin{dcode}
module flatten4;
import rank2;
public import flatten3;

auto flatten(Range)(Range range)
{ 
    static if      (rank!Range == 0)
        static assert(0, "flatten needs a range.");
    else static if (rank!Range == 1)
        return range;
    else static if (rank!Range == 2)
        return Flatten!(Range)(range);
    else         // rank 3 or higher
        return flatten(Flatten!(Range)(range));
}
\end{dcode}

And, testing:

\index{IFTI}
\begin{dcode}
module using_flatten4;
import std.algorithm;
import std.range;
import std.string;
import rank2;
import flatten4;

void main()
{
    auto rank3 = [[[0,1,2],[3,4,5],[6] ]
                 ,[[7],[],[8,9],[10,11]]
                 ,[[],[12]             ]
                 ,[[13]                ]];

    auto rank1 = flatten(rank3);
    assert(rank!(typeof(rank1)) == 1); // Yup, it's a linear range
    assert(equal( rank1, [0,1,2,3,4,5,6,7,8,9,10,11,12,13] ));

    auto stillRank1 = flatten(rank1);
    assert(equal( stillRank1, rank1 )); // No need to insist

    auto text =
   "Sing, O goddess, the anger of Achilles son of Peleus,
    that brought countless ills upon the Achaeans.
    Many a brave soul did it send hurrying down to Hades,
    and many a hero did it yield a prey to dogs and vultures,
    for so were the counsels of Jove fulfilled
    from the day on which the son of Atreus, king of men,
    and great Achilles, first fell out with one another.";

    auto lines = text.splitLines;   // array of strings
    string[][] words;
    foreach(line; lines) words ~= array(splitter(line, ' '));
    assert( rank!(typeof(words)) == 3); // range of range of strings
                                        // range of range of array of chars
    auto flat = flatten(words);

    assert(equal(take(flat, 50), 
             "Sing,Ogoddess,theangerofAchillessonofPeleus,thatbr"));
}
\end{dcode}

Here it is. It works and we used a struct template (this section, \ref{structtemplates}), \D{static if} (\ref{staticif}), inner member alias (\ref{inneralias}), factory functions (\ref{factory}) and IFTI (\ref{ifti}).

\section{Class Templates}\label{classtemplates}

\aparte{This Section Needs You!}{I'm not an OOP programmer and am not used to create interesting hierarchies. If anyone reading this has an example of class templates that could be used throughout the section, I'm game.}

\subsection{Syntax}\label{classsyntax}

No surprise here, just put the template parameters list between \D{class} and the optional inheritance indication:

\index{syntax!class templates}
\begin{dcode}
module classsyntax1;

class Base {}
interface Interface1 {}
interface Interface2 {}

class MyClass(Type, alias fun, bool b = false)
    : Base, Interface1, Interface2
{ /*...*/ }
\end{dcode}

What's more fun is that you can have parameterized inheritance: the various template parameters are defined before the base class list, you can use them here:

\index{syntax!class templates!parameterized inheritance}
\begin{dcode}
module classsyntax2;

class Base(T) {}
interface Interface1 {}
interface Interface2(alias fun, bool b) {}

class MyClass(Type, alias fun, bool b = false)
    : Base!(Type), Interface1, Interface2!(fun,b)
{ /*...*/ }
\end{dcode}

\aparte{Interface Templates?}{Yes you can. See section \ref{othertemplates}}

This opens interesting vistas, where what a class inherits is determined by its template arguments (since \DD{Base} may be many different classes or even interfaces depending on \DD{Type}). In fact, look at this:

\begin{dcode}
module classsyntax3;

enum WhatBase { Object, Interface, BaseClass }

template Base(WhatBase whatBase = WhatBase.Object)
{
    static if (is(T == WhatBase.Object))
        alias Object Base; // MyClass inherits directly from Object
    else static if(is(T == WhatBase.Interface))
        alias TheInterface Base;
    else
        alias TheBase Base;
}

class MyClass(Type) : Base!Type {}
\end{dcode}

With this, \DD{MyClass} can inherit from \DD{Object}, the root of D's class hierarchy, from an interface, or from another class. Obviously, the dispatching template could be much more refined. With a second template parameter, the base class could itself be parameterized, and so on.

What this syntax \emph{cannot} do however is change the number of interfaces at compile-time.\footnote{ Except, maybe, by having an interface template be empty for certain parameters, thus in effect disappearing from the list.} It's complicated to say: `with \emph{this} argument, \DD{MyClass} will inherit from \DD{I}, \DD{J} and \DD{K} and with \emph{that} argument, it will inherit only from \DD{L}.' You'd need the previous interfaces to all participate in the action, to all be templates and such. If the needed interfaces are all pre-defined and not templated, you need wrapping templates. It's a pain. However, type tuples can be used to greatly simplify this (see section \ref{inheritancelist} for an example).

\subsection{Methods Templates}\label{methodtemplates}

An object's methods are nothing more than delegates with a reference to the local \D{this} context. As seen for structs (\ref{membertemplates}), methods can be templates too.

\unfinished{I need to write something on overriding methods with templates. Also, I need to find some interesting method example. Man, I do not do classes.}

\subsection{\texorpdfstring{\D{invariant} clauses}
                           {invariant clauses}}
\label{classinvariant}

In the same family than \D{in}/f\D{out} clauses for functions (section \ref{inandoutclauses}), a class template's \D{invariant} clause has access to the template parameter. You cannot make it disappear totally, but you can get it to be empty with a \D{static if} statement.

\index{class template!invariant}
\index{static if@\D{static if}!enabling/disabling code!invariant clause@\D{invariant} clause}
\begin{dcode}
module classinvariant;

class MyClass(T, U, V)
{
    /*...*/

    invariant ()
    {
        static if (is(T == U))
        {
            /* invariant code */
        }
        else
        { } /* empty invariant */
    }
}
\end{dcode}

\subsection{Inner Classes}\label{innerclasses}

It's the same principle as for structs (\ref{innerstructs}). You can define inner classes using the template parameters. You can even give them method templates that use other template arguments. There is really nothing different from inner structs.

\subsection{Anonymous Classes}\label{anonymousclasses}

In D, you can return anonymous classes\index{anonymous!classes} directly from a function or a method. Can these be templated? Well, they cannot be class templates, that wouldn't make sense.\index{mantra} But you can return anonymous classes with templated methods, if you really need to.

\index{anonymous!class templates}
\begin{dcode}
module anonymousclass;

// stores a function and a default return value.
auto acceptor(alias fun, D)(D defaultValue)
{
    return new class 
    { 
        this() {}
        
        auto opCall(T)(T t)
        {
            static if (__traits(compiles, fun(T.init)))
                return fun(t); 
            else
                return defaultValue;
        }
    };
}

unittest
{
    int add1(int i) { return i+1;}
    auto accept = acceptor!(add1)(-1);
    
    auto test1 = accept(10); 
    assert(test1 == 11);

    auto test2 = accept("abc");
    assert(test2 == -1); // default value
}
\end{dcode}

For \D{\_\_traits}\DD{(compiles, ...)},\index{\_\_traits@\D{\_\_traits}} see \href{www.dlang.org/traits.html}{here} online and section \ref{traits} in this document.

\subsection{Parametrized Base Class}

You can use a template parameter directly as a base class:

\index{parametrized base class}
\index{template!parameters!as a base class}
\begin{dcode}
module parametrizedbaseclass;

interface ISerializable
{
    size_t serialize() @property;
}

class Serializable(T) : T, ISerializable
{
    size_t serialize() @property 
    {
        return this.tohash; 
    }
} 
\end{dcode}

In this example, a \DD{Serializable!SomeClass} can act as a \DD{SomeClass}. It's not different from what you would do with normal classes except the idiom\index{idiom!parameterized base class} is now abstracted on the base class: you write the template once, it can then be used on any class.

If you have different interfaces like this, you can nest these properties:

\index{nested templates instantiations}
\begin{dcode}
auto wrapped = new Serializable!(Iterable!(SomeClass))(/*...*/);
\end{dcode}

Of course, the base class and the interface may themselves be parameterized:

\begin{dcode}
module serializetemplate;

enum SerializationPolicy { policy1, policy2 }

interface ISerializable 
(SerializationPolicy policy = SerializationPolicy.policy1)
{
    static if (is(policy == SerializationPolicy.policy1))
        void serialize() { /*...*/ }
    else
        void serialize() { /*...*/ }
}

class Serializable(T, Policy) : T, ISerializable!Policy
{
    /*...*/
} 
\end{dcode}

In D, you can also get this kind of effect with an \D{alias X this;} declaration in your class or struct. You should also have a look at mixin templates (\ref{mixintemplates}) and wrapper templates (\ref{wrappertemplates}) for other idioms built around the same need. 

\subsection{Adding Functionalities through inheritance}
\label{functionalityinheritance}

Here is an example taken from Timon Gehr. Given a base class \DD{Cell} with a private field and get/set methods, it's possible to provide additional functionalities through inheritance. By defining templates for \DD{Cell} subclasses, each with a new possibility (doubling the value, logging the value, etc.), it's possible to select those new actions by inheritance:

\begin{dcode}
/**
 * Timon Gehr timon.gehr@gmx.ch via puremagic.com 
 */
module inheritanceexample;

import std.stdio;

abstract class Cell(T)
{
    abstract void set(T value);
    abstract const(T) get();
private:
    T field;
}

class AddSetter(C: Cell!T,T): C
{
    override void set(T value){field = value;}
}
class AddGetter(C: Cell!T,T): C
{
    override const(T) get(){return field;}
}

class DoubleCell(C: Cell!T,T): C
{
    override void set(T value){super.set(2*value);}
}

class OneUpCell(C: Cell!T,T): C
{
    override void set(T value){super.set(value+1);} 
}

class SetterLogger(C:Cell!T,T): C
{
    override void set(T value)
    {
        super.set(value);
        writeln("cell has been set to '",value,"'!");
    }
}

class GetterLogger(C:Cell!T,T): C
{
    override const(T) get()
    {
        auto value = super.get();
        writeln("'",value,"' has been retrieved!");
        return value;
    }
}

// ConcreteCell has a 'true' getter and a 'true' setter
class ConcreteCell(T): AddGetter!(AddSetter!(Cell!T)){}
// OneUpDoubleSetter has a setter that adds 1 to the stored value and then doubles it
class OneUpDoubleSetter(T): OneUpCell!(DoubleCell!(AddSetter!(Cell!T))){}
// doubleOneUpSetter has a setter that doubles the stored value and add 1
class DoubleOneUpSetter(T): DoubleCell!(OneUpCell!(AddSetter!(Cell!T))){}

void main()
{
    Cell!string x;
    x = new ConcreteCell!string;
    x.set("hello");
    writeln(x.get());
    
    Cell!int y;
    y = new SetterLogger!(ConcreteCell!int);
    y.set(123); // prints: "cell has been set to '123'!
       
    y = new GetterLogger!(DoubleCell!(ConcreteCell!int));
    y.set(1234);
    y.get(); // prints "'2468' has been retrieved!"

    y = new AddGetter!(OneUpDoubleSetter!int);
    y.set(100);
    writeln(y.get()); // prints "202"
    y = new AddGetter!(DoubleOneUpSetter!int);
    y.set(100);
    writeln(y.get()); // prints "201"
}
\end{dcode}
For those of you knowing the Scala programming language, this is a bit reminiscent of \emph{traits}, which in Scala a sort-of stub classes that can be added to class to provide new functions. In D, apart from the above feature, you can also use mixin templates (\ref{mixintemplates}) and string mixins (\ref{stringmixins}).


\subsection{The Curiously Recurring Template Pattern}

\begin{dcode}
module crtp;

class Base(Child) { /*...*/ }

class Derived : Base!Derived { /*...*/ }
\end{dcode}

Hold on, what does that mean? \DD{Base} is easy to understand. But what about \DD{Derived}? It says it inherits from another class that is templated on\ldots \DD{Derived} \emph{itself}? But \DD{Derived} is not defined at this stage! Or is it? 
Yes, that works. It's called CRTP, which stands for Curiously Recurring Template Pattern\index{Curiously Recurring Template Pattern} (see \href{ http://en.wikipedia.org/wiki/Curiously_recurring_template_pattern}{Wikipedia} on this). But what could be the interest of such a trick?

As you can see in the Wikipedia document it's used either to obtain a sort of compile-time binding or to inject code in your derived class. For the latter, D offers mixin templates (\ref{mixintemplates}) which you should have a look at. CRTP comes from C++\index{C++!CRTP} where you have multiple inheritance. In D, I fear it's not so interesting. Feel free to prove me wrong, I'll gladly change this section.

\subsection{Example}

\unfinished{ I want to add an example with \DD{duplicator}, a template that takes a class and creates another class which is its clone: same base, same interfaces, etc.}


\section{Other Templates?}\label{othertemplates}

Two other aggregate types in D can be templated using the same syntax: interfaces and unions.

\subsection{Interface Templates}

The syntax is exactly what you might imagine: 

\index{syntax!interface templates}
\begin{dcode}
module interfacesyntax;

interface Interf(T)
{
    T foo(T);
    T[] bar(T,int);
}
\end{dcode}

Templated interfaces are sometimes useful but as they look very much like class templates, I won't describe them. As before, remember The Mantra (see page \pageref{mantra}\index{mantra}): interface templates are \emph{not} interfaces.

\subsection{Union Templates}

Here is the syntax, no suprise there:

\index{syntax!union templates}
\begin{dcode}
module unionsyntax;

union Union(A,B,C) { A a; B b; C c;}
\end{dcode}

Union templates seem like a good idea, but honestly I've never seen one. Any reader of this document, please give me an example if you know one. 

Strangely, enumerations do not have the previous simplified syntax. To declare a templated enumeration, use the eponymous template trick:

\index{syntax!enum template}
\index{enum template}
\begin{dcode}
module enumsyntax;

template Enum(T)
{
    enum Enum : T { A, B, C}
}
\end{dcode}