src/Core/Stride.h

0001 // This file is part of Eigen, a lightweight C++ template library
0002 // for linear algebra.
0003 //
0004 // Copyright (C) 2010 Benoit Jacob <jacob.benoit.1@gmail.com>
0005 //
0006 // This Source Code Form is subject to the terms of the Mozilla
0007 // Public License v. 2.0. If a copy of the MPL was not distributed
0008 // with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
0009
0010 #ifndef EIGEN_STRIDE_H
0011 #define EIGEN_STRIDE_H
0012
0013 namespace Eigen {
0014
0015 /** \class Stride
0016   * \ingroup Core_Module
0017   *
0018   * \brief Holds strides information for Map
0019   *
0020   * This class holds the strides information for mapping arrays with strides with class Map.
0021   *
0022   * It holds two values: the inner stride and the outer stride.
0023   *
0024   * The inner stride is the pointer increment between two consecutive entries within a given row of a
0025   * row-major matrix or within a given column of a column-major matrix.
0026   *
0027   * The outer stride is the pointer increment between two consecutive rows of a row-major matrix or
0028   * between two consecutive columns of a column-major matrix.
0029   *
0030   * These two values can be passed either at compile-time as template parameters, or at runtime as
0031   * arguments to the constructor.
0032   *
0033   * Indeed, this class takes two template parameters:
0034   *  \tparam _OuterStrideAtCompileTime the outer stride, or Dynamic if you want to specify it at runtime.
0035   *  \tparam _InnerStrideAtCompileTime the inner stride, or Dynamic if you want to specify it at runtime.
0036   *
0037   * Here is an example:
0038   * \include Map_general_stride.cpp
0039   * Output: \verbinclude Map_general_stride.out
0040   *
0041   * Both strides can be negative, however, a negative stride of -1 cannot be specified at compiletime
0042   * because of the ambiguity with Dynamic which is defined to -1 (historically, negative strides were
0043   * not allowed).
0044   *
0045   * \sa class InnerStride, class OuterStride, \ref TopicStorageOrders
0046   */
0047 template<int _OuterStrideAtCompileTime, int _InnerStrideAtCompileTime>
0048 class Stride
0049 {
0050   public:
0051     typedef Eigen::Index Index; ///< \deprecated since Eigen 3.3
0052     enum {
0053       InnerStrideAtCompileTime = _InnerStrideAtCompileTime,
0054       OuterStrideAtCompileTime = _OuterStrideAtCompileTime
0055     };
0056
0057     /** Default constructor, for use when strides are fixed at compile time */
0058     EIGEN_DEVICE_FUNC
0059     Stride()
0060       : m_outer(OuterStrideAtCompileTime), m_inner(InnerStrideAtCompileTime)
0061     {
0062       // FIXME: for Eigen 4 we should use DynamicIndex instead of Dynamic.
0063       // FIXME: for Eigen 4 we should also unify this API with fix<>
0064       eigen_assert(InnerStrideAtCompileTime != Dynamic && OuterStrideAtCompileTime != Dynamic);
0065     }
0066
0067     /** Constructor allowing to pass the strides at runtime */
0068     EIGEN_DEVICE_FUNC
0069     Stride(Index outerStride, Index innerStride)
0070       : m_outer(outerStride), m_inner(innerStride)
0071     {
0072     }
0073
0074     /** Copy constructor */
0075     EIGEN_DEVICE_FUNC
0076     Stride(const Stride& other)
0077       : m_outer(other.outer()), m_inner(other.inner())
0078     {}
0079
0080     /** \returns the outer stride */
0081     EIGEN_DEVICE_FUNC EIGEN_CONSTEXPR
0082     inline Index outer() const { return m_outer.value(); }
0083     /** \returns the inner stride */
0084     EIGEN_DEVICE_FUNC EIGEN_CONSTEXPR
0085     inline Index inner() const { return m_inner.value(); }
0086
0087   protected:
0088     internal::variable_if_dynamic<Index, OuterStrideAtCompileTime> m_outer;
0089     internal::variable_if_dynamic<Index, InnerStrideAtCompileTime> m_inner;
0090 };
0091
0092 /** \brief Convenience specialization of Stride to specify only an inner stride
0093   * See class Map for some examples */
0094 template<int Value>
0095 class InnerStride : public Stride<0, Value>
0096 {
0097     typedef Stride<0, Value> Base;
0098   public:
0099     EIGEN_DEVICE_FUNC InnerStride() : Base() {}
0100     EIGEN_DEVICE_FUNC InnerStride(Index v) : Base(0, v) {} // FIXME making this explicit could break valid code
0101 };
0102
0103 /** \brief Convenience specialization of Stride to specify only an outer stride
0104   * See class Map for some examples */
0105 template<int Value>
0106 class OuterStride : public Stride<Value, 0>
0107 {
0108     typedef Stride<Value, 0> Base;
0109   public:
0110     EIGEN_DEVICE_FUNC OuterStride() : Base() {}
0111     EIGEN_DEVICE_FUNC OuterStride(Index v) : Base(v,0) {} // FIXME making this explicit could break valid code
0112 };
0113
0114 } // end namespace Eigen
0115
0116 #endif // EIGEN_STRIDE_H