* add documentation of the cool (?) "print with format" feature

* move the ioformat.cpp test to a documentation example
* rename IoFormat => IOFormat

Eigen/src/Core/Cwise.h

@@ -68,7 +68,7 @@ template<typename ExpressionType> class Cwise
     inline const ExpressionType& _expression() const { return m_matrix; }
 
     template<typename OtherDerived>
-	const EIGEN_CWISE_BINOP_RETURN_TYPE(ei_scalar_product_op)
+    const EIGEN_CWISE_BINOP_RETURN_TYPE(ei_scalar_product_op)
     operator*(const MatrixBase<OtherDerived> &other) const;
 
     template<typename OtherDerived>

Eigen/src/Core/IO.h

@@ -27,9 +27,29 @@
 
 enum { Raw, AlignCols };
 
-struct IoFormat
+/** \class IOFormat
+  *
+  * \brief Stores a set of parameters controlling the way matrices are printed
+  *
+  * List of available parameters:
+  *  - \b precision number of digits for floating point values
+  *  - \b flags can be either Raw (default) or AlignCols which aligns all the columns
+  *  - \b coeffSeparator string printed between two coefficients of the same row
+  *  - \b rowSeparator string printed between two rows
+  *  - \b rowPrefix string printed at the begining of each row
+  *  - \b rowSuffix string printed at the end of each row
+  *  - \b matPrefix string printed at the begining of the matrix
+  *  - \b matSuffix string printed at the end of the matrix
+  *
+  * Example: \include IOFormat.cpp
+  * Output: \verbinclude IOFormat.out
+  *
+  * \sa MatrixBase::format(), class WithFormat
+  */
+struct IOFormat
 {
-  IoFormat(int _precision=4, int _flags=Raw,
+  /** Default contructor, see class IOFormat for the meaning of the parameters */
+  IOFormat(int _precision=4, int _flags=Raw,
     const std::string& _coeffSeparator = " ",
     const std::string& _rowSeparator = "\n", const std::string& _rowPrefix="", const std::string& _rowSuffix="",
     const std::string& _matPrefix="", const std::string& _matSuffix="")
@@ -51,12 +71,26 @@ struct IoFormat
   int flags;
 };
 
+/** \class WithFormat
+  *
+  * \brief Pseudo expression providing matrix output with given format
+  *
+  * \param ExpressionType the type of the object on which IO stream operations are performed
+  *
+  * This class represents an expression with stream operators controlled by a given IOFormat.
+  * It is the return type of MatrixBase::format()
+  * and most of the time this is the only way it is used.
+  * 
+  * See class IOFormat for some examples.
+  *
+  * \sa MatrixBase::format(), class IOFormat
+  */
 template<typename ExpressionType>
 class WithFormat
 {
   public:
 
-    WithFormat(const ExpressionType& matrix, const IoFormat& format)
+    WithFormat(const ExpressionType& matrix, const IOFormat& format)
       : m_matrix(matrix), m_format(format)
     {}
 
@@ -67,19 +101,28 @@ class WithFormat
 
   protected:
     const typename ExpressionType::Nested m_matrix;
-    IoFormat m_format;
+    IOFormat m_format;
 };
 
+/** \returns a WithFormat proxy object allowing to print a matrix the with given
+  * format \a fmt.
+  *
+  * See class IOFormat for some examples.
+  *
+  * \sa class IOFormat, class WithFormat
+  */
 template<typename Derived>
 inline const WithFormat<Derived>
-MatrixBase<Derived>::format(const IoFormat& fmt) const
+MatrixBase<Derived>::format(const IOFormat& fmt) const
 {
   return WithFormat<Derived>(derived(), fmt);
 }
 
+/** \internal
+  * print the matrix \a _m to the output stream \a s using the output format \a fmt */
 template<typename Derived>
 std::ostream & ei_print_matrix(std::ostream & s, const MatrixBase<Derived> & _m,
-                               const IoFormat& fmt = IoFormat())
+                               const IOFormat& fmt = IOFormat())
 {
   const typename Derived::Nested m = _m;
   int width = 0;
@@ -121,6 +164,9 @@ std::ostream & ei_print_matrix(std::ostream & s, const MatrixBase<Derived> & _m,
 /** \relates MatrixBase
   *
   * Outputs the matrix, laid out as an array as usual, to the given stream.
+  * You can control the way the matrix is printed using MatrixBase::format().
+  *
+  * \sa MatrixBase::format()
   */
 template<typename Derived>
 std::ostream & operator <<

Eigen/src/Core/MatrixBase.h

@@ -525,7 +525,7 @@ template<typename Derived> class MatrixBase
     const Cwise<Derived> cwise() const;
     Cwise<Derived> cwise();
 
-    inline const WithFormat<Derived> format(const IoFormat& fmt) const;
+    inline const WithFormat<Derived> format(const IOFormat& fmt) const;
 
 /////////// Array module ///////////
 

Eigen/src/Core/util/ForwardDeclarations.h

@@ -82,7 +82,7 @@ template<typename Scalar> struct ei_scalar_max_op;
 template<typename Scalar> struct ei_scalar_random_op;
 template<typename Scalar> struct ei_scalar_add_op;
 
-struct IoFormat;
+struct IOFormat;
 
 template<typename Scalar>
 void ei_cache_friendly_product(

doc/snippets/IOFormat.cpp

@@ -1,6 +1,6 @@
 std::string sep = "\n----------------------------------------\n";
 Matrix3f m1;
-m1 << 0, 1.111111, 2, 3.33333, 4, 5, 6, 7, 8.888888, 9;
+m1 << 1.111111, 2, 3.33333, 4, 5, 6, 7, 8.888888, 9;
 
 IOFormat CommaInitFmt(4, Raw, ", ", ", ", "", "", " << ", ";");
 IOFormat CleanFmt(4, AlignCols, ", ", "\n", "[", "]");

test/CMakeLists.txt

@@ -118,7 +118,6 @@ EI_ADD_TEST(eigensolver)
 EI_ADD_TEST(geometry)
 EI_ADD_TEST(regression)
 EI_ADD_TEST(svd)
-EI_ADD_TEST(ioformat)
 EI_ADD_TEST(sparse)
 
 ENDIF(BUILD_TESTS)

test/ioformat.cpp

@@ -1,44 +0,0 @@
-// This file is part of Eigen, a lightweight C++ template library
-// for linear algebra. Eigen itself is part of the KDE project.
-//
-// Copyright (C) 2006-2008 Benoit Jacob <jacob@math.jussieu.fr>
-//
-// Eigen is free software; you can redistribute it and/or
-// modify it under the terms of the GNU Lesser General Public
-// License as published by the Free Software Foundation; either
-// version 3 of the License, or (at your option) any later version.
-//
-// Alternatively, you can redistribute it and/or
-// modify it under the terms of the GNU General Public License as
-// published by the Free Software Foundation; either version 2 of
-// the License, or (at your option) any later version.
-//
-// Eigen is distributed in the hope that it will be useful, but WITHOUT ANY
-// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
-// FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License or the
-// GNU General Public License for more details.
-//
-// You should have received a copy of the GNU Lesser General Public
-// License and a copy of the GNU General Public License along with
-// Eigen. If not, see <http://www.gnu.org/licenses/>.
-
-#include "main.h"
-
-void test_ioformat()
-{
-  std::string sep = "\n\n----------------------------------------\n\n";
-  Matrix4f m1;
-  m1 << 0, 1.111111, 2, 3.33333, 4, 5, 6, 7, 8.888888, 9, 10, 11, 12, 13, 14, 15;
-
-  IoFormat CommaInitFmt(4, Raw, ", ", ", ", "", "", " << ", ";");
-  IoFormat CleanFmt(4, AlignCols, ", ", "\n", "[", "]");
-  IoFormat OctaveFmt(4, AlignCols, ", ", ";\n", "", "", "[", "]");
-  IoFormat HeavyFmt(4, AlignCols, ", ", ";\n", "[", "]", "[", "]");
-  
-  
-  std::cout << m1 << sep;
-  std::cout << m1.format(CommaInitFmt) << sep;
-  std::cout << m1.format(CleanFmt) << sep;
-  std::cout << m1.format(OctaveFmt) << sep;
-  std::cout << m1.format(HeavyFmt) << sep;
-}