- rework the coefficients API

- make vectors use a separate loop unroller, so that copying a
row-vector into a col-vector is now possible
- add much more documentation
- misc improvements

Eigen/Core/Block.h

@@ -26,6 +26,28 @@
 #ifndef EIGEN_BLOCK_H
 #define EIGEN_BLOCK_H
 
+/** \class Block
+  *
+  * \brief Expression of a fixed-size block
+  *
+  * \param MatrixType the type of the object in which we are taking a block
+  * \param BlockRows the number of rows of the block we are taking
+  * \param BlockCols the number of columns of the block we are taking
+  *
+  * This class represents an expression of a fixed-size block. It is the return
+  * type of MatrixBase::block() and most of the time this is the only way it
+  * is used.
+  *
+  * However, if you want to directly maniputate fixed-size block expressions,
+  * for instance if you want to write a function returning such an expression, you
+  * will need to use this class.
+  *
+  * Here is an example illustrating this:
+  * \include class_Block.cpp
+  * Output: \verbinclude class_Block.out
+  *
+  * \sa MatrixBase::block(), class DynBlock
+  */
 template<typename MatrixType, int BlockRows, int BlockCols> class Block
   : public MatrixBase<typename MatrixType::Scalar,
                       Block<MatrixType, BlockRows, BlockCols> >
@@ -71,6 +93,18 @@ template<typename MatrixType, int BlockRows, int BlockCols> class Block
     const int m_startRow, m_startCol;
 };
 
+/** \returns a fixed-size expression of a block in *this.
+  *
+  * \param blockRows the number of rows in the block
+  * \param blockCols the number of columns in the block
+  * \param startRow the first row in the block
+  * \param startCol the first column in the block
+  *
+  * Example: \include MatrixBase_block.cpp
+  * Output: \verbinclude MatrixBase_block.out
+  *
+  * \sa class Block, dynBlock()
+  */
 template<typename Scalar, typename Derived>
 template<int BlockRows, int BlockCols>
 Block<Derived, BlockRows, BlockCols> MatrixBase<Scalar, Derived>

Eigen/Core/Cast.h

@@ -26,6 +26,26 @@
 #ifndef EIGEN_CAST_H
 #define EIGEN_CAST_H
 
+/** \class Cast
+  *
+  * \brief Expression with casted scalar type
+  *
+  * \param NewScalar the new scalar type
+  * \param MatrixType the type of the object in which we are casting the scalar type
+  *
+  * This class represents an expression where we are casting the scalar type to a new
+  * type. It is the return type of MatrixBase::cast() and most of the time this is the
+  * only way it is used.
+  *
+  * However, if you want to write a function returning such an expression, you
+  * will need to use this class.
+  *
+  * Here is an example illustrating this:
+  * \include class_Cast.cpp
+  * Output: \verbinclude class_Cast.out
+  *
+  * \sa MatrixBase::cast()
+  */
 template<typename NewScalar, typename MatrixType> class Cast : NoOperatorEquals,
   public MatrixBase<NewScalar, Cast<NewScalar, MatrixType> >
 {
@@ -56,7 +76,15 @@ template<typename NewScalar, typename MatrixType> class Cast : NoOperatorEquals,
 };
 
 /** \returns an expression of *this with the \a Scalar type casted to
-  * \a NewScalar. */
+  * \a NewScalar.
+  *
+  * \param NewScalar the type we are casting the scalars to
+  *
+  * Example: \include MatrixBase_cast.cpp
+  * Output: \verbinclude MatrixBase_cast.out
+  *
+  * \sa class Cast
+  */
 template<typename Scalar, typename Derived>
 template<typename NewScalar>
 const Cast<NewScalar, Derived>

Eigen/Core/Coeffs.h

@@ -26,105 +26,225 @@
 #ifndef EIGEN_COEFFS_H
 #define EIGEN_COEFFS_H
 
+/** Short version: don't use this function, use
+  * \link operator()(int,int) const \endlink instead.
+  *
+  * Long version: this function is similar to
+  * \link operator()(int,int) const \endlink, but without the assertion.
+  * Use this for limiting the performance cost of debugging code when doing
+  * repeated coefficient access. Only use this when it is guaranteed that the
+  * parameters \a row and \a col are in range.
+  *
+  * If EIGEN_INTERNAL_DEBUGGING is defined, an assertion will be made, making this
+  * function equivalent to \link operator()(int,int) const \endlink.
+  *
+  * \sa operator()(int,int) const, coeffRef(int,int), coeff(int) const
+  */
 template<typename Scalar, typename Derived>
 Scalar MatrixBase<Scalar, Derived>
-  ::coeff(int row, int col, AssertLevel assertLevel = InternalDebugging) const
+  ::coeff(int row, int col) const
 {
-  eigen_assert(assertLevel, row >= 0 && row < rows()
+  eigen_internal_assert(row >= 0 && row < rows()
-			    && col >= 0 && col < cols());
+                     && col >= 0 && col < cols());
   return static_cast<const Derived *>(this)->_coeff(row, col);
 }
 
