Docs: aliasing and component-wise operations.

2 files changed, 40 insertions, 1 deletions

diff --git a/doc/I11_Aliasing.dox b/doc/I11_Aliasing.dox
index 04a24bded..c7e984cf3 100644
--- a/doc/I11_Aliasing.dox
+++ b/doc/I11_Aliasing.dox
@@ -128,7 +128,26 @@ functions provided:
 
 \section TopicAliasingCwise Aliasing and component-wise operations
 
-Synopsis: Things like mat = 2 * mat, matA = matA + matB and arr = arr.sin() are safe.
+As explained above, it may be dangerous if the same matrix or array occurs on both the left-hand side and the
+right-hand side of an assignment operator, and it is then often necessary to evaluate the right-hand side
+explicitly. However, applying component-wise operations (such as matrix addition, scalar multiplication and
+array multiplication) is safe. 
+
+The following example has only component-wise operations. Thus, there is no need for .eval() even though
+the same matrix appears on both sides of the assignments.
+
+<table class="example">
+<tr><th>Example</th><th>Output</th></tr>
+<tr><td>
+\include TopicAliasing_cwise.cpp
+</td>
+<td>
+\verbinclude TopicAliasing_cwise.out
+</td></tr></table>
+
+In general, an assignment is safe if the (i,j) entry of the expression on the right-hand side depends only on
+the (i,j) entry of the matrix or array on the left-hand side and not on any other entries. In that case it is
+not necessary to evaluate the right-hand side explicitly.
 
 
 \section TopicAliasingMatrixMult Aliasing and matrix multiplication
diff --git a/doc/snippets/TopicAliasing_cwise.cpp b/doc/snippets/TopicAliasing_cwise.cpp
new file mode 100644
index 000000000..7049f6c56
--- /dev/null
+++ b/doc/snippets/TopicAliasing_cwise.cpp
@@ -0,0 +1,20 @@
+MatrixXf mat(2,2); 
+mat << 1, 2,  4, 7;
+cout << "Here is the matrix mat:\n" << mat << endl << endl;
+
+mat = 2 * mat;
+cout << "After 'mat = 2 * mat', mat = \n" << mat << endl << endl;
+
+
+mat = mat - MatrixXf::Identity(2,2);
+cout << "After the subtraction, it becomes\n" << mat << endl << endl;
+
+
+ArrayXXf arr = mat;
+arr = arr.square();
+cout << "After squaring, it becomes\n" << arr << endl << endl;
+
+// Combining all operations in one statement:
+mat << 1, 2,  4, 7;
+mat = (2 * mat - MatrixXf::Identity(2,2)).array().square();
+cout << "Doing everything at once yields\n" << mat << endl << endl;