doc/TopicResizing.dox

namespace Eigen {

/** \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


<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.

\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

*/
}