Tutorial page 4: add some text, diversify examples.
Use \verbinclude for output text to disable syntax highlighting.
Give tables consistent look.
diff --git a/doc/C04_TutorialBlockOperations.dox b/doc/C04_TutorialBlockOperations.dox
index 70773a4..b45cbfb 100644
--- a/doc/C04_TutorialBlockOperations.dox
+++ b/doc/C04_TutorialBlockOperations.dox
@@ -13,21 +13,22 @@
\b Table \b of \b contents
- \ref TutorialBlockOperationsUsing
- - \ref TutorialBlockOperationsSyntax
- - \ref TutorialBlockOperationsSyntaxColumnRows
- - \ref TutorialBlockOperationsSyntaxCorners
+ - \ref TutorialBlockOperationsSyntaxColumnRows
+ - \ref TutorialBlockOperationsSyntaxCorners
+ - \ref TutorialBlockOperationsSyntaxVectors
+
\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> by using
-the following syntax:
+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 \b version</td>
+<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>
-<tr><td>Block of size <tt>(p,q)</tt>, starting at <tt>(i,j)</tt></td>
+<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>
<td>\code
@@ -35,7 +36,15 @@
</tr>
</table>
-Therefore, if we want to print the values of a block inside a matrix we can simply write:
+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.
+
+The following program uses the default and optimized versions to print the values of several blocks inside a
+matrix.
+
<table class="tutorial_code"><tr><td>
\include Tutorial_BlockOperations_print_block.cpp
</td>
@@ -44,10 +53,15 @@
\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 previous example the \link DenseBase::block() .block() \endlink function was employed
-to read the values inside matrix \p m . Blocks can also be used to perform operations and
-assignments within matrices or arrays of different size:
+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.
<table class="tutorial_code"><tr><td>
\include Tutorial_BlockOperations_block_assignment.cpp
@@ -57,55 +71,38 @@
\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.
-Blocks can also be combined with matrices and arrays to create more complex expressions:
-\code
- MatrixXf m(3,3), n(2,2);
- MatrixXf p(3,3);
-
- m.block(0,0,2,2) = m.block(0,0,2,2) * n + p.block(1,1,2,2);
-\endcode
+\section TutorialBlockOperationsSyntaxColumnRows Columns and rows
-It is important to point out that \link DenseBase::block() .block() \endlink is the
-general case for a block operation but there are many other useful block operations,
-as described in the next section.
-
-\section TutorialBlockOperationsSyntax Block operation syntax
-The following tables show a summary of Eigen's block operations and how they are applied to
-fixed- and dynamic-sized Eigen objects.
-
-\subsection TutorialBlockOperationsSyntaxColumnRows Columns and rows
-Other extremely useful block operations are \link DenseBase::col() .col() \endlink and
-\link DenseBase::row() .row() \endlink which provide access to a
-specific row or column. This is a special case in the sense that the syntax for fixed- and
-dynamic-sized objects is exactly the same:
+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.
<table class="tutorial_code" align="center">
-<tr><td align="center">\b Block \b operation</td>
+<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>
<tr><td>i<sup>th</sup> row
\link DenseBase::row() * \endlink</td>
<td>\code
-MatrixXf m;
-std::cout << m.row(i);\endcode </td>
+matrix.row(i);\endcode </td>
<td>\code
-Matrix3f m;
-std::cout << m.row(i);\endcode </td>
+matrix.row(i);\endcode </td>
</tr>
<tr><td>j<sup>th</sup> column
\link DenseBase::col() * \endlink</td>
<td>\code
-MatrixXf m;
-std::cout << m.col(j);\endcode </td>
+matrix.col(j);\endcode </td>
<td>\code
-Matrix3f m;
-std::cout << m.col(j);\endcode </td>
+matrix.col(j);\endcode </td>
</tr>
</table>
-A simple example demonstrating these feature follows:
+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.
<table class="tutorial_code"><tr><td>
C++ code:
@@ -113,94 +110,83 @@
</td>
<td>
Output:
-\include Tutorial_BlockOperations_colrow.out
+\verbinclude Tutorial_BlockOperations_colrow.out
</td></tr></table>
-\b NOTE: 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.
+\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 < \c p and \c j < \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.
-\subsection TutorialBlockOperationsSyntaxCorners Corner-related operations
+The different possibilities are summarized in the following table:
+
<table class="tutorial_code" align="center">
-<tr><td align="center">\b Block \b operation</td>
+<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>
<tr><td>Top-left p by q block \link DenseBase::topLeftCorner() * \endlink</td>
<td>\code
-MatrixXf m;
-std::cout << m.topLeftCorner(p,q);\endcode </td>
+matrix.topLeftCorner(p,q);\endcode </td>
<td>\code
-Matrix3f m;
-std::cout << m.topLeftCorner<p,q>();\endcode </td>
+matrix.topLeftCorner<p,q>();\endcode </td>
</tr>
<tr><td>Bottom-left p by q block
\link DenseBase::bottomLeftCorner() * \endlink</td>
<td>\code
-MatrixXf m;
-std::cout << m.bottomLeftCorner(p,q);\endcode </td>
+matrix.bottomLeftCorner(p,q);\endcode </td>
<td>\code
-Matrix3f m;
-std::cout << m.bottomLeftCorner<p,q>();\endcode </td>
+matrix.bottomLeftCorner<p,q>();\endcode </td>
</tr>
<tr><td>Top-right p by q block
\link DenseBase::topRightCorner() * \endlink</td>
<td>\code
-MatrixXf m;
-std::cout << m.topRightCorner(p,q);\endcode </td>
+matrix.topRightCorner(p,q);\endcode </td>
<td>\code
-Matrix3f m;
-std::cout << m.topRightCorner<p,q>();\endcode </td>
+matrix.topRightCorner<p,q>();\endcode </td>
</tr>
<tr><td>Bottom-right p by q block
\link DenseBase::bottomRightCorner() * \endlink</td>
<td>\code
-MatrixXf m;
-std::cout << m.bottomRightCorner(p,q);\endcode </td>
+matrix.bottomRightCorner(p,q);\endcode </td>
<td>\code
-Matrix3f m;
-std::cout << m.bottomRightCorner<p,q>();\endcode </td>
+matrix.bottomRightCorner<p,q>();\endcode </td>
</tr>
-<tr><td>Block containing the first q rows
+<tr><td>%Block containing the first q rows
\link DenseBase::topRows() * \endlink</td>
<td>\code
-MatrixXf m;
-std::cout << m.topRows(q);\endcode </td>
+matrix.topRows(q);\endcode </td>
<td>\code
-Matrix3f m;
-std::cout << m.topRows<q>();\endcode </td>
+matrix.topRows<q>();\endcode </td>
</tr>
-<tr><td>Block containing the last q rows
+<tr><td>%Block containing the last q rows
\link DenseBase::bottomRows() * \endlink</td>
<td>\code
-MatrixXf m;
-std::cout << m.bottomRows(q);\endcode </td>
+matrix.bottomRows(q);\endcode </td>
<td>\code
-Matrix3f m;
-std::cout << m.bottomRows<q>();\endcode </td>
+matrix.bottomRows<q>();\endcode </td>
</tr>
-<tr><td>Block containing the first p columns
+<tr><td>%Block containing the first p columns
\link DenseBase::leftCols() * \endlink</td>
<td>\code
-MatrixXf m;
-std::cout << m.leftCols(p);\endcode </td>
+matrix.leftCols(p);\endcode </td>
<td>\code
-Matrix3f m;
-std::cout << m.leftCols<p>();\endcode </td>
+matrix.leftCols<p>();\endcode </td>
</tr>
-<tr><td>Block containing the last q columns
+<tr><td>%Block containing the last q columns
\link DenseBase::rightCols() * \endlink</td>
<td>\code
-MatrixXf m;
-std::cout << m.rightCols(q);\endcode </td>
+matrix.rightCols(q);\endcode </td>
<td>\code
-Matrix3f m;
-std::cout << m.rightCols<q>();\endcode </td>
+matrix.rightCols<q>();\endcode </td>
</tr>
</table>
-
-Here is a simple example showing the power of the operations presented above:
+Here is a simple example illustrating the use of the operations presented above:
<table class="tutorial_code"><tr><td>
C++ code:
@@ -208,49 +194,38 @@
</td>
<td>
Output:
-\include Tutorial_BlockOperations_corner.out
+\verbinclude Tutorial_BlockOperations_corner.out
</td></tr></table>
+\section TutorialBlockOperationsSyntaxVectors Block operations for vectors
-
-
-
-
-
-\subsection TutorialBlockOperationsSyntaxVectors Block operations for vectors
-Eigen also provides a set of block operations designed specifically for vectors:
+Eigen also provides a set of block operations designed specifically for vectors and one-dimensional arrays:
<table class="tutorial_code" align="center">
-<tr><td align="center">\b Block \b operation</td>
+<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>
-<tr><td>Block containing the first \p n elements
+<tr><td>%Block containing the first \p n elements
\link DenseBase::head() * \endlink</td>
<td>\code
-VectorXf v;
-std::cout << v.head(n);\endcode </td>
+vector.head(n);\endcode </td>
<td>\code
-Vector3f v;
-std::cout << v.head<n>();\endcode </td>
+vector.head<n>();\endcode </td>
</tr>
-<tr><td>Block containing the last \p n elements
+<tr><td>%Block containing the last \p n elements
\link DenseBase::tail() * \endlink</td>
<td>\code
-VectorXf v;
-std::cout << v.tail(n);\endcode </td>
+vector.tail(n);\endcode </td>
<td>\code
-Vector3f m;
-std::cout << v.tail<n>();\endcode </td>
+vector.tail<n>();\endcode </td>
</tr>
-<tr><td>Block containing \p n elements, starting at position \p i
+<tr><td>%Block containing \p n elements, starting at position \p i
\link DenseBase::segment() * \endlink</td>
<td>\code
-VectorXf v;
-std::cout << v.segment(i,n);\endcode </td>
+vector.segment(i,n);\endcode </td>
<td>\code
-Vector3f m;
-std::cout << v.segment<n>(i);\endcode </td>
+vector.segment<n>(i);\endcode </td>
</tr>
</table>
@@ -262,7 +237,7 @@
</td>
<td>
Output:
-\include Tutorial_BlockOperations_vector.out
+\verbinclude Tutorial_BlockOperations_vector.out
</td></tr></table>
\li \b Next: \ref TutorialAdvancedInitialization