+/** \returns the coefficient at given the given row and column.
+  *
+  * \sa operator()(int,int), operator[](int) const
+  */
 template<typename Scalar, typename Derived>
 Scalar MatrixBase<Scalar, Derived>
-  ::operator()(int row, int col) const { return coeff(row, col, UserDebugging); }
+  ::operator()(int row, int col) const
+{
+  assert(row >= 0 && row < rows()
+      && col >= 0 && col < cols());
+  return static_cast<const Derived *>(this)->_coeff(row, col);
+}
 
+/** Short version: don't use this function, use
+  * \link operator()(int,int) \endlink instead.
+  *
+  * Long version: this function is similar to
+  * \link operator()(int,int) \endlink, but without the assertion.
+  * Use this for limiting the performance cost of debugging code when doing
+  * repeated coefficient access. Only use this when it is guaranteed that the
+  * parameters \a row and \a col are in range.
+  *
+  * If EIGEN_INTERNAL_DEBUGGING is defined, an assertion will be made, making this
+  * function equivalent to \link operator()(int,int) \endlink.
+  *
+  * \sa operator()(int,int), coeff(int, int) const, coeffRef(int)
+  */
 template<typename Scalar, typename Derived>
 Scalar& MatrixBase<Scalar, Derived>
-  ::coeffRef(int row, int col, AssertLevel assertLevel = InternalDebugging)
+  ::coeffRef(int row, int col)
 {
-  eigen_assert(assertLevel, row >= 0 && row < rows()
+  eigen_internal_assert(row >= 0 && row < rows()
-			    && col >= 0 && col < cols());
+                     && col >= 0 && col < cols());
   return static_cast<Derived *>(this)->_coeffRef(row, col);
 }
 
+/** \returns a reference to the coefficient at given the given row and column.
+  *
+  * \sa operator()(int,int) const, operator[](int)
+  */
 template<typename Scalar, typename Derived>
 Scalar& MatrixBase<Scalar, Derived>
-  ::operator()(int row, int col) { return coeffRef(row, col, UserDebugging); }
+  ::operator()(int row, int col)
+{
+  assert(row >= 0 && row < rows()
+      && col >= 0 && col < cols());
+  return static_cast<Derived *>(this)->_coeffRef(row, col);
+}
 
+/** Short version: don't use this function, use
+  * \link operator[](int) const \endlink instead.
+  *
+  * Long version: this function is similar to
+  * \link operator[](int) const \endlink, but without the assertion.
+  * Use this for limiting the performance cost of debugging code when doing
+  * repeated coefficient access. Only use this when it is guaranteed that the
+  * parameters \a row and \a col are in range.
+  *
+  * If EIGEN_INTERNAL_DEBUGGING is defined, an assertion will be made, making this
+  * function equivalent to \link operator[](int) const \endlink.
+  *
+  * \sa operator[](int) const, coeffRef(int), coeff(int,int) const
+  */
 template<typename Scalar, typename Derived>
 Scalar MatrixBase<Scalar, Derived>
-  ::coeff(int index, AssertLevel assertLevel = InternalDebugging) const
+  ::coeff(int index) const
 {
-  eigen_assert(assertLevel, IsVector);
+  eigen_internal_assert(IsVector);
   if(RowsAtCompileTime == 1)
   {
-    eigen_assert(assertLevel, index >= 0 && index < cols());
+    eigen_internal_assert(index >= 0 && index < cols());
     return coeff(0, index);
   }
   else
   {
-    eigen_assert(assertLevel, index >= 0 && index < rows());
+    eigen_internal_assert(index >= 0 && index < rows());
     return coeff(index, 0);
   }
 }
 
+/** \returns the coefficient at given index.
+  *
+  * \only_for_vectors
+  *
+  * \sa operator[](int), operator()(int,int) const, x() const, y() const,
+  * z() const, w() const
+  */
 template<typename Scalar, typename Derived>
 Scalar MatrixBase<Scalar, Derived>
-  ::operator[](int index) const { return coeff(index, UserDebugging); }
+  ::operator[](int index) const
-
-template<typename Scalar, typename Derived>
-Scalar& MatrixBase<Scalar, Derived>
-  ::coeffRef(int index, AssertLevel assertLevel = InternalDebugging)
 {
-  eigen_assert(assertLevel, IsVector);
+  assert(IsVector);
   if(RowsAtCompileTime == 1)
   {
-    eigen_assert(assertLevel, index >= 0 && index < cols());
+    assert(index >= 0 && index < cols());
+    return coeff(0, index);
+  }
+  else
+  {
+    assert(index >= 0 && index < rows());
+    return coeff(index, 0);
+  }
+}
+
+/** Short version: don't use this function, use
+  * \link operator[](int) \endlink instead.
+  *
+  * Long version: this function is similar to
+  * \link operator[](int) \endlink, but without the assertion.
+  * Use this for limiting the performance cost of debugging code when doing
+  * repeated coefficient access. Only use this when it is guaranteed that the
+  * parameters \a row and \a col are in range.
+  *
+  * If EIGEN_INTERNAL_DEBUGGING is defined, an assertion will be made, making this
+  * function equivalent to \link operator[](int) \endlink.
+  *
+  * \sa operator[](int), coeff(int) const, coeffRef(int,int)
+  */
+template<typename Scalar, typename Derived>
+Scalar& MatrixBase<Scalar, Derived>
+  ::coeffRef(int index)
+{
+  eigen_internal_assert(IsVector);
+  if(RowsAtCompileTime == 1)
+  {
+    eigen_internal_assert(index >= 0 && index < cols());
     return coeffRef(0, index);
   }
   else
   {
-    eigen_assert(assertLevel, index >= 0 && index < rows());
+    eigen_internal_assert(index >= 0 && index < rows());
     return coeffRef(index, 0);
   }
 }
 
+/** \returns a reference to the coefficient at given index.
+  *
+  * \only_for_vectors
+  *
+  * \sa operator[](int) const, operator()(int,int), x(), y(), z(), w()
+  */
 template<typename Scalar, typename Derived>
 Scalar& MatrixBase<Scalar, Derived>
-  ::operator[](int index) { return coeffRef(index, UserDebugging); }
+  ::operator[](int index)
+{
+  assert(IsVector);
+  if(RowsAtCompileTime == 1)
+  {
+    assert(index >= 0 && index < cols());
+    return coeffRef(0, index);
+  }
+  else
+  {
+    assert(index >= 0 && index < rows());
+    return coeffRef(index, 0);
+  }
+}
 
+/** equivalent to operator[](0). \only_for_vectors */
 template<typename Scalar, typename Derived>
 Scalar MatrixBase<Scalar, Derived>
-  ::x() const { return coeff(0, UserDebugging); }
+  ::x() const { return (*this)[0]; }
 
+/** equivalent to operator[](1). \only_for_vectors */
 template<typename Scalar, typename Derived>
 Scalar MatrixBase<Scalar, Derived>
-  ::y() const { return coeff(1, UserDebugging); }
+  ::y() const { return (*this)[1]; }
 
+/** equivalent to operator[](2). \only_for_vectors */
 template<typename Scalar, typename Derived>
 Scalar MatrixBase<Scalar, Derived>
-  ::z() const { return coeff(2, UserDebugging); }
+  ::z() const { return (*this)[2]; }
 
+/** equivalent to operator[](3). \only_for_vectors */
 template<typename Scalar, typename Derived>
 Scalar MatrixBase<Scalar, Derived>
-  ::w() const { return coeff(3, UserDebugging); }
+  ::w() const { return (*this)[3]; }
 
+/** equivalent to operator[](0). \only_for_vectors */
 template<typename Scalar, typename Derived>
 Scalar& MatrixBase<Scalar, Derived>
-  ::x() { return coeffRef(0, UserDebugging); }
+  ::x() { return (*this)[0]; }
 
+/** equivalent to operator[](1). \only_for_vectors */
 template<typename Scalar, typename Derived>
 Scalar& MatrixBase<Scalar, Derived>
-  ::y() { return coeffRef(1, UserDebugging); }
+  ::y() { return (*this)[1]; }
 
+/** equivalent to operator[](2). \only_for_vectors */
 template<typename Scalar, typename Derived>
 Scalar& MatrixBase<Scalar, Derived>
-  ::z() { return coeffRef(2, UserDebugging); }
+  ::z() { return (*this)[2]; }
 
+/** equivalent to operator[](3). \only_for_vectors */
 template<typename Scalar, typename Derived>
 Scalar& MatrixBase<Scalar, Derived>
-  ::w() { return coeffRef(3, UserDebugging); }
+  ::w() { return (*this)[3]; }
-
 
 #endif // EIGEN_COEFFS_H

Eigen/Core/Column.h

@@ -26,6 +26,26 @@
 #ifndef EIGEN_COLUMN_H
 #define EIGEN_COLUMN_H
 
+/** \class Column
+  *
+  * \brief Expression of a column
+  *
+  * \param MatrixType the type of the object in which we are taking a column
+  *
+  * This class represents an expression of a column. It is the return
+  * type of MatrixBase::col() and most of the time this is the only way it
+  * is used.
+  *
+  * However, if you want to directly maniputate column expressions,
+  * for instance if you want to write a function returning such an expression, you
+  * will need to use this class.
+  *
+  * Here is an example illustrating this:
+  * \include class_Column.cpp
+  * Output: \verbinclude class_Column.out
+  *
+  * \sa MatrixBase::col()
+  */
 template<typename MatrixType> class Column
   : public MatrixBase<typename MatrixType::Scalar, Column<MatrixType> >
 {
@@ -67,8 +87,12 @@ template<typename MatrixType> class Column
     const int m_col;
 };
 
