diff --git a/vector_proxy.hpp b/vector_proxy.hpp index 8654c1eb..d90c6b74 100644 --- a/vector_proxy.hpp +++ b/vector_proxy.hpp @@ -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) + */ template class vector_range: public vector_expression > { @@ -565,7 +564,20 @@ namespace boost { namespace numeric { namespace ublas { : 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) + */ template class vector_slice: public vector_expression > { @@ -1089,6 +1101,26 @@ namespace boost { namespace numeric { namespace ublas { // 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 where \c A can be \c int, \c size_t, \c long, etc... + * - \c std::vector where \c A can \c int, \c size_t, \c long, etc... + * - \c boost::numeric::ublas::vector 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) + * \tparam IA the type of index vector. Default is \c ublas::indirect_array<> + */ template class vector_indirect: public vector_expression > { diff --git a/vector_sparse.hpp b/vector_sparse.hpp index edde0440..de7c3103 100644 --- a/vector_sparse.hpp +++ b/vector_sparse.hpp @@ -273,8 +273,8 @@ namespace boost { namespace numeric { namespace ublas { * Supported parameters for the adapted array are \c map_array and * \c map_std. The latter is equivalent to \c std::map. * - * \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 mapped_vector: @@ -770,8 +770,29 @@ namespace boost { namespace numeric { namespace ublas { const typename mapped_vector::value_type mapped_vector::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 + * \tparam TA the type of adapted array for values. Default is unbounded_array + */ template class compressed_vector: public vector_container > { @@ -1389,9 +1410,29 @@ namespace boost { namespace numeric { namespace ublas { template const typename compressed_vector::value_type compressed_vector::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 + * \tparam TA the type of adapted array for values. Default is unbounded_array + */ template class coordinate_vector: public vector_container > {