1namespace Eigen { 2 3/** \page TopicTemplateKeyword The template and typename keywords in C++ 4 5There are two uses for the \c template and \c typename keywords in C++. One of them is fairly well known 6amongst programmers: to define templates. The other use is more obscure: to specify that an expression refers 7to a template function or a type. This regularly trips up programmers that use the %Eigen library, often 8leading to error messages from the compiler that are difficult to understand. 9 10<b>Table of contents</b> 11 - \ref TopicTemplateKeywordToDefineTemplates 12 - \ref TopicTemplateKeywordExample 13 - \ref TopicTemplateKeywordExplanation 14 - \ref TopicTemplateKeywordResources 15 16 17\section TopicTemplateKeywordToDefineTemplates Using the template and typename keywords to define templates 18 19The \c template and \c typename keywords are routinely used to define templates. This is not the topic of this 20page as we assume that the reader is aware of this (otherwise consult a C++ book). The following example 21should illustrate this use of the \c template keyword. 22 23\code 24template <typename T> 25bool isPositive(T x) 26{ 27 return x > 0; 28} 29\endcode 30 31We could just as well have written <tt>template <class T></tt>; the keywords \c typename and \c class have the 32same meaning in this context. 33 34 35\section TopicTemplateKeywordExample An example showing the second use of the template keyword 36 37Let us illustrate the second use of the \c template keyword with an example. Suppose we want to write a 38function which copies all entries in the upper triangular part of a matrix into another matrix, while keeping 39the lower triangular part unchanged. A straightforward implementation would be as follows: 40 41<table class="example"> 42<tr><th>Example:</th><th>Output:</th></tr> 43<tr><td> 44\include TemplateKeyword_simple.cpp 45</td> 46<td> 47\verbinclude TemplateKeyword_simple.out 48</td></tr></table> 49 50That works fine, but it is not very flexible. First, it only works with dynamic-size matrices of 51single-precision floats; the function \c copyUpperTriangularPart() does not accept static-size matrices or 52matrices with double-precision numbers. Second, if you use an expression such as 53<tt>mat.topLeftCorner(3,3)</tt> as the parameter \c src, then this is copied into a temporary variable of type 54MatrixXf; this copy can be avoided. 55 56As explained in \ref TopicFunctionTakingEigenTypes, both issues can be resolved by making 57\c copyUpperTriangularPart() accept any object of type MatrixBase. This leads to the following code: 58 59<table class="example"> 60<tr><th>Example:</th><th>Output:</th></tr> 61<tr><td> 62\include TemplateKeyword_flexible.cpp 63</td> 64<td> 65\verbinclude TemplateKeyword_flexible.out 66</td></tr></table> 67 68The one line in the body of the function \c copyUpperTriangularPart() shows the second, more obscure use of 69the \c template keyword in C++. Even though it may look strange, the \c template keywords are necessary 70according to the standard. Without it, the compiler may reject the code with an error message like "no match 71for operator<". 72 73 74\section TopicTemplateKeywordExplanation Explanation 75 76The reason that the \c template keyword is necessary in the last example has to do with the rules for how 77templates are supposed to be compiled in C++. The compiler has to check the code for correct syntax at the 78point where the template is defined, without knowing the actual value of the template arguments (\c Derived1 79and \c Derived2 in the example). That means that the compiler cannot know that <tt>dst.triangularPart</tt> is 80a member template and that the following < symbol is part of the delimiter for the template 81parameter. Another possibility would be that <tt>dst.triangularPart</tt> is a member variable with the < 82symbol refering to the <tt>operator<()</tt> function. In fact, the compiler should choose the second 83possibility, according to the standard. If <tt>dst.triangularPart</tt> is a member template (as in our case), 84the programmer should specify this explicitly with the \c template keyword and write <tt>dst.template 85triangularPart</tt>. 86 87The precise rules are rather complicated, but ignoring some subtleties we can summarize them as follows: 88- A <em>dependent name</em> is name that depends (directly or indirectly) on a template parameter. In the 89 example, \c dst is a dependent name because it is of type <tt>MatrixBase<Derived1></tt> which depends 90 on the template parameter \c Derived1. 91- If the code contains either one of the contructions <tt>xxx.yyy</tt> or <tt>xxx->yyy</tt> and \c xxx is a 92 dependent name and \c yyy refers to a member template, then the \c template keyword must be used before 93 \c yyy, leading to <tt>xxx.template yyy</tt> or <tt>xxx->template yyy</tt>. 94- If the code contains the contruction <tt>xxx::yyy</tt> and \c xxx is a dependent name and \c yyy refers to a 95 member typedef, then the \c typename keyword must be used before the whole construction, leading to 96 <tt>typename xxx::yyy</tt>. 97 98As an example where the \c typename keyword is required, consider the following code in \ref TutorialSparse 99for iterating over the non-zero entries of a sparse matrix type: 100 101\code 102SparseMatrixType mat(rows,cols); 103for (int k=0; k<mat.outerSize(); ++k) 104 for (SparseMatrixType::InnerIterator it(mat,k); it; ++it) 105 { 106 /* ... */ 107 } 108\endcode 109 110If \c SparseMatrixType depends on a template parameter, then the \c typename keyword is required: 111 112\code 113template <typename T> 114void iterateOverSparseMatrix(const SparseMatrix<T>& mat; 115{ 116 for (int k=0; k<m1.outerSize(); ++k) 117 for (typename SparseMatrix<T>::InnerIterator it(mat,k); it; ++it) 118 { 119 /* ... */ 120 } 121} 122\endcode 123 124 125\section TopicTemplateKeywordResources Resources for further reading 126 127For more information and a fuller explanation of this topic, the reader may consult the following sources: 128- The book "C++ Template Metaprogramming" by David Abrahams and Aleksey Gurtovoy contains a very good 129 explanation in Appendix B ("The typename and template Keywords") which formed the basis for this page. 130- http://pages.cs.wisc.edu/~driscoll/typename.html 131- http://www.parashift.com/c++-faq-lite/templates.html#faq-35.18 132- http://www.comeaucomputing.com/techtalk/templates/#templateprefix 133- http://www.comeaucomputing.com/techtalk/templates/#typename 134 135*/ 136} 137