[Boost-commit] svn:boost r62929 - branches/ublas-doxygen

Subject: [Boost-commit] svn:boost r62929 - branches/ublas-doxygen
From: david.bellot_at_[hidden]
Date: 2010-06-14 08:10:45

Author: david.bellot
Date: 2010-06-14 08:10:45 EDT (Mon, 14 Jun 2010)
New Revision: 62929
URL: http://svn.boost.org/trac/boost/changeset/62929

Log:
more doc on vector. Official doc for vector_indirect

Text files modified: 
   branches/ublas-doxygen/vector_proxy.hpp  |    54 +++++++++++++++++++++++++++++++-------- 
   branches/ublas-doxygen/vector_sparse.hpp |    51 ++++++++++++++++++++++++++++++++++---   
   2 files changed, 89 insertions(+), 16 deletions(-)

Modified: branches/ublas-doxygen/vector_proxy.hpp
==============================================================================
--- branches/ublas-doxygen/vector_proxy.hpp	(original)
+++ branches/ublas-doxygen/vector_proxy.hpp	2010-06-14 08:10:45 EDT (Mon, 14 Jun 2010)
@@ -21,16 +21,15 @@
 
 namespace boost { namespace numeric { namespace ublas {
 
-    // ------------------------
-    // Vector based range class
-    // ------------------------
-
-    /// \brief A subvector defined by a range on another vector. It is used as a normal vector.
-    /// A subvector defined by a range on another vector. It is used as a normal vector.
-    /// After being defined it allows the manipulation of a subvector like a normal vector.
-    /// If the specified range falls outside that of of the index range of the vector, then
-    /// the \c vector_range is not a well formed Vector Expression and access to an element
-    /// outside of index range of the vector is \b undefined.
+    /** \brief A vector referencing a continuous subvector of elements of vector \c v containing all elements specified by \c range.
+     *
+     * A vector range can be used as a normal vector in any expression. 
+     * If the specified range falls outside that of the index range of the vector, then
+     * the \c vector_range is not a well formed \i Vector \i Expression and access to an 
+     * element outside of index range of the vector is \b undefined.
+     *
+     * \tparam V the type of vector referenced (for example \c vector<double>)
+     */
     template<class V>
     class vector_range:
         public vector_expression<vector_range<V> > {
@@ -565,7 +564,20 @@
     : vector_temporary_traits< V > {} ;
 
 
-    // Vector based slice class
+    /** \brief A vector referencing a non continuous subvector of elements of vector v containing all elements specified by \c slice.
+     *
+     * A vector slice can be used as a normal vector in any expression.
+     * If the specified slice falls outside that of the index slice of the vector, then
+     * the \c vector_slice is not a well formed \i Vector \i Expression and access to an 
+     * element outside of index slice of the vector is \b undefined.
+     *
+     * A slice is a generalization of a range. In a range going from \f$a\f$ to \f$b\f$, 
+     * all elements belong to the range. In a slice, a \i \f$step\f$ can be specified meaning to
+     * take one element over \f$step\f$ in the range specified from \$fa\f$ to \f$b\f$.
+     * Obviously, a slice with a \f$step\f$ of 1 is equivalent to a range.
+     *
+     * \tparam V the type of vector referenced (for example \c vector<double>)
+     */
     template<class V>
     class vector_slice:
         public vector_expression<vector_slice<V> > {
@@ -1089,6 +1101,26 @@
     // Vector based indirection class
     // Contributed by Toon Knapen.
     // Extended and optimized by Kresimir Fresl.
+
+    /** \brief A vector referencing a non continuous subvector of elements given another vector of indices.
+     *
+     * It is the most general version of any subvectors because it uses another vector of indices to reference
+     * the subvector. 
+     *
+     * The vector of indices can be of any type with the restriction that its elements must be
+     * type-compatible with the size_type \c of the container. In practice, the following are good candidates:
+     * - \c boost::numeric::ublas::indirect_array<A> where \c A can be \c int, \c size_t, \c long, etc...
+     * - \c std::vector<A> where \c A can \c int, \c size_t, \c long, etc...
+     * - \c boost::numeric::ublas::vector<int> can work too (\c int can be replaced by another integer type)
+     * - etc...
+     *
+     * An indirect vector can be used as a normal vector in any expression. If the specified indirect vector 
+     * falls outside that of the indices of the vector, then the \c vector_indirect is not a well formed 
+     * \i Vector \i Expression and access to an element outside of indices of the vector is \b undefined.
+     *
+     * \tparam V the type of vector referenced (for example \c vector<double>)
+     * \tparam IA the type of index vector. Default is \c ublas::indirect_array<>
+     */
     template<class V, class IA>
     class vector_indirect:
         public vector_expression<vector_indirect<V, IA> > {

Modified: branches/ublas-doxygen/vector_sparse.hpp
==============================================================================
--- branches/ublas-doxygen/vector_sparse.hpp	(original)
+++ branches/ublas-doxygen/vector_sparse.hpp	2010-06-14 08:10:45 EDT (Mon, 14 Jun 2010)
@@ -273,8 +273,8 @@
      * Supported parameters for the adapted array are \c map_array<std::size_t, T> and 
      * \c map_std<std::size_t, T>. The latter is equivalent to \c std::map<std::size_t, T>.
      *
-     * \tparam T
-     * \tparam A
+     * \tparam T the type of object stored in the vector (like double, float, complex, etc...)
+     * \tparam A the type of Storage array
      */
     template<class T, class A>
     class mapped_vector:
@@ -770,8 +770,29 @@
     const typename mapped_vector<T, A>::value_type mapped_vector<T, A>::zero_ = value_type/*zero*/();
 
 
-    // Compressed array based sparse vector class
     // Thanks to Kresimir Fresl for extending this to cover different index bases.
+    
+    /** \brief Compressed array based sparse vector
+     *
+     * a sparse vector of values of type T of variable size. The non zero values are stored as 
+     * two seperate arrays: an index array and a value array. The index array is always sorted 
+     * and there is at most one entry for each index. Inserting an element can be time consuming.
+     * If the vector contains a few zero entries, then it is better to have a normal vector.
+     * If the vector has a very high dimension with a few non-zero values, then this vector is
+     * very memory efficient (at the cost of a few more computations).
+     *
+     * For a \f$n\f$-dimensional compressed vector and \f$0 \leq i < n\f$ the non-zero elements 
+     * \f$v_i\f$ are mapped to consecutive elements of the index and value container, i.e. for 
+     * elements \f$k = v_i_1\f$ and \f$k + 1 = v_i_2\f$ of these containers holds \f$i_1 < i_2\f$.
+     *
+     * Supported parameters for the adapted array (indices and values) are \c unbounded_array<> ,
+     * \c bounded_array<> and \c std::vector<>.
+     *
+     * \tparam T the type of object stored in the vector (like double, float, complex, etc...)
+     * \tparam IB the index base of the compressed vector. Default is 0. Other supported value is 1
+     * \tparam IA the type of adapted array for indices. Default is \c unbounded_array<std::size_t>
+     * \tparam TA the type of adapted array for values. Default is unbounded_array<T>
+     */
     template<class T, std::size_t IB, class IA, class TA>
     class compressed_vector:
         public vector_container<compressed_vector<T, IB, IA, TA> > {
@@ -1389,9 +1410,29 @@
     template<class T, std::size_t IB, class IA, class TA>
     const typename compressed_vector<T, IB, IA, TA>::value_type compressed_vector<T, IB, IA, TA>::zero_ = value_type/*zero*/();
 
-
-    // Coordimate array based sparse vector class
     // Thanks to Kresimir Fresl for extending this to cover different index bases.
+
+    /** \brief Coordimate array based sparse vector
+     *
+     * a sparse vector of values of type \c T of variable size. The non zero values are stored 
+     * as two seperate arrays: an index array and a value array. The arrays may be out of order 
+     * with multiple entries for each vector element. If there are multiple values for the same 
+     * index the sum of these values is the real value. It is way more efficient for inserting values
+     * than a \c compressed_vector but less memory efficient. Also linearly parsing a vector can 
+     * be longer in specific cases than a \c compressed_vector.
+     *
+     * For a n-dimensional sorted coordinate vector and \f$ 0 \leq i < n\f$ the non-zero elements 
+     * \f$v_i\f$ are mapped to consecutive elements of the index and value container, i.e. for 
+     * elements \f$k = v_i_1\f$and \f$k + 1 = v_i_2\f$of these containers holds \f$i_1 < i_2\f$.
+     *
+     * Supported parameters for the adapted array (indices and values) are \c unbounded_array<> ,
+     * \c bounded_array<> and \c std::vector<>.
+     *
+     * \tparam T the type of object stored in the vector (like double, float, complex, etc...)
+     * \tparam IB the index base of the compressed vector. Default is 0. Other supported value is 1
+     * \tparam IA the type of adapted array for indices. Default is \c unbounded_array<std::size_t>
+     * \tparam TA the type of adapted array for values. Default is unbounded_array<T>
+     */
     template<class T, std::size_t IB, class IA, class TA>
     class coordinate_vector:
         public vector_container<coordinate_vector<T, IB, IA, TA> > {