|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r62109 - branches/ublas-doxygen
From: david.bellot_at_[hidden]
Date: 2010-05-20 08:49:25
Author: david.bellot
Date: 2010-05-20 08:49:23 EDT (Thu, 20 May 2010)
New Revision: 62109
URL: http://svn.boost.org/trac/boost/changeset/62109
Log:
documentation on vector types
Text files modified:
branches/ublas-doxygen/blas.hpp | 23 ++++++--------
branches/ublas-doxygen/doxydoc.hpp | 22 +------------
branches/ublas-doxygen/vector.hpp | 62 +++++++++++++++++++++++++++++----------
3 files changed, 58 insertions(+), 49 deletions(-)
Modified: branches/ublas-doxygen/blas.hpp
==============================================================================
--- branches/ublas-doxygen/blas.hpp (original)
+++ branches/ublas-doxygen/blas.hpp 2010-05-20 08:49:23 EDT (Thu, 20 May 2010)
@@ -16,14 +16,13 @@
#include <boost/numeric/ublas/traits.hpp>
namespace boost { namespace numeric { namespace ublas {
+
+ /// \brief Interface and implementation of BLAS level 1
+ /// Interface and implementation of BLAS level 1. This includes functions which perform vector-vector operations.
+ /// More information about BLAS can be found at http://en.wikipedia.org/wiki/BLAS
namespace blas_1 {
- /** \namespace boost::numeric::ublas::blas_1
- \brief wrapper functions for level 1 blas
- */
-
-
/** \brief 1-Norm: \f$\sum_i |x_i|\f$
\ingroup blas1
*/
@@ -107,12 +106,11 @@
}
+ /// \brief Interface and implementation of BLAS level 2
+ /// Interface and implementation of BLAS level 2. This includes functions which perform matrix-vector operations.
+ /// More information about BLAS can be found at http://en.wikipedia.org/wiki/BLAS
namespace blas_2 {
- /** \namespace boost::numeric::ublas::blas_2
- \brief wrapper functions for level 2 blas
- */
-
/** \brief multiply vector \a v with triangular matrix \a m
\ingroup blas2
\todo: check that matrix is really triangular
@@ -209,12 +207,11 @@
}
+ /// \brief Interface and implementation of BLAS level 3
+ /// Interface and implementation of BLAS level 3. This includes functions which perform matrix-matrix operations.
+ /// More information about BLAS can be found at http://en.wikipedia.org/wiki/BLAS
namespace blas_3 {
- /** \namespace boost::numeric::ublas::blas_3
- \brief wrapper functions for level 3 blas
- */
-
/** \brief triangular matrix multiplication
\ingroup blas3
*/
Modified: branches/ublas-doxygen/doxydoc.hpp
==============================================================================
--- branches/ublas-doxygen/doxydoc.hpp (original)
+++ branches/ublas-doxygen/doxydoc.hpp 2010-05-20 08:49:23 EDT (Thu, 20 May 2010)
@@ -1,23 +1,5 @@
-/// \class boost::numeric::ublas::c_matrix::const_iterator1
-/// \brief An iterator on const values from a column perspective
-/// An iterator on const values from a column perspective: if it points to a matrix value at \f$(i,j)\f$, incrementing it (resp. decrementing it) will make it point to \f$(i+1,j)\f$ (resp. \f$(i-1,j\f$) assuming this position is valid. It has reached the bottom of the matrix when its value equals end1().
-/// Iterator1 follows the same semantic as STL iterators. Setting its value to begin()1 will point it to the position \f$(0,0)\f$ of the matrix. To start at another column the method find() can be used (e.g. find(0,10) to start at the 11-th column).
-
+///
/// \class boost::numeric::ublas::c_vector
/// \brief An array based vector class which size is defined at type specification or object instanciation.
/// An array based matrix class which size is defined at type specification or object instanciation. This matrix is directly based on a predefinec C-style arry of data, thus providing the fastest implementation possible. The constraint is that dimensions of the matrix must be specified at the instanciation or the type specification. For instance, \code typedef c_matrix<double,4,4> my_4by4_matrix\encode defines a 4x4 double-precision matrix. You can also instantiate it directly with \code c_matrix<int,8,5> my_fast_matrix\endcode. This will make a 8 by 5 integer matrix. The price to pay for this speed is that you cannot resize it to a size larger than the one defined in the template parameters. In the previous example, a size of 4 by 5 or 3 by 2 is acceptable, but a new size of 9 by 5 or even 10 by 10 will raise a bad_size() exception.
-
-/// \namespace boost::numeric::ublas::blas_1
-/// \brief Interface and implementation of BLAS level 1
-/// Interface and implementation of BLAS level 1. This includes functions which perform vector-vector operations.
-/// More information about BLAS can be found at http://en.wikipedia.org/wiki/BLAS
-
-/// \namespace boost::numeric::ublas::blas_2
-/// \brief Interface and implementation of BLAS level 2
-/// Interface and implementation of BLAS level 2. This includes functions which perform matrix-vector operations.
-/// More information about BLAS can be found at http://en.wikipedia.org/wiki/BLAS
-
-/// \namespace boost::numeric::ublas::blas_3
-/// \brief Interface and implementation of BLAS level 3
-/// Interface and implementation of BLAS level 3. This includes functions which perform matrix-matrix operations.
-/// More information about BLAS can be found at http://en.wikipedia.org/wiki/BLAS
+///
Modified: branches/ublas-doxygen/vector.hpp
==============================================================================
--- branches/ublas-doxygen/vector.hpp (original)
+++ branches/ublas-doxygen/vector.hpp 2010-05-20 08:49:23 EDT (Thu, 20 May 2010)
@@ -26,10 +26,11 @@
namespace boost { namespace numeric { namespace ublas {
- /// \brief Array-based vector class
- ///
- /// Array-based vector class: this templated vector class is the base container adaptor for dense vectors. For a \f$n\-dimensional vector \f$v\f$ and \f$0 \leq i < n\f$ every element \f$v_i\f$ is mapped to the \f$i\f$-th element of the container. The 2 templates parameters respectively defines the following:
- /// \tparam T type of the objects stored in the vector: it can be anything even if most of the time, scalar types will be used like \c double or \c int. Complex types can be used, or even classes.
+ /// \brief The classical dense vector
+ /// A dense vector of values of type \c T of variable size. A storage type \c A can be specified which defaults to \c unbounded_array.
+ /// Elements are constructed by \c A, which need not initialise their value. For a \f$n\-dimensional vector \f$v\f$ and \f$0 \leq i < n\f$
+ /// every element \f$v_i\f$ is mapped to the \f$i\f$-th element of the container.
+ /// \tparam T type of the objects stored in the vector: it can be anything even if most of the time, scalar types will be used like \c double or \c int. Complex types can be used, or even classes like boost::interval.
/// \tparam A The type of the storage array of the vector. By default it is \c unbounded_array<T>. Common other value can be \c <bounded_array<T> and \c std::vector<T>.
/// Also note that, expect when making an empty vector, all other constructors imply a \f$O(n)\f$ time complexity during construction due to the initialization. Because \e uBLAS tries to avoid the creation of temporaries into expressions, this penalty only occurs when explicitely creating vectors in your code. If you want to create many vectors without initialization, consider using a different storage type like \c std::vector<T> for example.
template<class T, class A>
@@ -134,7 +135,7 @@
// -----------------------
/// \brief Return the maximum size of the data container.
- /// Return the upper bound (maximum size) on the data container. Depending on the container, it can be bigger of the current size of the vector.
+ /// Return the upper bound (maximum size) on the data container. Depending on the container, it can be bigger than the current size of the vector.
BOOST_UBLAS_INLINE
size_type max_size () const {
return data_.max_size ();
@@ -214,6 +215,7 @@
// --------------
/// \brief Return a const reference to the element \f$i\f$
+ /// Return a const reference to the element \f$i\f$. With some compilers, this notation will be faster than \c[i]
/// \param i index of the element
BOOST_UBLAS_INLINE
const_reference operator () (size_type i) const {
@@ -221,6 +223,7 @@
}
/// \brief Return a reference to the element \f$i\f$
+ /// Return a reference to the element \f$i\f$. With some compilers, this notation will be faster than \c[i]
/// \param i index of the element
BOOST_UBLAS_INLINE
reference operator () (size_type i) {
@@ -474,9 +477,6 @@
typedef typename A::iterator subiterator_type;
public:
- /// \typedef iterator
- /// \typedef const_iterator
-
#ifdef BOOST_UBLAS_USE_INDEXED_ITERATOR
typedef indexed_iterator<self_type, dense_random_access_iterator_tag> iterator;
typedef indexed_const_iterator<self_type, dense_random_access_iterator_tag> const_iterator;
@@ -744,10 +744,13 @@
};
#endif
+ /// \brief Return an iterator on the first element of the vector
BOOST_UBLAS_INLINE
iterator begin () {
return find (0);
}
+
+ /// \brief Return an iterator at the end of the vector
BOOST_UBLAS_INLINE
iterator end () {
return find (data_.size ());
@@ -757,24 +760,37 @@
typedef reverse_iterator_base<const_iterator> const_reverse_iterator;
typedef reverse_iterator_base<iterator> reverse_iterator;
+ /// \brief Return a const reverse iterator before the first element of the reversed vector (i.e. end() of normal vector)
BOOST_UBLAS_INLINE
const_reverse_iterator rbegin () const {
return const_reverse_iterator (end ());
}
+
+ /// \brief Return a const reverse iterator on the end of the reverse vector (i.e. first element of the normal vector)
BOOST_UBLAS_INLINE
const_reverse_iterator rend () const {
return const_reverse_iterator (begin ());
}
+
+ /// \brief Return a const reverse iterator before the first element of the reversed vector (i.e. end() of normal vector)
BOOST_UBLAS_INLINE
reverse_iterator rbegin () {
return reverse_iterator (end ());
}
+
+ /// \brief Return a const reverse iterator on the end of the reverse vector (i.e. first element of the normal vector)
BOOST_UBLAS_INLINE
reverse_iterator rend () {
return reverse_iterator (begin ());
}
+ // -------------
// Serialization
+ // -------------
+
+ /// Serialize a vector into and archive as defined in Boost
+ /// \param ar Archive object. Can be a flat file, an XML file or any other stream
+ /// \param file_version Optional file version (not yet used)
template<class Archive>
void serialize(Archive & ar, const unsigned int /* file_version */){
ar & serialization::make_nvp("data",data_);
@@ -785,7 +801,13 @@
};
+ // --------------------
// Bounded vector class
+ // --------------------
+
+ /// \brief a dense vector of values of type \c T, of variable size but with maximum \f$N\f$.
+ /// A dense vector of values of type \c T, of variable size but with maximum \f$N\f$. The default constructor
+ /// creates the vector with size \f$N\f$. Elements are constructed by the storage type \c bounded_array, which \b need \b not \b initialise their value.
template<class T, std::size_t N>
class bounded_vector:
public vector<T, bounded_array<T, N> > {
@@ -853,7 +875,14 @@
};
+ // -----------------
// Zero vector class
+ // -----------------
+
+ /// \brief A zero vector of type \c T and a given \c size
+ /// A zero vector of type \c T and a given \c size. This is a virtual vector in the sense that no memory is allocated
+ /// for storing the zero values: it still acts like any other vector. However assigning values to it will not change the zero
+ /// vector into a normal vector. It must first be assigned to another normal vector by any suitable means. Its memory footprint is constant.
template<class T, class ALLOC>
class zero_vector:
public vector_container<zero_vector<T, ALLOC> > {
@@ -1301,13 +1330,11 @@
template<class T, class ALLOC>
typename unit_vector<T, ALLOC>::const_value_type unit_vector<T, ALLOC>::one_ (1); // ISSUE: need 'one'-traits here
-
- // Scalar vector class
- /// \brief vector having a unique value
- ///
- /// A scalar vector is a vector having a unique value whatever its size. Changing its value means changing all the element at once to the new value.
- /// \tparam T type of the objects stored in the vector: it can be anything even if most of the time, scalar types will be used like \c double or \c int. Complex types can be used, or even classes.
- /// \tparam ALLOC
+ /// \brief A scalar (i.e. unique value) vector of type \c T and a given \c size
+ /// A scalar (i.e. unique value) vector of type \c T and a given \c size. This is a virtual vector in the sense that no memory is allocated
+ /// for storing the unique value more than once: it still acts like any other vector. However assigning a new value will change all the value at once.
+ /// vector into a normal vector. It must first be assigned to another normal vector by any suitable means. Its memory footprint is constant.
+ /// \tparam T type of the objects stored in the vector: it can be anything even if most of the time, scalar types will be used like \c double or \c int. Complex types can be used, or even classes like boost::interval.
template<class T, class ALLOC>
class scalar_vector:
public vector_container<scalar_vector<T, ALLOC> > {
@@ -1543,8 +1570,11 @@
value_type value_;
};
-
+ // ------------------------
// Array based vector class
+ // ------------------------
+
+ /// \brief A dense vector of values of type \c T with the given \c size. The data is stored as an ordinary C++ array \c T \c data_[M]
template<class T, std::size_t N>
class c_vector:
public vector_container<c_vector<T, N> > {
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk