diff options
author | Gael Guennebaud <g.gael@free.fr> | 2017-01-10 22:58:58 +0100 |
---|---|---|
committer | Gael Guennebaud <g.gael@free.fr> | 2017-01-10 22:58:58 +0100 |
commit | 1b5570988bd2d6f783874e2d4fd6b7be45c8ac3c (patch) | |
tree | 6fc5b18af801ea127f8373fdcd64de795bec84f9 | |
parent | 17eac60446650dc31bde7156a4febe504ab347b7 (diff) |
Add doc to seq, seqN, ArithmeticSequence, operator(), etc.
-rw-r--r-- | Eigen/src/Core/ArithmeticSequence.h | 91 | ||||
-rw-r--r-- | Eigen/src/Core/IndexedView.h | 4 | ||||
-rw-r--r-- | Eigen/src/plugins/IndexedViewMethods.h | 88 |
3 files changed, 162 insertions, 21 deletions
diff --git a/Eigen/src/Core/ArithmeticSequence.h b/Eigen/src/Core/ArithmeticSequence.h index bbedd99c2..0fadfb86c 100644 --- a/Eigen/src/Core/ArithmeticSequence.h +++ b/Eigen/src/Core/ArithmeticSequence.h @@ -17,6 +17,8 @@ namespace Eigen { //-------------------------------------------------------------------------------- struct all_t { all_t() {} }; + +/** Can be used as a parameter to DenseBase::operator()(const RowIndices&, const ColIndices&) to index all rows or columns */ static const all_t all; //-------------------------------------------------------------------------------- @@ -24,7 +26,10 @@ static const all_t all; //-------------------------------------------------------------------------------- -/** This namespace defines a set of classes and functions to build and evaluate symbolic expressions of scalar type Index. +/** \namespace Symbolic + * \ingroup Core_Module + * + * This namespace defines a set of classes and functions to build and evaluate symbolic expressions of scalar type Index. * Here is a simple example: * * \code @@ -42,6 +47,7 @@ static const all_t all; * // In c++98/11, only one symbol per expression is supported for now: * auto expr98 = (3-x)/2; * std::cout << expr98.eval(x=6) << "\n"; + * \endcode * * It is currently only used internally to define and minipulate the placeholders::last and placeholders::end symbols in Eigen::seq and Eigen::seqN. * @@ -218,13 +224,39 @@ protected: } // end namespace Symbolic +/** \namespace placeholders + */ namespace placeholders { namespace internal { struct symbolic_last_tag {}; } +/** Can be used as a parameter to seq and seqN functions to symbolically reference the last element/row/columns + * of the underlying vector or matrix once passed to DenseBase::operator()(const RowIndices&, const ColIndices&). + * + * This symbolic placeholder support standard arithmetic operation. + * + * A typical usage example would be: + * \code + * using namespace Eigen; + * using Eigen::placeholders::last; + * VectorXd v(n); + * v(seq(2,last-2)).setOnes(); + * \endcode + * + * \sa end + */ static const Symbolic::SymbolExpr<internal::symbolic_last_tag> last; + +/** Can be used as a parameter to seq and seqN functions to symbolically reference the last+1 element/row/columns + * of the underlying vector or matrix once passed to DenseBase::operator()(const RowIndices&, const ColIndices&). + * + * This symbolic placeholder support standard arithmetic operation. + * It is essentially an alias to last+1 + * + * \sa last + */ static const Symbolic::AddExpr<Symbolic::SymbolExpr<internal::symbolic_last_tag>,Symbolic::ValueExpr> end(last+1); } // end namespace placeholders @@ -265,6 +297,24 @@ inline fix_t<N> fix() { return fix_t<N>(); } // seq(first,last,incr) and seqN(first,size,incr) //-------------------------------------------------------------------------------- +/** \class ArithemeticSequence + * + * This class represents an arithmetic progression \f$ a_0, a_1, a_2, ..., a_{n-1}\f$ defined by + * its \em first value \f$ a_0 \f$, its \em size (aka length) \em n, and the \em increment (aka stride) + * that is equal to \f$ a_{i+1}-a_{i}\f$ for any \em i. + * + * It is internally used as the return type of the seq and seqN functions, and as the input arguments + * of DenseBase::operator()(const RowIndices&, const ColIndices&), and most of the time this is the + * only way it is used. + * + * \tparam FirstType type of the first element, usually an Index, + * but internally it can be a symbolic expression + * \tparam SizeType type representing the size of the sequence, usually an Index + * or a compile time integral constant. Internally, it can also be a symbolic expression + * \tparam IncrType type of the increment, can be a runtime Index, or a compile time integral constant (default is compile-time 1) + * + * \sa seq, seqN, DenseBase::operator()(const RowIndices&, const ColIndices&), class IndexedView + */ template<typename FirstType=Index,typename SizeType=Index,typename IncrType=fix_t<1> > class ArithemeticSequence { @@ -278,8 +328,13 @@ public: IncrAtCompileTime = get_compile_time<IncrType,DynamicIndex>::value }; + /** \returns the size, i.e., number of elements, of the sequence */ Index size() const { return m_size; } + + /** \returns the first element \f$ a_0 \f$ in the sequence */ Index first() const { return m_first; } + + /** \returns the value \f$ a_i \f$ at index \a i in the sequence. */ Index operator[](Index i) const { return m_first + i * m_incr; } const FirstType& firstObject() const { return m_first; } @@ -301,18 +356,50 @@ template<int N> struct cleanup_seq_type<fix_t<N> (*)() > { typedef fix_t<N> type } +/** \returns an ArithemeticSequence starting at \a first, of length \a size, and increment \a incr + * \sa seqN(FirstType,SizeType), seq(FirstType,LastType,IncrType) */ template<typename FirstType,typename SizeType,typename IncrType> ArithemeticSequence<typename internal::cleanup_seq_type<FirstType>::type,typename internal::cleanup_seq_type<SizeType>::type,typename internal::cleanup_seq_type<IncrType>::type > seqN(FirstType first, SizeType size, IncrType incr) { return ArithemeticSequence<typename internal::cleanup_seq_type<FirstType>::type,typename internal::cleanup_seq_type<SizeType>::type,typename internal::cleanup_seq_type<IncrType>::type>(first,size,incr); } +/** \returns an ArithemeticSequence starting at \a first, of length \a size, and unit increment + * \sa seqN(FirstType,SizeType,IncrType), seq(FirstType,LastType) */ template<typename FirstType,typename SizeType> ArithemeticSequence<typename internal::cleanup_seq_type<FirstType>::type,typename internal::cleanup_seq_type<SizeType>::type > seqN(FirstType first, SizeType size) { return ArithemeticSequence<typename internal::cleanup_seq_type<FirstType>::type,typename internal::cleanup_seq_type<SizeType>::type>(first,size); } +#ifdef EIGEN_PARSED_BY_DOXYGEN + +/** \returns an ArithemeticSequence starting at \a f, up (or down) to \a l, and unit increment + * + * It is essentially an alias to: + * \code + * seqN(f,l-f+1); + * \endcode + * + * \sa seqN(FirstType,SizeType), seq(FirstType,LastType,IncrType) + */ +template<typename FirstType,typename LastType> +auto seq(FirstType f, LastType l); + +/** \returns an ArithemeticSequence starting at \a f, up (or down) to \a l, and with positive (or negative) increment \a incr + * + * It is essentially an alias to: + * \code + * seqN(f, (l-f+incr)/incr, incr); + * \endcode + * + * \sa seqN(FirstType,SizeType,IncrType), seq(FirstType,LastType) + */ +template<typename FirstType,typename LastType, typename IncrType> +auto seq(FirstType f, LastType l, IncrType incr); + +#else // EIGEN_PARSED_BY_DOXYGEN + #if EIGEN_HAS_CXX11 template<typename FirstType,typename LastType> auto seq(FirstType f, LastType l) -> decltype(seqN(f,(l-f+fix<1>()))) @@ -414,6 +501,8 @@ seq(const Symbolic::BaseExpr<FirstTypeDerived> &f, const Symbolic::BaseExpr<Last } #endif +#endif // EIGEN_PARSED_BY_DOXYGEN + namespace internal { template<typename T> diff --git a/Eigen/src/Core/IndexedView.h b/Eigen/src/Core/IndexedView.h index 269882e78..781cebd4e 100644 --- a/Eigen/src/Core/IndexedView.h +++ b/Eigen/src/Core/IndexedView.h @@ -85,7 +85,7 @@ class IndexedViewImpl; * - std::vector<int> * - std::valarray<int> * - std::array<int> - * - c++ arrays: int[N] + * - Plain C arrays: int[N] * - Eigen::ArrayXi * - decltype(ArrayXi::LinSpaced(...)) * - Any view/expressions of the previous types @@ -94,7 +94,7 @@ class IndexedViewImpl; * - Eigen::IntAsArray (helper for single index) * - etc. * - * In typical usages of %Eigen, this class should never be used directly. It is the return type of DenseBase::operator(). + * In typical usages of %Eigen, this class should never be used directly. It is the return type of DenseBase::operator()(const RowIndices&, const ColIndices&). * * \sa class Block */ diff --git a/Eigen/src/plugins/IndexedViewMethods.h b/Eigen/src/plugins/IndexedViewMethods.h index 53eff093c..ea1aa6e2e 100644 --- a/Eigen/src/plugins/IndexedViewMethods.h +++ b/Eigen/src/plugins/IndexedViewMethods.h @@ -7,6 +7,7 @@ // Public License v. 2.0. If a copy of the MPL was not distributed // with this file, You can obtain one at http://mozilla.org/MPL/2.0/. +#ifndef EIGEN_PARSED_BY_DOXYGEN // This file is automatically included twice to generate const and non-const versions @@ -20,54 +21,67 @@ template<typename RowIndices, typename ColIndices> struct EIGEN_INDEXED_VIEW_METHOD_TYPE { - typedef IndexedView<EIGEN_INDEXED_VIEW_METHOD_CONST Derived,typename internal::MakeIndexing<RowIndices>::type,typename internal::MakeIndexing<ColIndices>::type> type; + typedef IndexedView<EIGEN_INDEXED_VIEW_METHOD_CONST Derived, + typename internal::MakeIndexing<RowIndices>::type, + typename internal::MakeIndexing<ColIndices>::type> type; }; +// This is the generic version + template<typename RowIndices, typename ColIndices> typename internal::enable_if< ! (internal::traits<typename EIGEN_INDEXED_VIEW_METHOD_TYPE<RowIndices,ColIndices>::type>::IsBlockAlike || (internal::is_integral<RowIndices>::value && internal::is_integral<ColIndices>::value)), typename EIGEN_INDEXED_VIEW_METHOD_TYPE<RowIndices,ColIndices>::type >::type -operator()(const RowIndices& rowIndices, const ColIndices& colIndices) EIGEN_INDEXED_VIEW_METHOD_CONST { - return typename EIGEN_INDEXED_VIEW_METHOD_TYPE<RowIndices,ColIndices>::type( - derived(), internal::make_indexing(rowIndices,derived().rows()), internal::make_indexing(colIndices,derived().cols())); +operator()(const RowIndices& rowIndices, const ColIndices& colIndices) EIGEN_INDEXED_VIEW_METHOD_CONST +{ + return typename EIGEN_INDEXED_VIEW_METHOD_TYPE<RowIndices,ColIndices>::type + (derived(), internal::make_indexing(rowIndices,derived().rows()), internal::make_indexing(colIndices,derived().cols())); } +// The folowing overload returns a Block<> object + template<typename RowIndices, typename ColIndices> typename internal::enable_if< internal::traits<typename EIGEN_INDEXED_VIEW_METHOD_TYPE<RowIndices,ColIndices>::type>::IsBlockAlike && !(internal::is_integral<RowIndices>::value && internal::is_integral<ColIndices>::value), typename internal::traits<typename EIGEN_INDEXED_VIEW_METHOD_TYPE<RowIndices,ColIndices>::type>::BlockType>::type -operator()(const RowIndices& rowIndices, const ColIndices& colIndices) EIGEN_INDEXED_VIEW_METHOD_CONST { +operator()(const RowIndices& rowIndices, const ColIndices& colIndices) EIGEN_INDEXED_VIEW_METHOD_CONST +{ typedef typename internal::traits<typename EIGEN_INDEXED_VIEW_METHOD_TYPE<RowIndices,ColIndices>::type>::BlockType BlockType; typename internal::MakeIndexing<RowIndices>::type actualRowIndices = internal::make_indexing(rowIndices,derived().rows()); typename internal::MakeIndexing<ColIndices>::type actualColIndices = internal::make_indexing(colIndices,derived().cols()); return BlockType(derived(), - internal::first(actualRowIndices), - internal::first(actualColIndices), - internal::size(actualRowIndices), - internal::size(actualColIndices)); + internal::first(actualRowIndices), + internal::first(actualColIndices), + internal::size(actualRowIndices), + internal::size(actualColIndices)); } +// The folowing three overloads are needed to handle raw Index[N] arrays. + template<typename RowIndicesT, std::size_t RowIndicesN, typename ColIndices> IndexedView<EIGEN_INDEXED_VIEW_METHOD_CONST Derived,const RowIndicesT (&)[RowIndicesN],typename internal::MakeIndexing<ColIndices>::type> -operator()(const RowIndicesT (&rowIndices)[RowIndicesN], const ColIndices& colIndices) EIGEN_INDEXED_VIEW_METHOD_CONST { - return IndexedView<EIGEN_INDEXED_VIEW_METHOD_CONST Derived,const RowIndicesT (&)[RowIndicesN],typename internal::MakeIndexing<ColIndices>::type>( - derived(), rowIndices, internal::make_indexing(colIndices,derived().cols())); +operator()(const RowIndicesT (&rowIndices)[RowIndicesN], const ColIndices& colIndices) EIGEN_INDEXED_VIEW_METHOD_CONST +{ + return IndexedView<EIGEN_INDEXED_VIEW_METHOD_CONST Derived,const RowIndicesT (&)[RowIndicesN],typename internal::MakeIndexing<ColIndices>::type> + (derived(), rowIndices, internal::make_indexing(colIndices,derived().cols())); } template<typename RowIndices, typename ColIndicesT, std::size_t ColIndicesN> IndexedView<EIGEN_INDEXED_VIEW_METHOD_CONST Derived,typename internal::MakeIndexing<RowIndices>::type, const ColIndicesT (&)[ColIndicesN]> -operator()(const RowIndices& rowIndices, const ColIndicesT (&colIndices)[ColIndicesN]) EIGEN_INDEXED_VIEW_METHOD_CONST { - return IndexedView<EIGEN_INDEXED_VIEW_METHOD_CONST Derived,typename internal::MakeIndexing<RowIndices>::type,const ColIndicesT (&)[ColIndicesN]>( - derived(), internal::make_indexing(rowIndices,derived().rows()), colIndices); +operator()(const RowIndices& rowIndices, const ColIndicesT (&colIndices)[ColIndicesN]) EIGEN_INDEXED_VIEW_METHOD_CONST +{ + return IndexedView<EIGEN_INDEXED_VIEW_METHOD_CONST Derived,typename internal::MakeIndexing<RowIndices>::type,const ColIndicesT (&)[ColIndicesN]> + (derived(), internal::make_indexing(rowIndices,derived().rows()), colIndices); } template<typename RowIndicesT, std::size_t RowIndicesN, typename ColIndicesT, std::size_t ColIndicesN> IndexedView<EIGEN_INDEXED_VIEW_METHOD_CONST Derived,const RowIndicesT (&)[RowIndicesN], const ColIndicesT (&)[ColIndicesN]> -operator()(const RowIndicesT (&rowIndices)[RowIndicesN], const ColIndicesT (&colIndices)[ColIndicesN]) EIGEN_INDEXED_VIEW_METHOD_CONST { - return IndexedView<EIGEN_INDEXED_VIEW_METHOD_CONST Derived,const RowIndicesT (&)[RowIndicesN],const ColIndicesT (&)[ColIndicesN]>( - derived(), rowIndices, colIndices); +operator()(const RowIndicesT (&rowIndices)[RowIndicesN], const ColIndicesT (&colIndices)[ColIndicesN]) EIGEN_INDEXED_VIEW_METHOD_CONST +{ + return IndexedView<EIGEN_INDEXED_VIEW_METHOD_CONST Derived,const RowIndicesT (&)[RowIndicesN],const ColIndicesT (&)[ColIndicesN]> + (derived(), rowIndices, colIndices); } #undef EIGEN_INDEXED_VIEW_METHOD_CONST @@ -79,3 +93,41 @@ operator()(const RowIndicesT (&rowIndices)[RowIndicesN], const ColIndicesT (&col #undef EIGEN_INDEXED_VIEW_METHOD_2ND_PASS #endif +#else // EIGEN_PARSED_BY_DOXYGEN + +/** + * \returns a generic submatrix view defined by the rows and columns indexed \a rowIndices and \a colIndices respectively. + * + * Each parameter must either be: + * - An integer indexing a single row or column + * - Eigen::all indexing the full set of respective rows or columns in increasing order + * - An ArithemeticSequence as returned by the seq and seqN functions + * - Any %Eigen's vector/array of integers or expressions + * - Plain C arrays: \c int[N] + * - And more generally any type exposing the following two member functions: + * \code + * <integral type> operator[](<integral type>) const; + * <integral type> size() const; + * \endcode + * where \c <integral \c type> stands for any integer type compatible with Eigen::Index (i.e. \c std::ptrdiff_t). + * + * The last statement implies compatibility with \c std::vector, \c std::valarray, \c std::array, many of the Range-v3's ranges, etc. + * + * If the submatrix can be represented using a starting position \c (i,j) and positive sizes \c (rows,columns), then this + * method will returns a Block object after extraction of the relevant information from the passed arguments. This is the case + * when all arguments are either: + * - An integer + * - Eigen::all + * - An ArithemeticSequence with compile-time increment strictly equal to 1, as returned by seq(a,b), and seqN(a,N). + * + * Otherwise a more general IndexedView<Derived,RowIndices',ColIndices'> object will be returned, after conversion of the inputs + * to more suitable types \c RowIndices' and \c ColIndices'. + * + * \sa class Block, class IndexedView, DenseBase::block(Index,Index,Index,Index) + */ +template<typename RowIndices, typename ColIndices> +IndexedView_or_Block +operator()(const RowIndices& rowIndices, const ColIndices& colIndices); + +#endif // EIGEN_PARSED_BY_DOXYGEN + |