* add resize(int, NoChange) and resize(NoChange, int)

* add missing assert in resize(int)
* add examples for all resize variants
* expand docs (part of which is from Tim Hutt's e-mail)

Eigen/src/Core/Matrix.h

@@ -215,14 +215,19 @@ class Matrix
 
     /** Resizes \c *this to a \a rows x \a cols matrix.
       *
-      * Makes sense for dynamic-size matrices only.
+      * This method is intended for dynamic-size matrices, although it is legal to call it on any
+      * matrix as long as fixed dimensions are left unchanged. If you only want to change the number
+      * of rows and/or of columns, you can use resize(NoChange_t, int), resize(int, NoChange_t). 
       *
       * If the current number of coefficients of \c *this exactly matches the
       * product \a rows * \a cols, then no memory allocation is performed and
       * the current values are left unchanged. In all other cases, including
       * shrinking, the data is reallocated and all previous values are lost.
       *
-      * \sa resize(int) for vectors.
+      * Example: \include Matrix_resize_int_int.cpp
+      * Output: \verbinclude Matrix_resize_int_int.out
+      *
+      * \sa resize(int) for vectors, resize(NoChange_t, int), resize(int, NoChange_t)
       */
     inline void resize(int rows, int cols)
     {
@@ -235,17 +240,51 @@ class Matrix
 
     /** Resizes \c *this to a vector of length \a size
       *
-      * \sa resize(int,int) for the details.
+      * \only_for_vectors. This method does not work for
+      * partially dynamic matrices when the static dimension is anything other
+      * than 1. For example it will not work with Matrix<double, 2, Dynamic>.
+      *
+      * Example: \include Matrix_resize_int.cpp
+      * Output: \verbinclude Matrix_resize_int.out
+      *
+      * \sa resize(int,int), resize(NoChange_t, int), resize(int, NoChange_t)
       */
     inline void resize(int size)
     {
       EIGEN_STATIC_ASSERT_VECTOR_ONLY(Matrix)
+      ei_assert(SizeAtCompileTime == Dynamic || SizeAtCompileTime == size);
       if(RowsAtCompileTime == 1)
         m_storage.resize(size, 1, size);
       else
         m_storage.resize(size, size, 1);
     }
 
+    /** Resizes the matrix, changing only the number of columns. For the parameter of type NoChange_t, just pass the special value \c NoChange
+      * as in the example below.
+      *
+      * Example: \include Matrix_resize_NoChange_int.cpp
+      * Output: \verbinclude Matrix_resize_NoChange_int.out
+      *
+      * \sa resize(int,int)
+      */
+    inline void resize(NoChange_t, int cols)
+    {
+      resize(rows(), cols);
+    }
+
+    /** Resizes the matrix, changing only the number of rows. For the parameter of type NoChange_t, just pass the special value \c NoChange
+      * as in the example below.
+      *
+      * Example: \include Matrix_resize_int_NoChange.cpp
+      * Output: \verbinclude Matrix_resize_int_NoChange.out
+      *
+      * \sa resize(int,int)
+      */
+    inline void resize(int rows, NoChange_t)
+    {
+      resize(rows, cols());
+    }
+
     /** Resizes *this to have the same dimensions as \a other.
       * Takes care of doing all the checking that's needed.
       *

Eigen/src/Core/util/Constants.h

@@ -241,6 +241,8 @@ enum {
   DontAlign = 0x2
 };
 
+enum NoChange_t { NoChange };
+
 enum {
   IsDense         = 0,
   IsSparse        = SparseBit,

doc/C01_QuickStartGuide.dox

@@ -88,6 +88,17 @@ For example, \c Vector3d is a typedef for \code Matrix<double, 3, 1> \endcode
 
 For dynamic-size, that is in order to left the number of rows or of columns unspecified at compile-time, use the special value Eigen::Dynamic. For example, \c VectorXd is a typedef for \code Matrix<double, Dynamic, 1> \endcode
 
+All combinations are allowed: you can have a matrix with a fixed number of rows and a dynamic number of columns, etc. The following are all valid:
+
+\code
+Matrix<double, 6, Dynamic> // Dynamic number of columns
+Matrix<double, Dynamic, 2> // Dynamic number of rows
+Matrix<double, Dynamic, Dynamic> // Fully dynamic
+Matrix<double, 13, 3> // Fully fixed
+\endcode
+
+Fixed-size and partially-dynamic-size matrices may use all the same API calls as fully dynamic
+matrices, but the fixed dimension(s) must remain constant, or an assertion failure will occur.
 
 <a href="#" class="top">top</a>\section TutorialCoreCoefficients Coefficient access
 
@@ -109,6 +120,48 @@ Notice that these coefficient access methods have assertions checking the ranges
 
 <a href="#" class="top">top</a>\section TutorialCoreMatrixInitialization Matrix and vector creation and initialization
 
+\subsection TutorialCtors Matrix constructors
+
+The default constructor leaves coefficients uninitialized. Any dynamic size is set to 0, in which case the matrix/vector is considered uninitialized (no array is allocated).
+
+\code
+Matrix3f A; // construct 3x3 matrix with uninitialized coefficients
+A(0,0) = 5; // OK
+MatrixXf B; // construct 0x0 matrix without allocating anything
+A(0,0) = 5; // Error, B is uninitialized, doesn't have any coefficients to address
+\endcode
+
+In the above example, B is an uninitialized matrix. What to do with such a matrix? You can call resize() on it, or you can assign another matrix to it. Like this:
+
+\code
+MatrixXf B; // uninitialized matrix
+B.resize(3,5); // OK, now B is a 3x5 matrix with uninitialized coefficients
+B(0,0) = 5; // OK
+MatrixXf C; // uninitialized matrix
+C = B; // OK, C is initialized as a copy of B
+\endcode
+
+There also are constructors taking size parameters, allowing to directly initialize dynamic-size matrices:
+
+\code
+MatrixXf B(3,5); // B is a 3x5 matrix with uninitialized coefficients
+\endcode
+
+Note that even if one of the dimensions is known at compile time, you must specify it. The only exception is vectors (i.e. matrices where one of the dimensions is known at compile time to be 1).
+
+\code
+VectorXf v(10); // OK, v is a vector of size 10 with uninitialized coefficients
+Matrix<float,2,Dynamic> m(10); // Error: m is not a vector, must provide explicitly the 2 sizes
+Matrix<float,2,Dynamic> m(2,10); // OK
+Matrix2f m(2,2); // OK. Of course it's redundant to pass the parameters here, but it's allowed.
+\endcode
+
+For small fixed-size vectors, we also allow constructors passing the coefficients:
+\code
+Vector2f u(1.2f, 3.4f);
+Vector3f v(1.2f, 3.4f, 5.6f);
+Vector4f w(1.2f, 3.4f, 5.6f, 7.8f);
+\endcode
 
 \subsection TutorialPredefMat Predefined Matrices
 Eigen offers several static methods to create special matrix expressions, and non-static methods to assign these expressions to existing matrices:

doc/snippets/Matrix_resize_NoChange_int.cpp

@@ -0,0 +1,3 @@
+MatrixXd m(3,4);
+m.resize(NoChange, 5);
+cout << "m: " << m.rows() << " rows, " << m.cols() << " cols" << endl;

doc/snippets/Matrix_resize_int.cpp

@@ -0,0 +1,6 @@
+VectorXd v(10);
+v.resize(3);
+RowVector3d w;
+w.resize(3); // this is legal, but has no effect
+cout << "v: " << v.rows() << " rows, " << v.cols() << " cols" << endl;
+cout << "w: " << w.rows() << " rows, " << w.cols() << " cols" << endl;

doc/snippets/Matrix_resize_int_NoChange.cpp

@@ -0,0 +1,3 @@
+MatrixXd m(3,4);
+m.resize(5, NoChange);
+cout << "m: " << m.rows() << " rows, " << m.cols() << " cols" << endl;

doc/snippets/Matrix_resize_int_int.cpp

@@ -0,0 +1,9 @@
+MatrixXd m(2,3);
+m << 1,2,3,4,5,6;
+cout << "here's the 2x3 matrix m:" << endl << m << endl;
+cout << "let's resize m to 3x2. This is a conservative resizing because 2*3==3*2." << endl;
+m.resize(3,2);
+cout << "here's the 3x2 matrix m:" << endl << m << endl;
+cout << "now let's resize m to size 2x2. This is NOT a conservative resizing, so it becomes uninitialized:" << endl;
+m.resize(2,2);
+cout << m << endl;