-/** \returns an expression of the \a i-th column of *this.
+/** \returns an expression of the \a i-th column of *this. Note that the numbering starts at 0.
-  * \sa row(int) */
+  *
+  * Example: \include MatrixBase_col.cpp
+  * Output: \verbinclude MatrixBase_col.out
+  *
+  * \sa row(), class Column */
 template<typename Scalar, typename Derived>
 Column<Derived>
 MatrixBase<Scalar, Derived>::col(int i) const

Eigen/Core/DynBlock.h

@@ -30,9 +30,11 @@
   *
   * \brief Expression of a dynamic-size block
   *
+  * \param MatrixType the type of the object in which we are taking a block
+  *
   * This class represents an expression of a dynamic-size block. It is the return
-  * type of MatrixBase::dynBlock() and most of the time this is the only way this
+  * type of MatrixBase::dynBlock() and most of the time this is the only way it
-  * class is used.
+  * is used.
   *
   * However, if you want to directly maniputate dynamic-size block expressions,
   * for instance if you want to write a function returning such an expression, you
@@ -40,8 +42,7 @@
   *
   * Here is an example illustrating this:
   * \include class_DynBlock.cpp
-  * Output:
+  * Output: \verbinclude class_DynBlock.out
-  * \verbinclude class_DynBlock.out
   *
   * \sa MatrixBase::dynBlock()
   */
@@ -101,12 +102,10 @@ template<typename MatrixType> class DynBlock
   * \param blockRows the number of rows in the block
   * \param blockCols the number of columns in the block
   *
-  * Example:
+  * Example: \include MatrixBase_dynBlock.cpp
-  * \include MatrixBase_dynBlock.cpp
+  * Output: \verbinclude MatrixBase_dynBlock.out
-  * Output:
-  * \verbinclude MatrixBase_dynBlock.out
   *
-  * \sa class DynBlock
+  * \sa class DynBlock, block()
   */
 template<typename Scalar, typename Derived>
 DynBlock<Derived> MatrixBase<Scalar, Derived>

Eigen/Core/MatrixBase.h

