1namespace Eigen { 2 3/** \eigenManualPage TutorialReshape Reshape 4 5Since the version 3.4, %Eigen exposes convenient methods to reshape a matrix to another matrix of different sizes or vector. 6All cases are handled via the DenseBase::reshaped(NRowsType,NColsType) and DenseBase::reshaped() functions. 7Those functions do not perform in-place reshaping, but instead return a <i> view </i> on the input expression. 8 9\eigenAutoToc 10 11\section TutorialReshapeMat2Mat Reshaped 2D views 12 13The more general reshaping transformation is handled via: `reshaped(nrows,ncols)`. 14Here is an example reshaping a 4x4 matrix to a 2x8 one: 15 16<table class="example"> 17<tr><th>Example:</th><th>Output:</th></tr> 18<tr><td> 19\include MatrixBase_reshaped_int_int.cpp 20</td> 21<td> 22\verbinclude MatrixBase_reshaped_int_int.out 23</td></tr></table> 24 25By default, the input coefficients are always interpreted in column-major order regardless of the storage order of the input expression. 26For more control on ordering, compile-time sizes, and automatic size deduction, please see de documentation of DenseBase::reshaped(NRowsType,NColsType) that contains all the details with many examples. 27 28 29\section TutorialReshapeMat2Vec 1D linear views 30 31A very common usage of reshaping is to create a 1D linear view over a given 2D matrix or expression. 32In this case, sizes can be deduced and thus omitted as in the following example: 33 34<table class="example"> 35<tr><th>Example:</th></tr> 36<tr><td> 37\include MatrixBase_reshaped_to_vector.cpp 38</td></tr> 39<tr><th>Output:</th></tr> 40<tr><td> 41\verbinclude MatrixBase_reshaped_to_vector.out 42</td></tr></table> 43 44This shortcut always returns a column vector and by default input coefficients are always interpreted in column-major order. 45Again, see the documentation of DenseBase::reshaped() for more control on the ordering. 46 47\section TutorialReshapeInPlace 48 49The above examples create reshaped views, but what about reshaping inplace a given matrix? 50Of course this task in only conceivable for matrix and arrays having runtime dimensions. 51In many cases, this can be accomplished via PlainObjectBase::resize(Index,Index): 52 53<table class="example"> 54<tr><th>Example:</th></tr> 55<tr><td> 56\include Tutorial_reshaped_vs_resize_1.cpp 57</td></tr> 58<tr><th>Output:</th></tr> 59<tr><td> 60\verbinclude Tutorial_reshaped_vs_resize_1.out 61</td></tr></table> 62 63However beware that unlike \c reshaped, the result of \c resize depends on the input storage order. 64It thus behaves similarly to `reshaped<AutoOrder>`: 65 66<table class="example"> 67<tr><th>Example:</th></tr> 68<tr><td> 69\include Tutorial_reshaped_vs_resize_2.cpp 70</td></tr> 71<tr><th>Output:</th></tr> 72<tr><td> 73\verbinclude Tutorial_reshaped_vs_resize_2.out 74</td></tr></table> 75 76Finally, assigning a reshaped matrix to itself is currently not supported and will result to undefined-behavior because of \link TopicAliasing aliasing \endlink. 77The following is forbidden: \code A = A.reshaped(2,8); \endcode 78This is OK: \code A = A.reshaped(2,8).eval(); \endcode 79 80*/ 81 82} 83