src/Core/Array.h

0001 // This file is part of Eigen, a lightweight C++ template library
0002 // for linear algebra.
0003 //
0004 // Copyright (C) 2009 Gael Guennebaud <gael.guennebaud@inria.fr>
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_ARRAY_H
0011 #define EIGEN_ARRAY_H
0012
0013 namespace RivetEigen {
0014
0015 namespace internal {
0016 template<typename _Scalar, int _Rows, int _Cols, int _Options, int _MaxRows, int _MaxCols>
0017 struct traits<Array<_Scalar, _Rows, _Cols, _Options, _MaxRows, _MaxCols> > : traits<Matrix<_Scalar, _Rows, _Cols, _Options, _MaxRows, _MaxCols> >
0018 {
0019   typedef ArrayXpr XprKind;
0020   typedef ArrayBase<Array<_Scalar, _Rows, _Cols, _Options, _MaxRows, _MaxCols> > XprBase;
0021 };
0022 }
0023
0024 /** \class Array
0025   * \ingroup Core_Module
0026   *
0027   * \brief General-purpose arrays with easy API for coefficient-wise operations
0028   *
0029   * The %Array class is very similar to the Matrix class. It provides
0030   * general-purpose one- and two-dimensional arrays. The difference between the
0031   * %Array and the %Matrix class is primarily in the API: the API for the
0032   * %Array class provides easy access to coefficient-wise operations, while the
0033   * API for the %Matrix class provides easy access to linear-algebra
0034   * operations.
0035   *
0036   * See documentation of class Matrix for detailed information on the template parameters
0037   * storage layout.
0038   *
0039   * This class can be extended with the help of the plugin mechanism described on the page
0040   * \ref TopicCustomizing_Plugins by defining the preprocessor symbol \c EIGEN_ARRAY_PLUGIN.
0041   *
0042   * \sa \blank \ref TutorialArrayClass, \ref TopicClassHierarchy
0043   */
0044 template<typename _Scalar, int _Rows, int _Cols, int _Options, int _MaxRows, int _MaxCols>
0045 class Array
0046   : public PlainObjectBase<Array<_Scalar, _Rows, _Cols, _Options, _MaxRows, _MaxCols> >
0047 {
0048   public:
0049
0050     typedef PlainObjectBase<Array> Base;
0051     EIGEN_DENSE_PUBLIC_INTERFACE(Array)
0052
0053     enum { Options = _Options };
0054     typedef typename Base::PlainObject PlainObject;
0055
0056   protected:
0057     template <typename Derived, typename OtherDerived, bool IsVector>
0058     friend struct internal::conservative_resize_like_impl;
0059
0060     using Base::m_storage;
0061
0062   public:
0063
0064     using Base::base;
0065     using Base::coeff;
0066     using Base::coeffRef;
0067
0068     /**
0069       * The usage of
0070       *   using Base::operator=;
0071       * fails on MSVC. Since the code below is working with GCC and MSVC, we skipped
0072       * the usage of 'using'. This should be done only for operator=.
0073       */
0074     template<typename OtherDerived>
0075     EIGEN_DEVICE_FUNC
0076     EIGEN_STRONG_INLINE Array& operator=(const EigenBase<OtherDerived> &other)
0077     {
0078       return Base::operator=(other);
0079     }
0080
0081     /** Set all the entries to \a value.
0082       * \sa DenseBase::setConstant(), DenseBase::fill()
0083       */
0084     /* This overload is needed because the usage of
0085       *   using Base::operator=;
0086       * fails on MSVC. Since the code below is working with GCC and MSVC, we skipped
0087       * the usage of 'using'. This should be done only for operator=.
0088       */
0089     EIGEN_DEVICE_FUNC
0090     EIGEN_STRONG_INLINE Array& operator=(const Scalar &value)
0091     {
0092       Base::setConstant(value);
0093       return *this;
0094     }
0095
0096     /** Copies the value of the expression \a other into \c *this with automatic resizing.
0097       *
0098       * *this might be resized to match the dimensions of \a other. If *this was a null matrix (not already initialized),
0099       * it will be initialized.
0100       *
0101       * Note that copying a row-vector into a vector (and conversely) is allowed.
0102       * The resizing, if any, is then done in the appropriate way so that row-vectors
0103       * remain row-vectors and vectors remain vectors.
0104       */
0105     template<typename OtherDerived>
0106     EIGEN_DEVICE_FUNC
0107     EIGEN_STRONG_INLINE Array& operator=(const DenseBase<OtherDerived>& other)
0108     {
0109       return Base::_set(other);
0110     }
0111
0112     /** This is a special case of the templated operator=. Its purpose is to
0113       * prevent a default operator= from hiding the templated operator=.
0114       */
0115     EIGEN_DEVICE_FUNC
0116     EIGEN_STRONG_INLINE Array& operator=(const Array& other)
0117     {
0118       return Base::_set(other);
0119     }
0120
0121     /** Default constructor.
0122       *
0123       * For fixed-size matrices, does nothing.
0124       *
0125       * For dynamic-size matrices, creates an empty matrix of size 0. Does not allocate any array. Such a matrix
0126       * is called a null matrix. This constructor is the unique way to create null matrices: resizing
0127       * a matrix to 0 is not supported.
0128       *
0129       * \sa resize(Index,Index)
0130       */
0131     EIGEN_DEVICE_FUNC
0132     EIGEN_STRONG_INLINE Array() : Base()
0133     {
0134       Base::_check_template_params();
0135       EIGEN_INITIALIZE_COEFFS_IF_THAT_OPTION_IS_ENABLED
0136     }
0137
0138 #ifndef EIGEN_PARSED_BY_DOXYGEN
0139     // FIXME is it still needed ??
0140     /** \internal */
0141     EIGEN_DEVICE_FUNC
0142     Array(internal::constructor_without_unaligned_array_assert)
0143       : Base(internal::constructor_without_unaligned_array_assert())
0144     {
0145       Base::_check_template_params();
0146       EIGEN_INITIALIZE_COEFFS_IF_THAT_OPTION_IS_ENABLED
0147     }
0148 #endif
0149
0150 #if EIGEN_HAS_RVALUE_REFERENCES
0151     EIGEN_DEVICE_FUNC
0152     Array(Array&& other) EIGEN_NOEXCEPT_IF(std::is_nothrow_move_constructible<Scalar>::value)
0153       : Base(std::move(other))
0154     {
0155       Base::_check_template_params();
0156     }
0157     EIGEN_DEVICE_FUNC
0158     Array& operator=(Array&& other) EIGEN_NOEXCEPT_IF(std::is_nothrow_move_assignable<Scalar>::value)
0159     {
0160       Base::operator=(std::move(other));
0161       return *this;
0162     }
0163 #endif
0164
0165     #if EIGEN_HAS_CXX11
0166     /** \copydoc PlainObjectBase(const Scalar& a0, const Scalar& a1, const Scalar& a2, const Scalar& a3, const ArgTypes&... args)
0167      *
0168      * Example: \include Array_variadic_ctor_cxx11.cpp
0169      * Output: \verbinclude Array_variadic_ctor_cxx11.out
0170      *
0171      * \sa Array(const std::initializer_list<std::initializer_list<Scalar>>&)
0172      * \sa Array(const Scalar&), Array(const Scalar&,const Scalar&)
0173      */
0174     template <typename... ArgTypes>
0175     EIGEN_DEVICE_FUNC EIGEN_STRONG_INLINE
0176     Array(const Scalar& a0, const Scalar& a1, const Scalar& a2, const Scalar& a3, const ArgTypes&... args)
0177       : Base(a0, a1, a2, a3, args...) {}
0178
0179     /** \brief Constructs an array and initializes it from the coefficients given as initializer-lists grouped by row. \cpp11
0180       *
0181       * In the general case, the constructor takes a list of rows, each row being represented as a list of coefficients:
0182       *
0183       * Example: \include Array_initializer_list_23_cxx11.cpp
0184       * Output: \verbinclude Array_initializer_list_23_cxx11.out
0185       *
0186       * Each of the inner initializer lists must contain the exact same number of elements, otherwise an assertion is triggered.
0187       *
0188       * In the case of a compile-time column 1D array, implicit transposition from a single row is allowed.
0189       * Therefore <code> Array<int,Dynamic,1>{{1,2,3,4,5}}</code> is legal and the more verbose syntax
0190       * <code>Array<int,Dynamic,1>{{1},{2},{3},{4},{5}}</code> can be avoided:
0191       *
0192       * Example: \include Array_initializer_list_vector_cxx11.cpp
0193       * Output: \verbinclude Array_initializer_list_vector_cxx11.out
0194       *
0195       * In the case of fixed-sized arrays, the initializer list sizes must exactly match the array sizes,
0196       * and implicit transposition is allowed for compile-time 1D arrays only.
0197       *
0198       * \sa  Array(const Scalar& a0, const Scalar& a1, const Scalar& a2, const Scalar& a3, const ArgTypes&... args)
0199       */
0200     EIGEN_DEVICE_FUNC
0201     EIGEN_STRONG_INLINE Array(const std::initializer_list<std::initializer_list<Scalar>>& list) : Base(list) {}
0202     #endif // end EIGEN_HAS_CXX11
0203
0204     #ifndef EIGEN_PARSED_BY_DOXYGEN
0205     template<typename T>
0206     EIGEN_DEVICE_FUNC
0207     EIGEN_STRONG_INLINE explicit Array(const T& x)
0208     {
0209       Base::_check_template_params();
0210       Base::template _init1<T>(x);
0211     }
0212
0213     template<typename T0, typename T1>
0214     EIGEN_DEVICE_FUNC
0215     EIGEN_STRONG_INLINE Array(const T0& val0, const T1& val1)
0216     {
0217       Base::_check_template_params();
0218       this->template _init2<T0,T1>(val0, val1);
0219     }
0220
0221     #else
0222     /** \brief Constructs a fixed-sized array initialized with coefficients starting at \a data */
0223     EIGEN_DEVICE_FUNC explicit Array(const Scalar *data);
0224     /** Constructs a vector or row-vector with given dimension. \only_for_vectors
0225       *
0226       * Note that this is only useful for dynamic-size vectors. For fixed-size vectors,
0227       * it is redundant to pass the dimension here, so it makes more sense to use the default
0228       * constructor Array() instead.
0229       */
0230     EIGEN_DEVICE_FUNC
0231     EIGEN_STRONG_INLINE explicit Array(Index dim);
0232     /** constructs an initialized 1x1 Array with the given coefficient
0233       * \sa const Scalar& a0, const Scalar& a1, const Scalar& a2, const Scalar& a3, const ArgTypes&... args */
0234     Array(const Scalar& value);
0235     /** constructs an uninitialized array with \a rows rows and \a cols columns.
0236       *
0237       * This is useful for dynamic-size arrays. For fixed-size arrays,
0238       * it is redundant to pass these parameters, so one should use the default constructor
0239       * Array() instead. */
0240     Array(Index rows, Index cols);
0241     /** constructs an initialized 2D vector with given coefficients
0242       * \sa Array(const Scalar& a0, const Scalar& a1, const Scalar& a2, const Scalar& a3, const ArgTypes&... args) */
0243     Array(const Scalar& val0, const Scalar& val1);
0244     #endif  // end EIGEN_PARSED_BY_DOXYGEN
0245
0246     /** constructs an initialized 3D vector with given coefficients
0247       * \sa Array(const Scalar& a0, const Scalar& a1, const Scalar& a2, const Scalar& a3, const ArgTypes&... args)
0248       */
0249     EIGEN_DEVICE_FUNC
0250     EIGEN_STRONG_INLINE Array(const Scalar& val0, const Scalar& val1, const Scalar& val2)
0251     {
0252       Base::_check_template_params();
0253       EIGEN_STATIC_ASSERT_VECTOR_SPECIFIC_SIZE(Array, 3)
0254       m_storage.data()[0] = val0;
0255       m_storage.data()[1] = val1;
0256       m_storage.data()[2] = val2;
0257     }
0258     /** constructs an initialized 4D vector with given coefficients
0259       * \sa Array(const Scalar& a0, const Scalar& a1, const Scalar& a2, const Scalar& a3, const ArgTypes&... args)
0260       */
0261     EIGEN_DEVICE_FUNC
0262     EIGEN_STRONG_INLINE Array(const Scalar& val0, const Scalar& val1, const Scalar& val2, const Scalar& val3)
0263     {
0264       Base::_check_template_params();
0265       EIGEN_STATIC_ASSERT_VECTOR_SPECIFIC_SIZE(Array, 4)
0266       m_storage.data()[0] = val0;
0267       m_storage.data()[1] = val1;
0268       m_storage.data()[2] = val2;
0269       m_storage.data()[3] = val3;
0270     }
0271
0272     /** Copy constructor */
0273     EIGEN_DEVICE_FUNC
0274     EIGEN_STRONG_INLINE Array(const Array& other)
0275             : Base(other)
0276     { }
0277
0278   private:
0279     struct PrivateType {};
0280   public:
0281
0282     /** \sa MatrixBase::operator=(const EigenBase<OtherDerived>&) */
0283     template<typename OtherDerived>
0284     EIGEN_DEVICE_FUNC
0285     EIGEN_STRONG_INLINE Array(const EigenBase<OtherDerived> &other,
0286                               typename internal::enable_if<internal::is_convertible<typename OtherDerived::Scalar,Scalar>::value,
0287                                                            PrivateType>::type = PrivateType())
0288       : Base(other.derived())
0289     { }
0290
0291     EIGEN_DEVICE_FUNC EIGEN_CONSTEXPR
0292     inline Index innerStride() const EIGEN_NOEXCEPT{ return 1; }
0293     EIGEN_DEVICE_FUNC EIGEN_CONSTEXPR
0294     inline Index outerStride() const EIGEN_NOEXCEPT { return this->innerSize(); }
0295
0296     #ifdef EIGEN_ARRAY_PLUGIN
0297     #include EIGEN_ARRAY_PLUGIN
0298     #endif
0299
0300   private:
0301
0302     template<typename MatrixType, typename OtherDerived, bool SwapPointers>
0303     friend struct internal::matrix_swap_impl;
0304 };
0305
0306 /** \defgroup arraytypedefs Global array typedefs
0307   * \ingroup Core_Module
0308   *
0309   * %Eigen defines several typedef shortcuts for most common 1D and 2D array types.
0310   *
0311   * The general patterns are the following:
0312   *
0313   * \c ArrayRowsColsType where \c Rows and \c Cols can be \c 2,\c 3,\c 4 for fixed size square matrices or \c X for dynamic size,
0314   * and where \c Type can be \c i for integer, \c f for float, \c d for double, \c cf for complex float, \c cd
0315   * for complex double.
0316   *
0317   * For example, \c Array33d is a fixed-size 3x3 array type of doubles, and \c ArrayXXf is a dynamic-size matrix of floats.
0318   *
0319   * There are also \c ArraySizeType which are self-explanatory. For example, \c Array4cf is
0320   * a fixed-size 1D array of 4 complex floats.
0321   *
0322   * With \cpp11, template alias are also defined for common sizes.
0323   * They follow the same pattern as above except that the scalar type suffix is replaced by a
0324   * template parameter, i.e.:
0325   *   - `ArrayRowsCols<Type>` where `Rows` and `Cols` can be \c 2,\c 3,\c 4, or \c X for fixed or dynamic size.
0326   *   - `ArraySize<Type>` where `Size` can be \c 2,\c 3,\c 4 or \c X for fixed or dynamic size 1D arrays.
0327   *
0328   * \sa class Array
0329   */
0330
0331 #define EIGEN_MAKE_ARRAY_TYPEDEFS(Type, TypeSuffix, Size, SizeSuffix)   \
0332 /** \ingroup arraytypedefs */                                    \
0333 typedef Array<Type, Size, Size> Array##SizeSuffix##SizeSuffix##TypeSuffix;  \
0334 /** \ingroup arraytypedefs */                                    \
0335 typedef Array<Type, Size, 1>    Array##SizeSuffix##TypeSuffix;
0336
0337 #define EIGEN_MAKE_ARRAY_FIXED_TYPEDEFS(Type, TypeSuffix, Size)         \
0338 /** \ingroup arraytypedefs */                                    \
0339 typedef Array<Type, Size, Dynamic> Array##Size##X##TypeSuffix;  \
0340 /** \ingroup arraytypedefs */                                    \
0341 typedef Array<Type, Dynamic, Size> Array##X##Size##TypeSuffix;
0342
0343 #define EIGEN_MAKE_ARRAY_TYPEDEFS_ALL_SIZES(Type, TypeSuffix) \
0344 EIGEN_MAKE_ARRAY_TYPEDEFS(Type, TypeSuffix, 2, 2) \
0345 EIGEN_MAKE_ARRAY_TYPEDEFS(Type, TypeSuffix, 3, 3) \
0346 EIGEN_MAKE_ARRAY_TYPEDEFS(Type, TypeSuffix, 4, 4) \
0347 EIGEN_MAKE_ARRAY_TYPEDEFS(Type, TypeSuffix, Dynamic, X) \
0348 EIGEN_MAKE_ARRAY_FIXED_TYPEDEFS(Type, TypeSuffix, 2) \
0349 EIGEN_MAKE_ARRAY_FIXED_TYPEDEFS(Type, TypeSuffix, 3) \
0350 EIGEN_MAKE_ARRAY_FIXED_TYPEDEFS(Type, TypeSuffix, 4)
0351
0352 EIGEN_MAKE_ARRAY_TYPEDEFS_ALL_SIZES(int,                  i)
0353 EIGEN_MAKE_ARRAY_TYPEDEFS_ALL_SIZES(float,                f)
0354 EIGEN_MAKE_ARRAY_TYPEDEFS_ALL_SIZES(double,               d)
0355 EIGEN_MAKE_ARRAY_TYPEDEFS_ALL_SIZES(std::complex<float>,  cf)
0356 EIGEN_MAKE_ARRAY_TYPEDEFS_ALL_SIZES(std::complex<double>, cd)
0357
0358 #undef EIGEN_MAKE_ARRAY_TYPEDEFS_ALL_SIZES
0359 #undef EIGEN_MAKE_ARRAY_TYPEDEFS
0360 #undef EIGEN_MAKE_ARRAY_FIXED_TYPEDEFS
0361
0362 #if EIGEN_HAS_CXX11
0363
0364 #define EIGEN_MAKE_ARRAY_TYPEDEFS(Size, SizeSuffix)               \
0365 /** \ingroup arraytypedefs */                                     \
0366 /** \brief \cpp11 */                                              \
0367 template <typename Type>                                          \
0368 using Array##SizeSuffix##SizeSuffix = Array<Type, Size, Size>;    \
0369 /** \ingroup arraytypedefs */                                     \
0370 /** \brief \cpp11 */                                              \
0371 template <typename Type>                                          \
0372 using Array##SizeSuffix = Array<Type, Size, 1>;
0373
0374 #define EIGEN_MAKE_ARRAY_FIXED_TYPEDEFS(Size)                     \
0375 /** \ingroup arraytypedefs */                                     \
0376 /** \brief \cpp11 */                                              \
0377 template <typename Type>                                          \
0378 using Array##Size##X = Array<Type, Size, Dynamic>;                \
0379 /** \ingroup arraytypedefs */                                     \
0380 /** \brief \cpp11 */                                              \
0381 template <typename Type>                                          \
0382 using Array##X##Size = Array<Type, Dynamic, Size>;
0383
0384 EIGEN_MAKE_ARRAY_TYPEDEFS(2, 2)
0385 EIGEN_MAKE_ARRAY_TYPEDEFS(3, 3)
0386 EIGEN_MAKE_ARRAY_TYPEDEFS(4, 4)
0387 EIGEN_MAKE_ARRAY_TYPEDEFS(Dynamic, X)
0388 EIGEN_MAKE_ARRAY_FIXED_TYPEDEFS(2)
0389 EIGEN_MAKE_ARRAY_FIXED_TYPEDEFS(3)
0390 EIGEN_MAKE_ARRAY_FIXED_TYPEDEFS(4)
0391
0392 #undef EIGEN_MAKE_ARRAY_TYPEDEFS
0393 #undef EIGEN_MAKE_ARRAY_FIXED_TYPEDEFS
0394
0395 #endif // EIGEN_HAS_CXX11
0396
0397 #define EIGEN_USING_ARRAY_TYPEDEFS_FOR_TYPE_AND_SIZE(TypeSuffix, SizeSuffix) \
0398 using RivetEigen::Matrix##SizeSuffix##TypeSuffix; \
0399 using RivetEigen::Vector##SizeSuffix##TypeSuffix; \
0400 using RivetEigen::RowVector##SizeSuffix##TypeSuffix;
0401
0402 #define EIGEN_USING_ARRAY_TYPEDEFS_FOR_TYPE(TypeSuffix) \
0403 EIGEN_USING_ARRAY_TYPEDEFS_FOR_TYPE_AND_SIZE(TypeSuffix, 2) \
0404 EIGEN_USING_ARRAY_TYPEDEFS_FOR_TYPE_AND_SIZE(TypeSuffix, 3) \
0405 EIGEN_USING_ARRAY_TYPEDEFS_FOR_TYPE_AND_SIZE(TypeSuffix, 4) \
0406 EIGEN_USING_ARRAY_TYPEDEFS_FOR_TYPE_AND_SIZE(TypeSuffix, X) \
0407
0408 #define EIGEN_USING_ARRAY_TYPEDEFS \
0409 EIGEN_USING_ARRAY_TYPEDEFS_FOR_TYPE(i) \
0410 EIGEN_USING_ARRAY_TYPEDEFS_FOR_TYPE(f) \
0411 EIGEN_USING_ARRAY_TYPEDEFS_FOR_TYPE(d) \
0412 EIGEN_USING_ARRAY_TYPEDEFS_FOR_TYPE(cf) \
0413 EIGEN_USING_ARRAY_TYPEDEFS_FOR_TYPE(cd)
0414
0415 } // end namespace RivetEigen
0416
0417 #endif // EIGEN_ARRAY_H