Wrote resizing documentation page

libeigen/eigen!2110

Co-authored-by: Simon Merkle <st172506@stud.uni-stuttgart.de>

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

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!
+<b>Note on Vectors:</b> 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 <Eigen/Dense>
+
+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
 
 */
 }