io done

svn path=/branches/ublas-doxygen/; revision=63481

io.hpp

@@ -21,7 +21,28 @@
 
 namespace boost { namespace numeric { namespace ublas {
 
-    /** \brief Output operator*/
+    /** \brief output stream operator for vector expressions
+     *
+     * In fact, you can simply output any vector expression to a standard output stream
+     * as defined in the C++ standard library. For example:
+     * \code
+     * vector<float> v1(3),v2(3);
+     * for(size_t i=0; i<3; i++)
+     * {
+     *       v1(i) = i+0.2;
+     *       v2(i) = i+0.3;
+     * }
+     * cout << v1+v2 << endl;
+     * \endcode
+     * will display the some of the 2 vectors like this:
+     * \code
+     * [3](0.5,2.5,4.5)
+     * \endcode
+     *
+     * \param os is a standard basic output stream
+     * \param v is a vector expression
+     * \return a reference to the resulting output stream
+     */
     template<class E, class T, class VE>
     // BOOST_UBLAS_INLINE This function seems to be big. So we do not let the compiler inline it.
     std::basic_ostream<E, T> &operator << (std::basic_ostream<E, T> &os,
@@ -41,6 +62,28 @@ namespace boost { namespace numeric { namespace ublas {
         return os << s.str ().c_str ();
     }
 
+    /** \brief input stream operator for vectors
+     *
+     * This is used to feed in vectors with data stored as an ASCII representation
+     * from a standard input stream.
+     *
+     * From a file or any valid stream, the format is: 
+     * \c [<vector size>](<data1>,<data2>,...<dataN>) like for example:
+     * \code
+     * [5](1,2.1,3.2,3.14,0.2)
+     * \endcode
+     *
+     * You can use it like this
+     * \code
+     * my_input_stream >> my_vector;
+     * \endcode
+     *
+     * You can only put data into a valid \c vector<> not a \c vector_expression
+     *
+     * \param is is a standard basic input stream
+     * \param v is a vector
+     * \return a reference to the resulting input stream
+     */
     template<class E, class T, class VT, class VA>
     // BOOST_UBLAS_INLINE This function seems to be big. So we do not let the compiler inline it.
     std::basic_istream<E, T> &operator >> (std::basic_istream<E, T> &is,
@@ -79,6 +122,29 @@ namespace boost { namespace numeric { namespace ublas {
         return is;
     }
 
+    /** \brief output stream operator for matrix expressions
+     *
+     * it outpus the content of a \f$(M \times N)\f$ matrix to a standard output 
+     * stream using the following format:
+     * \c[<rows>,<columns>]((<m00>,<m01>,...,<m0N>),...,(<mM0>,<mM1>,...,<mMN>))
+     *
+     * For example:
+     * \code
+     * matrix<float> m(3,3) = scalar_matrix<float>(3,3,1.0) - diagonal_matrix<float>(3,3,1.0);
+     * cout << m << endl;
+     * \encode
+     * will display
+     * \code
+     * [3,3]((0,1,1),(1,0,1),(1,1,0))
+     * \endcode
+     * This output is made for storing and retrieving matrices in a simple way but you can
+     * easily recognize the following: 
+     * \f[ \left( \begin{array}[ccc] 1 & 1 & 1\\ 1 & 1 & 1\\ 1 & 1 & 1 \end{array} \right) - \left( \begin{array}[ccc] 1 & 0 & 1\\ 0 & 1 & 0\\ 0 & 0 & 1 \end{array} \right) = \left( \begin{array}[ccc] 0 & 1 & 1\\ 1 & 0 & 1\\ 1 & 1 & 0 \end{array} \right)
+     *
+     * \param os is a standard basic output stream
+     * \param m is a matrix expression
+     * \return a reference to the resulting output stream
+     */
     template<class E, class T, class ME>
     // BOOST_UBLAS_INLINE This function seems to be big. So we do not let the compiler inline it.
     std::basic_ostream<E, T> &operator << (std::basic_ostream<E, T> &os,
@@ -111,6 +177,25 @@ namespace boost { namespace numeric { namespace ublas {
         return os << s.str ().c_str ();
     }
 
+    /** \brief input stream operator for matrices
+     *
+     * This is used to feed in matrices with data stored as an ASCII representation
+     * from a standard input stream.
+     *
+     * From a file or any valid standard stream, the format is:
+     * \c[<rows>,<columns>]((<m00>,<m01>,...,<m0N>),...,(<mM0>,<mM1>,...,<mMN>))
+     *
+     * You can use it like this
+     * \code
+     * my_input_stream >> my_matrix;
+     * \endcode
+     *
+     * You can only put data into a valid \c matrix<> not a \c matrix_expression
+     *
+     * \param is is a standard basic input stream
+     * \param m is a matrix
+     * \return a reference to the resulting input stream
+     */
     template<class E, class T, class MT, class MF, class MA>
     // BOOST_UBLAS_INLINE This function seems to be big. So we do not let the compiler inline it.
     std::basic_istream<E, T> &operator >> (std::basic_istream<E, T> &is,
@@ -172,7 +257,27 @@ namespace boost { namespace numeric { namespace ublas {
         return is;
     }
 
-    // Special input operator for symmetrix_matrix
+    /** \brief special input stream operator for symmetric matrices
+     *
+     * This is used to feed in symmetric matrices with data stored as an ASCII 
+     * representation from a standard input stream.
+     *
+     * You can simply write your matrices in a file or any valid stream and read them again 
+     * at a later time with this function. The format is the following:
+     * \c[<rows>,<columns>]((<m00>,<m01>,...,<m0N>),...,(<mM0>,<mM1>,...,<mMN>))
+     *
+     * You can use it like this
+     * \code
+     * my_input_stream >> my_symmetric_matrix;
+     * \endcode
+     *
+     * You can only put data into a valid \c symmetric_matrix<> not a \c matrix_expression
+     * This function also checks that input data form a valid symmetric matrix
+     *
+     * \param is is a standard basic input stream
+     * \param m is a \c symmetric_matrix
+     * \return a reference to the resulting input stream
+     */
     template<class E, class T, class MT, class MF1, class MF2, class MA>
     // BOOST_UBLAS_INLINE This function seems to be big. So we do not let the compiler inline it.
     std::basic_istream<E, T> &operator >> (std::basic_istream<E, T> &is,