diff --git a/doc/Manual.dox b/doc/Manual.dox index 65ae778fc..73dd8a631 100644 --- a/doc/Manual.dox +++ b/doc/Manual.dox @@ -35,7 +35,6 @@ namespace Eigen { */ /** \page UnclassifiedPages Unclassified pages - - \subpage TopicResizing - \subpage TopicVectorization - \subpage TopicEigenExpressionTemplates - \subpage TopicScalarTypes @@ -70,6 +69,8 @@ namespace Eigen { \ingroup DenseMatrixManipulation_chapter */ /** \addtogroup TutorialReshape \ingroup DenseMatrixManipulation_chapter */ +/** \addtogroup TopicResizing + \ingroup DenseMatrixManipulation_chapter */ /** \addtogroup TutorialSTL \ingroup DenseMatrixManipulation_chapter */ /** \addtogroup TutorialMapClass diff --git a/doc/TopicResizing.dox b/doc/TopicResizing.dox index c323e17ad..b7f28bfb6 100644 --- a/doc/TopicResizing.dox +++ b/doc/TopicResizing.dox @@ -1,11 +1,179 @@ namespace Eigen { -/** \page TopicResizing Resizing +/** \eigenManualPage TopicResizing Resizing + +\eigenAutoToc + +\section TopicResizing_Resize Resizing with \link PlainObjectBase::resize(Index,Index) resize() \endlink + +The most basic method to change the size of matrices or vectors is \link PlainObjectBase::resize(Index,Index) resize(rows, cols) \endlink. +It takes the new number of rows and columns as arguments. + +\code +MatrixXd m(2,2); +m << 1, 2, 3, 4; +m.resize(3,3); +// m is now 3x3. +// OLD values are lost. NEW values are uninitialized. +\endcode + +The \c resize() method is **destructive** if the total number of coefficients (rows x columns) differs from the previous one. +Meaning that all previous values are lost and the newly allocated coefficients are **uninitialized**. +You should fill them before use. + +\subsection TopicResizing_ResizeNoOp The special case of "No-Op" resizing +If you resize a matrix while keeping the total number of coefficients unchanged, the existing values are preserved in memory. +(Meaning when old_rows x old_cols = new_rows x new_cols) + +However, because Eigen stores matrices in **column-major** order by default, the logical position of these values may change. + +\code +MatrixXd m(2,2); +m << 1, 2, 3, 4; +// m is now: 1 2 +// 3 4 +// Memory storage: [1, 3, 2, 4] + +// Resizing to 1x4 (total size 4 is unchanged) +m.resize(1,4); +// m is now: 1 3 2 4 +// The memory [1, 3, 2, 4] was not touched, but is now interpreted as a 1x4 matrix. +\endcode + +\subsection TopicResizing_ResizeNoChange Resizing only one dimension + +To resize only one dimension while leaving the other unchanged, +you can pass \c Eigen::NoChange as the parameter for the dimension you wish to keep. + +\code +MatrixXd m(2,2); +// Resize rows to 5, keep columns at 2 +m.resize(5, Eigen::NoChange); + +// Resize columns to 3, keep rows at 5 +m.resize(Eigen::NoChange, 3); +\endcode + +\subsection TopicResizing_ResizeVectors Resizing vectors + +Resizing for vectors behaves the same way as for matrices. +You provide the new size as an argument to \c resize(). + +\code +VectorXd v(3); +v << 1, 2, 3; +v.resize(5); +// v is now of size 5 and the values are uninitialized. +\endcode + +\subsection TopicResizing_ResizeArray Resizing arrays + +Resizing for arrays behaves the same way as for matrices. +You provide the new number of rows and columns as arguments to \c resize(). + +\code +ArrayXXf a(2,2); +a << 1, 2, 3, 4; +a.resize(3,3); +// a is now 3x3 and the values are uninitialized. +\endcode + +\section TopicResizing_ResizeLike Resizing to match another object with \link PlainObjectBase::resizeLike() resizeLike() \endlink + +You can resize a matrix or vector to match the dimensions of another object using \link PlainObjectBase::resizeLike() resizeLike(eigenBase) \endlink. +This method is also **destructive** (data is lost). + +\code +MatrixXd m(2,2); +MatrixXd n(4,4); +m.resizeLike(n); +// m is now 4x4. +\endcode -TODO: write this dox page! +Note on Vectors: When applied to vectors, \c resizeLike() matches the **size** (number of coefficients) of the other object, +but maintains the row/column orientation of the vector being resized. -Is linked from the tutorial on the Matrix class. +\code +RowVectorXd r(2); +VectorXd c(5); + +// r is resized to be a row-vector of size 5 (1x5), matching c's size. +// It does NOT become a column-vector. +r.resizeLike(c); +\endcode + +\section TopicResizing_Conservative Resizing with \link PlainObjectBase::conservativeResize(Index,Index) conservativeResize() \endlink + +If you need to resize a matrix while keeping its current values, +use \link PlainObjectBase::conservativeResize(Index,Index) conservativeResize(rows, cols) \endlink. + +\code +MatrixXd m(2,2); +m << 1, 2, 3, 4; +m.conservativeResize(3,3); +// m is now: +// 1 2 ? +// 3 4 ? +// ? ? ? +// The '?' are uninitialized values. +\endcode + + +When using \c conservativeResize(): +- **Preservation:** The existing values are preserved. +- **Alignment:** The matrix is resized relative to the **top-left** corner. +- **New Data:** Any newly allocated coefficients (if the matrix grows) are **uninitialized**. You should fill them before use. + +Just like \c resize(), you can resize **vectors** and **arrays** and keep previous values, using \c conservativeResize(). + +And just like \c resize(), you can use \c Eigen::NoChange to resize only one dimension conservatively: +\code +MatrixXd m(2,2); +m << 1, 2, 3, 4; + +// Add a new row (now 3x2), keeping existing values +m.conservativeResize(3, Eigen::NoChange); +\endcode + +\section TopicResizing_Assignment Automatic resizing on assignment + +By default, when you assign one matrix to another, Eigen automatically resizes the left-hand side to match the size of the right-hand side. + +\code +MatrixXf a(2,2); +MatrixXf b(4,4); +a = b; // a is now 4x4 +\endcode + +\subsection TopicResizing_DisableAuto Disabling automatic resizing + +In some applications, you may want to prevent automatic resizing to avoid unexpected memory allocations. +You can disable this behavior by defining the \c EIGEN_NO_AUTOMATIC_RESIZING preprocessor macro. + +If this macro is defined, the assignment `a = b` will trigger an assertion failure at runtime if the dimensions of `a` and `b` do not match. + +\code +#define EIGEN_NO_AUTOMATIC_RESIZING +#include + +void function() { + MatrixXf a(2,2); + MatrixXf b(4,4); + a = b; // ERROR: Runtime assertion failure +} +\endcode + +\section TopicResizing_Fixed Fixed-size matrices + +Resizing methods are technically available on fixed-size matrices for API uniformity, but they will trigger an assertion failure if you try to actually change the dimensions. +Because the dimensions of a fixed-size matrix (like \c Matrix4f) are determined at compile-time, they cannot be changed at runtime. + +\code +Matrix4f m; +m.resize(4,4); // Legal, no-op +m.resize(5,5); // ERROR: Runtime assertion failure +\endcode */ }