- 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

15 files changed, 125 insertions, 27 deletions

diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in
index 4f0e4c200..36e19f6d0 100644
--- a/doc/Doxyfile.in
+++ b/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_CLASSES     = YES
+HIDE_UNDOC_MEMBERS     = NO
+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
-MSCGEN_PATH            = 
-HIDE_UNDOC_RELATIONS   = YES
-HAVE_DOT               = YES
-CLASS_GRAPH            = YES
+CLASS_DIAGRAMS         = NO
+MSCGEN_PATH            = NO
+HIDE_UNDOC_RELATIONS   = NO
+HAVE_DOT               = NO
+CLASS_GRAPH            = NO
 COLLABORATION_GRAPH    = NO
-GROUP_GRAPHS           = YES
+GROUP_GRAPHS           = NO
 UML_LOOK               = NO
 TEMPLATE_RELATIONS     = NO
-INCLUDE_GRAPH          = YES
-INCLUDED_BY_GRAPH      = YES
+INCLUDE_GRAPH          = NO
+INCLUDED_BY_GRAPH      = NO
 CALL_GRAPH             = NO
 CALLER_GRAPH           = NO
-GRAPHICAL_HIERARCHY    = YES
-DIRECTORY_GRAPH        = YES
+GRAPHICAL_HIERARCHY    = NO
+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
-DOT_CLEANUP            = YES
+GENERATE_LEGEND        = NO
+DOT_CLEANUP            = NO
 #---------------------------------------------------------------------------
 # Configuration::additions related to the search engine   
 #---------------------------------------------------------------------------
diff --git a/doc/benchmark.cpp b/doc/benchmark.cpp
index 2bf445ed5..bf476acda 100644
--- a/doc/benchmark.cpp
+++ b/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[])
 {
diff --git a/doc/example.cpp b/doc/example.cpp
index 8b2608655..66c51b2c3 100644
--- a/doc/example.cpp
+++ b/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;
 }
diff --git a/doc/examples/class_Block.cpp b/doc/examples/class_Block.cpp
new file mode 100644
index 000000000..17dc4bce1
--- /dev/null
+++ b/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;
+}
diff --git a/doc/examples/class_Cast.cpp b/doc/examples/class_Cast.cpp
new file mode 100644
index 000000000..d1dfdc8be
--- /dev/null
+++ b/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;
+}
diff --git a/doc/examples/class_Column.cpp b/doc/examples/class_Column.cpp
new file mode 100644
index 000000000..ec8628ab7
--- /dev/null
+++ b/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;
+}
diff --git a/doc/examples/class_DynBlock.cpp b/doc/examples/class_DynBlock.cpp
index 8407d8733..3a8b607da 100644
--- a/doc/examples/class_DynBlock.cpp
+++ b/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);
 }
diff --git a/doc/examples/class_Row.cpp b/doc/examples/class_Row.cpp
new file mode 100644
index 000000000..70a388015
--- /dev/null
+++ b/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;
+}
diff --git a/doc/snippets/MatrixBase_block.cpp b/doc/snippets/MatrixBase_block.cpp
new file mode 100644
index 000000000..0a1b6d6d3
--- /dev/null
+++ b/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;
diff --git a/doc/snippets/MatrixBase_cast.cpp b/doc/snippets/MatrixBase_cast.cpp
new file mode 100644
index 000000000..f59b97df6
--- /dev/null
+++ b/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;
diff --git a/doc/snippets/MatrixBase_col.cpp b/doc/snippets/MatrixBase_col.cpp
new file mode 100644
index 000000000..ae287db32
--- /dev/null
+++ b/doc/snippets/MatrixBase_col.cpp
@@ -0,0 +1,3 @@
+Matrix3d m = Matrix3d::identity();
+m.col(1) = Vector3d(4,5,6);
+cout << m << endl;
diff --git a/doc/snippets/MatrixBase_dynBlock.cpp b/doc/snippets/MatrixBase_dynBlock.cpp
index 5ca7655ed..4fc6aceb3 100644
--- a/doc/snippets/MatrixBase_dynBlock.cpp
+++ b/doc/snippets/MatrixBase_dynBlock.cpp
@@ -1,3 +1,3 @@
-Matrix4d m = Matrix4d::identity();
-m.dynBlock(2,0,2,2) = m.dynBlock(0,0,2,2);
+Matrix3d m = Matrix3d::diagonal(Vector3d(1,2,3));
+m.dynBlock(1, 0, 2, 1) = m.dynBlock(1, 1, 2, 1);
 cout << m << endl;
diff --git a/doc/snippets/MatrixBase_row.cpp b/doc/snippets/MatrixBase_row.cpp
new file mode 100644
index 000000000..3f1d73b9e
--- /dev/null
+++ b/doc/snippets/MatrixBase_row.cpp
@@ -0,0 +1,3 @@
+Matrix3d m = Matrix3d::identity();
+m.row(1) = Vector3d(4,5,6);
+cout << m << endl;
diff --git a/doc/snippets/compile_snippet.cpp.in b/doc/snippets/compile_snippet.cpp.in
index 952a3ee81..9f7d568e5 100644
--- a/doc/snippets/compile_snippet.cpp.in
+++ b/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**)
 {
diff --git a/doc/tutorial.cpp b/doc/tutorial.cpp
index e98e1c07a..63ed3e5a5 100644
--- a/doc/tutorial.cpp
+++ b/doc/tutorial.cpp
@@ -1,6 +1,6 @@
 #include <Eigen/Core.h>
 
-USING_EIGEN_DATA_TYPES
+USING_PART_OF_NAMESPACE_EIGEN
 
 using namespace std;