improvements in tutorial page 4 : block operations

4 files changed, 52 insertions, 57 deletions

diff --git a/doc/C04_TutorialBlockOperations.dox b/doc/C04_TutorialBlockOperations.dox
index b45cbfbc8..ce6bc4717 100644
--- a/doc/C04_TutorialBlockOperations.dox
+++ b/doc/C04_TutorialBlockOperations.dox
@@ -21,13 +21,12 @@ provided that you let your compiler optimize.
 \section TutorialBlockOperationsUsing Using block operations
 
 The most general block operation in Eigen is called \link DenseBase::block() .block() \endlink.
-This function returns a block of size <tt>(p,q)</tt> whose origin is at <tt>(i,j)</tt>.
 There are two versions, whose syntax is as follows:
 
 <table class="tutorial_code" align="center">
 <tr><td align="center">\b %Block \b operation</td>
-<td align="center">Default version</td>
-<td align="center">Optimized version when the<br>size is known at compile time</td></tr>
+<td align="center">Version constructing a dynamic-size block expression</td>
+<td align="center">Version constructing a fixed-size block expression</td></tr>
 <tr><td>%Block of size <tt>(p,q)</tt>, starting at <tt>(i,j)</tt></td>
     <td>\code
 matrix.block(i,j,p,q);\endcode </td>
@@ -36,13 +35,14 @@ matrix.block<p,q>(i,j);\endcode </td>
 </tr>
 </table>
 
-The default version is a method which takes four arguments. It can always be used. The optimized version
-takes two template arguments (the size of the block) and two normal arguments (the position of the block).
-It can only be used if the size of the block is known at compile time, but it may be faster than the
-non-optimized version, especially if the size of the block is small. Both versions can be used on fixed-size
-and dynamic-size matrices and arrays.
+As always in Eigen, indices start at 0.
 
-The following program uses the default and optimized versions to print the values of several blocks inside a
+Both versions can be used on fixed-size and dynamic-size matrices and arrays.
+These two expressions are semantically equivalent.
+The only difference is that the fixed-size version will typically give you faster code if the block size is small,
+but requires this size to be known at compile time.
+
+The following program uses the dynamic-size and fixed-size versions to print the values of several blocks inside a
 matrix.
 
 <table class="tutorial_code"><tr><td>
@@ -53,15 +53,10 @@ Output:
 \verbinclude Tutorial_BlockOperations_print_block.out
 </td></tr></table>
 
-In the above example the \link DenseBase::block() .block() \endlink function was employed 
-to read the values inside matrix \p m . However, blocks can also be used as lvalues, meaning that you can
-assign to a block. 
+In the above example the \link DenseBase::block() .block() \endlink function was employed as a \em rvalue, i.e.
+it was only read from. However, blocks can also be used as \em lvalues, meaning that you can assign to a block.
 
-This is illustrated in the following example, which uses arrays instead of matrices.  The coefficients of the
-5-by-5 array \c n are first all set to 0.6, but then the 3-by-3 block in the middle is set to the values in 
-\c m . The penultimate line shows that blocks can be combined with matrices and arrays to create more complex
-expressions. Blocks of an array are an array expression, and thus the multiplication here is coefficient-wise
-multiplication.
+This is illustrated in the following example. This example also demonstrates blocks in arrays, which works exactly like the above-demonstrated blocks in matrices.
 
 <table class="tutorial_code"><tr><td>
 \include Tutorial_BlockOperations_block_assignment.cpp
@@ -71,38 +66,34 @@ Output:
 \verbinclude Tutorial_BlockOperations_block_assignment.out
 </td></tr></table>
 
-The \link DenseBase::block() .block() \endlink method is used for general block operations, but there are
-other methods for special cases. These are described in the rest of this page.
+While the \link DenseBase::block() .block() \endlink method can be used for any block operation, there are
+other methods for special cases, providing more specialized API and/or better performance. On the topic of performance, all what
+matters is that you give Eigen as much information as possible at compile time. For example, if your block is a single whole column in a matrix,
+using the specialized \link DenseBase::col() .col() \endlink function described below lets Eigen know that, which can give it optimization opportunities.
 