@@ -55,12 +55,17 @@
 template<typename Scalar, typename Derived> class MatrixBase
 {
   public:
-    /** The number of rows and of columns at compile-time. These are just
+    /** The number of rows at compile-time. This is just a copy of the value provided
-      * copies of the values provided by the \a Derived type. If a value
+      * by the \a Derived type. If a value is not known at compile-time,
-      * is not known at compile-time, it is set to the \a Dynamic constant.
+      * it is set to the \a Dynamic constant.
-      * \sa rows(), cols(), SizeAtCompileTime */
+      * \sa rows(), cols(), ColsAtCompileTime, SizeAtCompileTime */
-    static const int RowsAtCompileTime = Derived::_RowsAtCompileTime,
+    static const int RowsAtCompileTime = Derived::_RowsAtCompileTime;
-                     ColsAtCompileTime = Derived::_ColsAtCompileTime;
+    
+    /** The number of columns at compile-time. This is just a copy of the value provided
+      * by the \a Derived type. If a value is not known at compile-time,
+      * it is set to the \a Dynamic constant.
+      * \sa rows(), cols(), RowsAtCompileTime, SizeAtCompileTime */
+    static const int ColsAtCompileTime = Derived::_ColsAtCompileTime;
     
     /** This is equal to the number of coefficients, i.e. the number of
       * rows times the number of columns, or to \a Dynamic if this is not
@@ -77,9 +82,9 @@ template<typename Scalar, typename Derived> class MatrixBase
     /** This is the "reference type" used to pass objects of type MatrixBase as arguments
       * to functions. If this MatrixBase type represents an expression, then \a Ref
       * is just this MatrixBase type itself, i.e. expressions are just passed by value
-      * and the compiler is supposed to be clever enough to optimize that. If, on the
+      * and the compiler is usually clever enough to optimize that. If, on the
-      * other hand, this MatrixBase type is an actual matrix or vector, then \a Ref is
+      * other hand, this MatrixBase type is an actual matrix or vector type, then \a Ref is
-      * a typedef MatrixRef, which is like a reference, so that matrices and vectors
+      * a typedef to MatrixRef, which works as a reference, so that matrices and vectors
       * are passed by reference, not by value. \sa ref()*/
     typedef typename ForwardDecl<Derived>::Ref Ref;
     
@@ -195,16 +200,16 @@ template<typename Scalar, typename Derived> class MatrixBase
     Derived& operator/=(const std::complex<float>& other);
     Derived& operator/=(const std::complex<double>& other);
 
-    Scalar coeff(int row, int col, AssertLevel assertLevel) const;
+    Scalar coeff(int row, int col) const;
     Scalar operator()(int row, int col) const;
     
-    Scalar& coeffRef(int row, int col, AssertLevel assertLevel);
+    Scalar& coeffRef(int row, int col);
     Scalar& operator()(int row, int col);
     
-    Scalar coeff(int index, AssertLevel assertLevel) const;
+    Scalar coeff(int index) const;
     Scalar operator[](int index) const;
     
-    Scalar& coeffRef(int index, AssertLevel assertLevel);
+    Scalar& coeffRef(int index);
     Scalar& operator[](int index);
     
     Scalar x() const;

Eigen/Core/OperatorEquals.h

@@ -28,27 +28,27 @@
 #define EIGEN_OPERATOREQUALS_H
 
 template<typename Derived1, typename Derived2, int UnrollCount, int Rows>
-struct OperatorEqualsUnroller
+struct MatrixOperatorEqualsUnroller
 {
   static const int col = (UnrollCount-1) / Rows;
   static const int row = (UnrollCount-1) % Rows;
 
   static void run(Derived1 &dst, const Derived2 &src)
   {
-    OperatorEqualsUnroller<Derived1, Derived2, UnrollCount-1, Rows>::run(dst, src);
+    MatrixOperatorEqualsUnroller<Derived1, Derived2, UnrollCount-1, Rows>::run(dst, src);
     dst.coeffRef(row, col) = src.coeff(row, col);
   }
 };
 
 // prevent buggy user code from causing an infinite recursion
 template<typename Derived1, typename Derived2, int UnrollCount>
-struct OperatorEqualsUnroller<Derived1, Derived2, UnrollCount, 0>
+struct MatrixOperatorEqualsUnroller<Derived1, Derived2, UnrollCount, 0>
 {
   static void run(Derived1 &, const Derived2 &) {}
 };
 
 template<typename Derived1, typename Derived2, int Rows>
-struct OperatorEqualsUnroller<Derived1, Derived2, 1, Rows>
+struct MatrixOperatorEqualsUnroller<Derived1, Derived2, 1, Rows>
 {
   static void run(Derived1 &dst, const Derived2 &src)
   {
@@ -57,7 +57,41 @@ struct OperatorEqualsUnroller<Derived1, Derived2, 1, Rows>
 };
 
 template<typename Derived1, typename Derived2, int Rows>
-struct OperatorEqualsUnroller<Derived1, Derived2, Dynamic, Rows>
+struct MatrixOperatorEqualsUnroller<Derived1, Derived2, Dynamic, Rows>
+{
+  static void run(Derived1 &, const Derived2 &) {}
+};
+
+template<typename Derived1, typename Derived2, int UnrollCount>
+struct VectorOperatorEqualsUnroller
+{
+  static const int index = UnrollCount - 1;
+
+  static void run(Derived1 &dst, const Derived2 &src)
+  {
+    VectorOperatorEqualsUnroller<Derived1, Derived2, UnrollCount-1>::run(dst, src);
+    dst.coeffRef(index) = src.coeff(index);
+  }
+};
+
+// prevent buggy user code from causing an infinite recursion
+template<typename Derived1, typename Derived2>
+struct VectorOperatorEqualsUnroller<Derived1, Derived2, 0>
+{
+  static void run(Derived1 &, const Derived2 &) {}
+};
+
+template<typename Derived1, typename Derived2>
+struct VectorOperatorEqualsUnroller<Derived1, Derived2, 1>
+{
+  static void run(Derived1 &dst, const Derived2 &src)
+  {
+    dst.coeffRef(0) = src.coeff(0);
+  }
+};
+
+template<typename Derived1, typename Derived2>
+struct VectorOperatorEqualsUnroller<Derived1, Derived2, Dynamic>
 {
   static void run(Derived1 &, const Derived2 &) {}
 };
@@ -67,16 +101,31 @@ template<typename OtherDerived>
 Derived& MatrixBase<Scalar, Derived>
   ::operator=(const MatrixBase<Scalar, OtherDerived>& other)
 {
-  assert(rows() == other.rows() && cols() == other.cols());
+  if(IsVector && OtherDerived::IsVector) // copying a vector expression into a vector
-  if(EIGEN_UNROLLED_LOOPS && SizeAtCompileTime != Dynamic && SizeAtCompileTime <= 25)
+  {
-    OperatorEqualsUnroller
+    assert(size() == other.size());
-      <Derived, OtherDerived, SizeAtCompileTime, RowsAtCompileTime>::run
+    if(EIGEN_UNROLLED_LOOPS && SizeAtCompileTime != Dynamic && SizeAtCompileTime <= 25)
-        (*static_cast<Derived*>(this), *static_cast<const OtherDerived*>(&other));
+      VectorOperatorEqualsUnroller
-  else
+        <Derived, OtherDerived, SizeAtCompileTime>::run
-    for(int j = 0; j < cols(); j++) //traverse in column-dominant order
+          (*static_cast<Derived*>(this), *static_cast<const OtherDerived*>(&other));
-      for(int i = 0; i < rows(); i++)
+    else
-        coeffRef(i, j) = other.coeff(i, j);
+      for(int i = 0; i < size(); i++)
-  return *static_cast<Derived*>(this);
+        coeffRef(i) = other.coeff(i);
+    return *static_cast<Derived*>(this);
+  }
+  else // all other cases (typically, but not necessarily, copying a matrix)
+  {
+    assert(rows() == other.rows() && cols() == other.cols());
+    if(EIGEN_UNROLLED_LOOPS && SizeAtCompileTime != Dynamic && SizeAtCompileTime <= 25)
+      MatrixOperatorEqualsUnroller
+        <Derived, OtherDerived, SizeAtCompileTime, RowsAtCompileTime>::run
+          (*static_cast<Derived*>(this), *static_cast<const OtherDerived*>(&other));
+    else
+      for(int j = 0; j < cols(); j++) //traverse in column-dominant order
+        for(int i = 0; i < rows(); i++)
+          coeffRef(i, j) = other.coeff(i, j);
+    return *static_cast<Derived*>(this);
+  }
 }
 
 #endif // EIGEN_OPERATOREQUALS_H

Eigen/Core/Row.h

@@ -26,6 +26,26 @@
 #ifndef EIGEN_ROW_H
 #define EIGEN_ROW_H
 
+/** \class Row
+  *
+  * \brief Expression of a row
+  *
+  * \param MatrixType the type of the object in which we are taking a row
+  *
+  * This class represents an expression of a row. It is the return
+  * type of MatrixBase::row() and most of the time this is the only way it
+  * is used.
+  *
+  * However, if you want to directly maniputate row expressions,
+  * for instance if you want to write a function returning such an expression, you
+  * will need to use this class.
+  *
+  * Here is an example illustrating this:
+  * \include class_Row.cpp
+  * Output: \verbinclude class_Row.out
+  *
+  * \sa MatrixBase::row()
+  */
 template<typename MatrixType> class Row
   : public MatrixBase<typename MatrixType::Scalar, Row<MatrixType> >
 {
@@ -75,8 +95,12 @@ template<typename MatrixType> class Row
     const int m_row;
 };
 
-/** \returns an expression of the \a i-th row of *this.
+/** \returns an expression of the \a i-th row of *this. Note that the numbering starts at 0.
-  * \sa col(int)*/
+  *
+  * Example: \include MatrixBase_row.cpp
+  * Output: \verbinclude MatrixBase_row.out
+  *
+  * \sa col(), class Row */
 template<typename Scalar, typename Derived>
 Row<Derived>
 MatrixBase<Scalar, Derived>::row(int i) const

Eigen/Core/Util.h

@@ -34,18 +34,17 @@
 
 #undef minor
 
-#define USING_EIGEN_DATA_TYPES \
+#define USING_PART_OF_NAMESPACE_EIGEN \
 EIGEN_USING_MATRIX_TYPEDEFS \
-using Eigen::Matrix;
+using Eigen::Matrix; \
+using Eigen::MatrixBase;
 
 #ifdef EIGEN_INTERNAL_DEBUGGING
-#define EIGEN_ASSERT_LEVEL 2
+#define eigen_internal_assert(x) assert(x);
 #else
-#define EIGEN_ASSERT_LEVEL 1
+#define eigen_internal_assert(x)
 #endif
 
-#define eigen_assert(assertLevel, x) if(assertLevel <= EIGEN_ASSERT_LEVEL) assert(x);
-
 #ifdef NDEBUG
 #define EIGEN_ONLY_USED_FOR_DEBUG(x) (void)x
 #else
@@ -121,12 +120,6 @@ struct ForwardDecl<Matrix<_Scalar, _Rows, _Cols> >
 
 const int Dynamic = -1;
 
-enum AssertLevel
-{
-  UserDebugging = 1,
-  InternalDebugging = 2
-};
-
 //classes inheriting NoOperatorEquals don't generate a default operator=.
 class NoOperatorEquals
 {

doc/Doxyfile.in

@@ -35,7 +35,9 @@ DETAILS_AT_TOP         = NO
 INHERIT_DOCS           = YES
 SEPARATE_MEMBER_PAGES  = NO
 TAB_SIZE               = 8
-ALIASES                = 
+ALIASES                = \
+"only_for_vectors=This is only for vectors (either row-vectors or column-vectors), \
+as determined by \link MatrixBase::IsVector \endlink."
 OPTIMIZE_OUTPUT_FOR_C  = NO
 OPTIMIZE_OUTPUT_JAVA   = NO
 BUILTIN_STL_SUPPORT    = NO
@@ -51,8 +53,8 @@ EXTRACT_STATIC         = NO
 EXTRACT_LOCAL_CLASSES  = NO
 EXTRACT_LOCAL_METHODS  = NO
 EXTRACT_ANON_NSPACES   = NO
-HIDE_UNDOC_MEMBERS     = YES
+HIDE_UNDOC_MEMBERS     = NO
-HIDE_UNDOC_CLASSES     = YES
+HIDE_UNDOC_CLASSES     = NO
 HIDE_FRIEND_COMPOUNDS  = YES
 HIDE_IN_BODY_DOCS      = NO
 INTERNAL_DOCS          = NO
@@ -61,7 +63,7 @@ HIDE_SCOPE_NAMES       = YES
 SHOW_INCLUDE_FILES     = YES
 INLINE_INFO            = YES
 SORT_MEMBER_DOCS       = YES
-SORT_BRIEF_DOCS        = NO
+SORT_BRIEF_DOCS        = YES
 SORT_BY_SCOPE_NAME     = NO
 GENERATE_TODOLIST      = YES
 GENERATE_TESTLIST      = YES
@@ -77,7 +79,7 @@ FILE_VERSION_FILTER    =
 #---------------------------------------------------------------------------
 QUIET                  = NO
 WARNINGS               = YES
-WARN_IF_UNDOCUMENTED   = YES
+WARN_IF_UNDOCUMENTED   = NO
 WARN_IF_DOC_ERROR      = YES
 WARN_NO_PARAMDOC       = NO
 WARN_FORMAT            = "$file:$line: $text"
@@ -254,21 +256,21 @@ PERL_PATH              = /usr/bin/perl
 #---------------------------------------------------------------------------
 # Configuration options related to the dot tool   
 #---------------------------------------------------------------------------
-CLASS_DIAGRAMS         = YES
+CLASS_DIAGRAMS         = NO
-MSCGEN_PATH            = 
+MSCGEN_PATH            = NO
-HIDE_UNDOC_RELATIONS   = YES
+HIDE_UNDOC_RELATIONS   = NO
-HAVE_DOT               = YES
+HAVE_DOT               = NO
-CLASS_GRAPH            = YES
+CLASS_GRAPH            = NO
 COLLABORATION_GRAPH    = NO
-GROUP_GRAPHS           = YES
+GROUP_GRAPHS           = NO
 UML_LOOK               = NO
 TEMPLATE_RELATIONS     = NO
-INCLUDE_GRAPH          = YES
+INCLUDE_GRAPH          = NO
-INCLUDED_BY_GRAPH      = YES
+INCLUDED_BY_GRAPH      = NO
 CALL_GRAPH             = NO
 CALLER_GRAPH           = NO
-GRAPHICAL_HIERARCHY    = YES
+GRAPHICAL_HIERARCHY    = NO
-DIRECTORY_GRAPH        = YES
+DIRECTORY_GRAPH        = NO
 DOT_IMAGE_FORMAT       = png
 DOT_PATH               = 
 DOTFILE_DIRS           = 
@@ -276,8 +278,8 @@ DOT_GRAPH_MAX_NODES    = 50
 MAX_DOT_GRAPH_DEPTH    = 1000
 DOT_TRANSPARENT        = NO
 DOT_MULTI_TARGETS      = NO
-GENERATE_LEGEND        = YES
+GENERATE_LEGEND        = NO
-DOT_CLEANUP            = YES
+DOT_CLEANUP            = NO
 #---------------------------------------------------------------------------
 # Configuration::additions related to the search engine   
 #---------------------------------------------------------------------------

doc/benchmark.cpp

@@ -3,7 +3,7 @@
 #include <Eigen/Core.h>
 
 using namespace std;
-USING_EIGEN_DATA_TYPES
+USING_PART_OF_NAMESPACE_EIGEN
 
 int main(int argc, char *argv[])
 {

doc/example.cpp

@@ -1,18 +1,18 @@
 #include <Eigen/Core.h>
 
-USING_EIGEN_DATA_TYPES
+USING_PART_OF_NAMESPACE_EIGEN
 
 using namespace std;
 
 template<typename Scalar, typename Derived>
-void foo(const Eigen::MatrixBase<Scalar, Derived>& m)
+void foo(const MatrixBase<Scalar, Derived>& m)
 {
   cout << "Here's m:" << endl << m << endl;
 }
 
 template<typename Scalar, typename Derived>
 Eigen::ScalarMultiple<Derived>
-twice(const Eigen::MatrixBase<Scalar, Derived>& m)
+twice(const MatrixBase<Scalar, Derived>& m)
 {
   return 2 * m;
 }

doc/examples/class_Block.cpp

@@ -0,0 +1,23 @@
+#include <Eigen/Core.h>
+USING_PART_OF_NAMESPACE_EIGEN
+using namespace std;
+
+template<typename Scalar, typename Derived>
+Eigen::Block<Derived, 2, 2>
+topLeft2x2Corner(MatrixBase<Scalar, Derived>& m)
+{
+  return Eigen::Block<Derived, 2, 2>(m.ref(), 0, 0);
+  // note: tempting as it is, writing "m.block<2,2>(0,0)" here
+  // causes a compile error with g++ 4.2, apparently due to
+  // g++ getting confused by the many template types and
+  // template arguments involved.
+}
+
+int main(int, char**)
+{
+  Matrix3d m = Matrix3d::identity();
+  cout << topLeft2x2Corner(m) << endl;
+  topLeft2x2Corner(m) *= 2;
+  cout << "Now the matrix m is:" << endl << m << endl;
+  return 0;
+}

doc/examples/class_Cast.cpp

@@ -0,0 +1,23 @@
+#include <Eigen/Core.h>
+USING_PART_OF_NAMESPACE_EIGEN
+using namespace std;
+
+template<typename Scalar, typename Derived>
+Eigen::Cast<double, Derived>
+castToDouble(const MatrixBase<Scalar, Derived>& m)
+{
+  return Eigen::Cast<double, Derived>(m.ref());
+  // note: tempting as it is, writing "m.cast<double>()" here
+  // causes a compile error with g++ 4.2, apparently due to
+  // g++ getting confused by the many template types and
+  // template arguments involved.
+}
+
+int main(int, char**)
+{
+  Matrix2i m = Matrix2i::random();
+  cout << "Here's the matrix m. It has coefficients of type int."
+       << endl << m << endl;
+  cout << "Here's 0.05*m:" << endl << 0.05 * castToDouble(m) << endl;
+  return 0;
+}

doc/examples/class_Column.cpp

@@ -0,0 +1,19 @@
+#include <Eigen/Core.h>
+USING_PART_OF_NAMESPACE_EIGEN
+using namespace std;
+
+template<typename Scalar, typename Derived>
+Eigen::Column<Derived>
+firstColumn(MatrixBase<Scalar, Derived>& m)
+{
+  return m.col(0);
+}
+
+int main(int, char**)
+{
+  Matrix4d m = Matrix4d::identity();
+  cout << firstColumn(m) << endl;
+  firstColumn(m) *= 5;
+  cout << "Now the matrix m is:" << endl << m << endl;
+  return 0;
+}

doc/examples/class_DynBlock.cpp

@@ -1,10 +1,10 @@
 #include <Eigen/Core.h>
-USING_EIGEN_DATA_TYPES
+USING_PART_OF_NAMESPACE_EIGEN
 using namespace std;
 
 template<typename Scalar, typename Derived>
 Eigen::DynBlock<Derived>
-topLeftCorner(const Eigen::MatrixBase<Scalar, Derived>& m, int rows, int cols)
+topLeftCorner(MatrixBase<Scalar, Derived>& m, int rows, int cols)
 {
   return m.dynBlock(0, 0, rows, cols);
 }

doc/examples/class_Row.cpp

@@ -0,0 +1,19 @@
+#include <Eigen/Core.h>
+USING_PART_OF_NAMESPACE_EIGEN
+using namespace std;
+
+template<typename Scalar, typename Derived>
+Eigen::Row<Derived>
+firstRow(MatrixBase<Scalar, Derived>& m)
+{
+  return m.row(0);
+}
+
+int main(int, char**)
+{
+  Matrix4d m = Matrix4d::identity();
+  cout << firstRow(m) << endl;
+  firstRow(m) *= 5;
+  cout << "Now the matrix m is:" << endl << m << endl;
+  return 0;
+}

doc/snippets/MatrixBase_block.cpp

@@ -0,0 +1,3 @@
+Matrix4d m = Matrix4d::diagonal(Vector4d(1,2,3,4));
+m.block<2, 2>(2, 0) = m.block<2, 2>(2, 2);
+cout << m << endl;

doc/snippets/MatrixBase_cast.cpp

@@ -0,0 +1,3 @@
+Matrix2d md = Matrix2d::identity() * 0.45;
+Matrix2f mf = Matrix2f::identity();
+cout << md + mf.cast<double>() << endl;

doc/snippets/MatrixBase_col.cpp

@@ -0,0 +1,3 @@
+Matrix3d m = Matrix3d::identity();
+m.col(1) = Vector3d(4,5,6);
+cout << m << endl;

doc/snippets/MatrixBase_dynBlock.cpp

@@ -1,3 +1,3 @@
-Matrix4d m = Matrix4d::identity();
+Matrix3d m = Matrix3d::diagonal(Vector3d(1,2,3));
-m.dynBlock(2,0,2,2) = m.dynBlock(0,0,2,2);
+m.dynBlock(1, 0, 2, 1) = m.dynBlock(1, 1, 2, 1);
 cout << m << endl;

doc/snippets/MatrixBase_row.cpp

@@ -0,0 +1,3 @@
+Matrix3d m = Matrix3d::identity();
+m.row(1) = Vector3d(4,5,6);
+cout << m << endl;

doc/snippets/compile_snippet.cpp.in

@@ -1,5 +1,5 @@
 #include <Eigen/Core.h>
-USING_EIGEN_DATA_TYPES
+USING_PART_OF_NAMESPACE_EIGEN
 using namespace std;
 int main(int, char**)
 {

doc/tutorial.cpp

@@ -1,6 +1,6 @@
 #include <Eigen/Core.h>
 
-USING_EIGEN_DATA_TYPES
+USING_PART_OF_NAMESPACE_EIGEN
 
 using namespace std;