1namespace Eigen {
2
3/** \page TopicPitfalls Common pitfalls
4
5\section TopicPitfalls_template_keyword Compilation error with template methods
6
7See this \link TopicTemplateKeyword page \endlink.
8
9\section TopicPitfalls_auto_keyword C++11 and the auto keyword
10
11In short: do not use the auto keywords with Eigen's expressions, unless you are 100% sure about what you are doing. In particular, do not use the auto keyword as a replacement for a Matrix<> type. Here is an example:
12
13\code
14MatrixXd A, B;
15auto C = A*B;
16for(...) { ... w = C * v;  ...}
17\endcode
18
19In this example, the type of C is not a MatrixXd but an abstract expression representing a matrix product and storing references to A and B. Therefore, the product of A*B will be carried out multiple times, once per iteration of the for loop. Moreover, if the coefficients of A or B change during the iteration, then C will evaluate to different values.
20
21Here is another example leading to a segfault:
22\code
23auto C = ((A+B).eval()).transpose();
24// do something with C
25\endcode
26The problem is that eval() returns a temporary object (in this case a MatrixXd) which is then referenced by the Transpose<> expression. However, this temporary is deleted right after the first line, and there the C expression reference a dead object. The same issue might occur when sub expressions are automatically evaluated by Eigen as in the following example:
27\code
28VectorXd u, v;
29auto C = u + (A*v).normalized();
30// do something with C
31\endcode
32where the normalized() method has to evaluate the expensive product A*v to avoid evaluating it twice. On the other hand, the following example is perfectly fine:
33\code
34auto C = (u + (A*v).normalized()).eval();
35\endcode
36In this case, C will be a regular VectorXd object.
37*/
38}
39