+The rest of this page describes these specialized methods.
 
 \section TutorialBlockOperationsSyntaxColumnRows Columns and rows
 
-Individual columns and rows are special cases of blocks. Eigen provides methods to easily access them:
-\link DenseBase::col() .col() \endlink and \link DenseBase::row() .row()\endlink. There is no syntax variant
-for an optimized version.
+Individual columns and rows are special cases of blocks. Eigen provides methods to easily address them:
+\link DenseBase::col() .col() \endlink and \link DenseBase::row() .row()\endlink.
 
 <table class="tutorial_code" align="center">
 <tr><td align="center">\b %Block \b operation</td>
-<td align="center">Default version</td>
-<td align="center">Optimized version when the<br>size is known at compile time</td></tr>
+<td align="center">Method</td>
 <tr><td>i<sup>th</sup> row
                     \link DenseBase::row() * \endlink</td>
     <td>\code
 matrix.row(i);\endcode </td>
-    <td>\code 
-matrix.row(i);\endcode </td>
 </tr>
 <tr><td>j<sup>th</sup> column
                     \link DenseBase::col() * \endlink</td>
     <td>\code
 matrix.col(j);\endcode </td>
-    <td>\code 
-matrix.col(j);\endcode </td>
 </tr>
 </table>
 
-The argument for \p col() and \p row() is the index of the column or row to be accessed, starting at
-0. Therefore, \p col(0) will access the first column and \p col(1) the second one.
+The argument for \p col() and \p row() is the index of the column or row to be accessed. As always in Eigen, indices start at 0.
 
 <table class="tutorial_code"><tr><td>
 C++ code:
@@ -113,22 +104,21 @@ Output:
 \verbinclude Tutorial_BlockOperations_colrow.out
 </td></tr></table>
 
+That example also demonstrates that block expressions (here columns) can be used in arithmetic like any other expression.
+
 
 \section TutorialBlockOperationsSyntaxCorners Corner-related operations
 
 Eigen also provides special methods for blocks that are flushed against one of the corners or sides of a
 matrix or array. For instance, \link DenseBase::topLeftCorner() .topLeftCorner() \endlink can be used to refer
-to a block in the top-left corner of a matrix. Use <tt>matrix.topLeftCorner(p,q)</tt> to access the block
-consisting of the coefficients <tt>matrix(i,j)</tt> with \c i &lt; \c p and \c j &lt; \c q. As an other
-example, blocks consisting of whole rows flushed against the top side of the matrix can be accessed by
-\link DenseBase::topRows() .topRows() \endlink. 
+to a block in the top-left corner of a matrix.
 
 The different possibilities are summarized in the following table:
 
 <table class="tutorial_code" align="center">
 <tr><td align="center">\b %Block \b operation</td>
-<td align="center">Default version</td>
-<td align="center">Optimized version when the<br>size is known at compile time</td></tr>
+<td align="center">Version constructing a dynamic-size block expression</td>
+<td align="center">Version constructing a fixed-size block expression</td></tr>
 <tr><td>Top-left p by q block \link DenseBase::topLeftCorner() * \endlink</td>
     <td>\code
 matrix.topLeftCorner(p,q);\endcode </td>
@@ -200,12 +190,12 @@ Output:
 
 \section TutorialBlockOperationsSyntaxVectors Block operations for vectors
 
-Eigen also provides a set of block operations designed specifically for vectors and one-dimensional arrays:
+Eigen also provides a set of block operations designed specifically for the special case of vectors and one-dimensional arrays:
 
 <table class="tutorial_code" align="center">
 <tr><td align="center">\b %Block \b operation</td>
-<td align="center">Default version</td>
-<td align="center">Optimized version when the<br>size is known at compile time</td></tr>
+<td align="center">Version constructing a dynamic-size block expression</td>
+<td align="center">Version constructing a fixed-size block expression</td></tr>
 <tr><td>%Block containing the first \p n elements 
                     \link DenseBase::head() * \endlink</td>
     <td>\code
diff --git a/doc/examples/Tutorial_BlockOperations_block_assignment.cpp b/doc/examples/Tutorial_BlockOperations_block_assignment.cpp
index 56ca69a6e..76f49f2fb 100644
--- a/doc/examples/Tutorial_BlockOperations_block_assignment.cpp
+++ b/doc/examples/Tutorial_BlockOperations_block_assignment.cpp
@@ -6,13 +6,13 @@ using namespace Eigen;
 
 int main()
 {
-  Array33f m;
-  m << 1,2,3,
-       4,5,6,
-       7,8,9;
-  Array<float,5,5> n = Array<float,5,5>::Constant(0.6);
-  n.block(1,1,3,3) = m;
-  cout << "n = " << endl << n << endl << endl;
-  Array33f res = n.block(0,0,3,3) * m;
-  cout << "res =" << endl << res << endl;
+  Array22f m;
+  m << 1,2,
+       3,4;
+  Array44f a = Array44f::Constant(0.6);
+  cout << "Here is the array a:" << endl << a << endl << endl;
+  a.block<2,2>(1,1) = m;
+  cout << "Here is now a with m copied into its central 2x2 block:" << endl << a << endl << endl;
+  a.block(0,0,2,3) = a.block(2,1,2,3);
+  cout << "Here is now a with bottom-right 2x3 block copied into top-left 2x2 block:" << endl << a << endl << endl;
 }
diff --git a/doc/examples/Tutorial_BlockOperations_colrow.cpp b/doc/examples/Tutorial_BlockOperations_colrow.cpp
index e98263057..2e7eb009b 100644
--- a/doc/examples/Tutorial_BlockOperations_colrow.cpp
+++ b/doc/examples/Tutorial_BlockOperations_colrow.cpp
@@ -1,14 +1,17 @@
 #include <Eigen/Dense>
 #include <iostream>
 
+using namespace std;
+
 int main()
 {
   Eigen::MatrixXf m(3,3);
   m << 1,2,3,
        4,5,6,
        7,8,9;
-  std::cout << "2nd Row: " << m.row(1) << std::endl;
-  m.col(0) += m.col(2);
-  std::cout << "m after adding third column to first:\n";
-  std::cout << m << std::endl;
+  cout << "Here is the matrix m:" << endl << m << endl;
+  cout << "2nd Row: " << m.row(1) << endl;
+  m.col(2) += 3 * m.col(0);
+  cout << "After adding 3 times the first column into the third column, the matrix m is:\n";
+  cout << m << endl;
 }
diff --git a/doc/examples/Tutorial_BlockOperations_print_block.cpp b/doc/examples/Tutorial_BlockOperations_print_block.cpp
index 0fdefecdf..edea4aefe 100644
--- a/doc/examples/Tutorial_BlockOperations_print_block.cpp
+++ b/doc/examples/Tutorial_BlockOperations_print_block.cpp
@@ -1,6 +1,8 @@
 #include <Eigen/Dense>
 #include <iostream>
 
+using namespace std;
+
 int main()
 {
   Eigen::MatrixXf m(4,4);
@@ -8,11 +10,11 @@ int main()
         5, 6, 7, 8,
         9,10,11,12,
        13,14,15,16;
-  std::cout << "Block in the middle" << std::endl;
-  std::cout << m.block<2,2>(1,1) << std::endl << std::endl;
-  for (int i = 1; i < 4; ++i) 
+  cout << "Block in the middle" << endl;
+  cout << m.block<2,2>(1,1) << endl << endl;
+  for (int i = 1; i <= 3; ++i)
   {
-    std::cout << "Block of size " << i << std::endl;
-    std::cout << m.block(0,0,i,i) << std::endl << std::endl;
+    cout << "Block of size " << i << "x" << i << endl;
+    cout << m.block(0,0,i,i) << endl << endl;
   }
 }