Array.h

00001 // This file is part of Eigen, a lightweight C++ template library
00002 // for linear algebra.
00003 //
00004 // Copyright (C) 2009 Gael Guennebaud <gael.guennebaud@inria.fr>
00005 //
00006 // This Source Code Form is subject to the terms of the Mozilla
00007 // Public License v. 2.0. If a copy of the MPL was not distributed
00008 // with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
00009 
00010 #ifndef EIGEN_ARRAY_H
00011 #define EIGEN_ARRAY_H
00012 
00013 namespace Eigen {
00014 
00015 /** \class Array 
00016   * \ingroup Core_Module
00017   *
00018   * \brief General-purpose arrays with easy API for coefficient-wise operations
00019   *
00020   * The %Array class is very similar to the Matrix class. It provides
00021   * general-purpose one- and two-dimensional arrays. The difference between the
00022   * %Array and the %Matrix class is primarily in the API: the API for the
00023   * %Array class provides easy access to coefficient-wise operations, while the
00024   * API for the %Matrix class provides easy access to linear-algebra
00025   * operations.
00026   *
00027   * This class can be extended with the help of the plugin mechanism described on the page
00028   * \ref TopicCustomizingEigen by defining the preprocessor symbol \c EIGEN_ARRAY_PLUGIN.
00029   *
00030   * \sa \ref TutorialArrayClass, \ref TopicClassHierarchy
00031   */
00032 namespace internal {
00033 template<typename _Scalar, int _Rows, int _Cols, int _Options, int _MaxRows, int _MaxCols>
00034 struct traits<Array<_Scalar, _Rows, _Cols, _Options, _MaxRows, _MaxCols> > : traits<Matrix<_Scalar, _Rows, _Cols, _Options, _MaxRows, _MaxCols> >
00035 {
00036   typedef ArrayXpr XprKind;
00037   typedef ArrayBase<Array<_Scalar, _Rows, _Cols, _Options, _MaxRows, _MaxCols> > XprBase;
00038 };
00039 }
00040 
00041 template<typename _Scalar, int _Rows, int _Cols, int _Options, int _MaxRows, int _MaxCols>
00042 class Array
00043   : public PlainObjectBase<Array<_Scalar, _Rows, _Cols, _Options, _MaxRows, _MaxCols> >
00044 {
00045   public:
00046 
00047     typedef PlainObjectBase<Array> Base;
00048     EIGEN_DENSE_PUBLIC_INTERFACE(Array)
00049 
00050     enum { Options = _Options };
00051     typedef typename Base::PlainObject PlainObject;
00052 
00053   protected:
00054     template <typename Derived, typename OtherDerived, bool IsVector>
00055     friend struct internal::conservative_resize_like_impl;
00056 
00057     using Base::m_storage;
00058 
00059   public:
00060 
00061     using Base::base;
00062     using Base::coeff;
00063     using Base::coeffRef;
00064 
00065     /**
00066       * The usage of
00067       *   using Base::operator=;
00068       * fails on MSVC. Since the code below is working with GCC and MSVC, we skipped
00069       * the usage of 'using'. This should be done only for operator=.
00070       */
00071     template<typename OtherDerived>
00072     EIGEN_STRONG_INLINE Array& operator=(const EigenBase<OtherDerived> &other)
00073     {
00074       return Base::operator=(other);
00075     }
00076 
00077     /** Copies the value of the expression \a other into \c *this with automatic resizing.
00078       *
00079       * *this might be resized to match the dimensions of \a other. If *this was a null matrix (not already initialized),
00080       * it will be initialized.
00081       *
00082       * Note that copying a row-vector into a vector (and conversely) is allowed.
00083       * The resizing, if any, is then done in the appropriate way so that row-vectors
00084       * remain row-vectors and vectors remain vectors.
00085       */
00086     template<typename OtherDerived>
00087     EIGEN_STRONG_INLINE Array& operator=(const ArrayBase<OtherDerived>& other)
00088     {
00089       return Base::_set(other);
00090     }
00091 
00092     /** This is a special case of the templated operator=. Its purpose is to
00093       * prevent a default operator= from hiding the templated operator=.
00094       */
00095     EIGEN_STRONG_INLINE Array& operator=(const Array& other)
00096     {
00097       return Base::_set(other);
00098     }
00099 
00100     /** Default constructor.
00101       *
00102       * For fixed-size matrices, does nothing.
00103       *
00104       * For dynamic-size matrices, creates an empty matrix of size 0. Does not allocate any array. Such a matrix
00105       * is called a null matrix. This constructor is the unique way to create null matrices: resizing
00106       * a matrix to 0 is not supported.
00107       *
00108       * \sa resize(Index,Index)
00109       */
00110     EIGEN_STRONG_INLINE Array() : Base()
00111     {
00112       Base::_check_template_params();
00113       EIGEN_INITIALIZE_COEFFS_IF_THAT_OPTION_IS_ENABLED
00114     }
00115 
00116 #ifndef EIGEN_PARSED_BY_DOXYGEN
00117     // FIXME is it still needed ??
00118     /** \internal */
00119     Array(internal::constructor_without_unaligned_array_assert)
00120       : Base(internal::constructor_without_unaligned_array_assert())
00121     {
00122       Base::_check_template_params();
00123       EIGEN_INITIALIZE_COEFFS_IF_THAT_OPTION_IS_ENABLED
00124     }
00125 #endif
00126 
00127 #ifdef EIGEN_HAVE_RVALUE_REFERENCES
00128     Array(Array&& other)
00129       : Base(std::move(other))
00130     {
00131       Base::_check_template_params();
00132       if (RowsAtCompileTime!=Dynamic && ColsAtCompileTime!=Dynamic)
00133         Base::_set_noalias(other);
00134     }
00135     Array& operator=(Array&& other)
00136     {
00137       other.swap(*this);
00138       return *this;
00139     }
00140 #endif
00141 
00142     /** Constructs a vector or row-vector with given dimension. \only_for_vectors
00143       *
00144       * Note that this is only useful for dynamic-size vectors. For fixed-size vectors,
00145       * it is redundant to pass the dimension here, so it makes more sense to use the default
00146       * constructor Matrix() instead.
00147       */
00148     EIGEN_STRONG_INLINE explicit Array(Index dim)
00149       : Base(dim, RowsAtCompileTime == 1 ? 1 : dim, ColsAtCompileTime == 1 ? 1 : dim)
00150     {
00151       Base::_check_template_params();
00152       EIGEN_STATIC_ASSERT_VECTOR_ONLY(Array)
00153       eigen_assert(dim >= 0);
00154       eigen_assert(SizeAtCompileTime == Dynamic || SizeAtCompileTime == dim);
00155       EIGEN_INITIALIZE_COEFFS_IF_THAT_OPTION_IS_ENABLED
00156     }
00157 
00158     #ifndef EIGEN_PARSED_BY_DOXYGEN
00159     template<typename T0, typename T1>
00160     EIGEN_STRONG_INLINE Array(const T0& val0, const T1& val1)
00161     {
00162       Base::_check_template_params();
00163       this->template _init2<T0,T1>(val0, val1);
00164     }
00165     #else
00166     /** constructs an uninitialized matrix with \a rows rows and \a cols columns.
00167       *
00168       * This is useful for dynamic-size matrices. For fixed-size matrices,
00169       * it is redundant to pass these parameters, so one should use the default constructor
00170       * Matrix() instead. */
00171     Array(Index rows, Index cols);
00172     /** constructs an initialized 2D vector with given coefficients */
00173     Array(const Scalar& val0, const Scalar& val1);
00174     #endif
00175 
00176     /** constructs an initialized 3D vector with given coefficients */
00177     EIGEN_STRONG_INLINE Array(const Scalar& val0, const Scalar& val1, const Scalar& val2)
00178     {
00179       Base::_check_template_params();
00180       EIGEN_STATIC_ASSERT_VECTOR_SPECIFIC_SIZE(Array, 3)
00181       m_storage.data()[0] = val0;
00182       m_storage.data()[1] = val1;
00183       m_storage.data()[2] = val2;
00184     }
00185     /** constructs an initialized 4D vector with given coefficients */
00186     EIGEN_STRONG_INLINE Array(const Scalar& val0, const Scalar& val1, const Scalar& val2, const Scalar& val3)
00187     {
00188       Base::_check_template_params();
00189       EIGEN_STATIC_ASSERT_VECTOR_SPECIFIC_SIZE(Array, 4)
00190       m_storage.data()[0] = val0;
00191       m_storage.data()[1] = val1;
00192       m_storage.data()[2] = val2;
00193       m_storage.data()[3] = val3;
00194     }
00195 
00196     explicit Array(const Scalar *data );
00197 
00198     /** Constructor copying the value of the expression \a other */
00199     template<typename OtherDerived>
00200     EIGEN_STRONG_INLINE Array(const ArrayBase<OtherDerived>& other)
00201              : Base(other.rows() * other.cols(), other.rows(), other.cols())
00202     {
00203       Base::_check_template_params();
00204       Base::_set_noalias(other);
00205     }
00206     /** Copy constructor */
00207     EIGEN_STRONG_INLINE Array(const Array& other)
00208             : Base(other.rows() * other.cols(), other.rows(), other.cols())
00209     {
00210       Base::_check_template_params();
00211       Base::_set_noalias(other);
00212     }
00213     /** Copy constructor with in-place evaluation */
00214     template<typename OtherDerived>
00215     EIGEN_STRONG_INLINE Array(const ReturnByValue<OtherDerived>& other)
00216     {
00217       Base::_check_template_params();
00218       Base::resize(other.rows(), other.cols());
00219       other.evalTo(*this);
00220     }
00221 
00222     /** \sa MatrixBase::operator=(const EigenBase<OtherDerived>&) */
00223     template<typename OtherDerived>
00224     EIGEN_STRONG_INLINE Array(const EigenBase<OtherDerived> &other)
00225       : Base(other.derived().rows() * other.derived().cols(), other.derived().rows(), other.derived().cols())
00226     {
00227       Base::_check_template_params();
00228       Base::_resize_to_match(other);
00229       *this = other;
00230     }
00231 
00232     /** Override MatrixBase::swap() since for dynamic-sized matrices of same type it is enough to swap the
00233       * data pointers.
00234       */
00235     template<typename OtherDerived>
00236     void swap(ArrayBase<OtherDerived> const & other)
00237     { this->_swap(other.derived()); }
00238 
00239     inline Index innerStride() const { return 1; }
00240     inline Index outerStride() const { return this->innerSize(); }
00241 
00242     #ifdef EIGEN_ARRAY_PLUGIN
00243     #include EIGEN_ARRAY_PLUGIN
00244     #endif
00245 
00246   private:
00247 
00248     template<typename MatrixType, typename OtherDerived, bool SwapPointers>
00249     friend struct internal::matrix_swap_impl;
00250 };
00251 
00252 /** \defgroup arraytypedefs Global array typedefs
00253   * \ingroup Core_Module
00254   *
00255   * Eigen defines several typedef shortcuts for most common 1D and 2D array types.
00256   *
00257   * The general patterns are the following:
00258   *
00259   * \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,
00260   * 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
00261   * for complex double.
00262   *
00263   * For example, \c Array33d is a fixed-size 3x3 array type of doubles, and \c ArrayXXf is a dynamic-size matrix of floats.
00264   *
00265   * There are also \c ArraySizeType which are self-explanatory. For example, \c Array4cf is
00266   * a fixed-size 1D array of 4 complex floats.
00267   *
00268   * \sa class Array
00269   */
00270 
00271 #define EIGEN_MAKE_ARRAY_TYPEDEFS(Type, TypeSuffix, Size, SizeSuffix)   \
00272 /** \ingroup arraytypedefs */                                    \
00273 typedef Array<Type, Size, Size> Array##SizeSuffix##SizeSuffix##TypeSuffix;  \
00274 /** \ingroup arraytypedefs */                                    \
00275 typedef Array<Type, Size, 1>    Array##SizeSuffix##TypeSuffix;
00276 
00277 #define EIGEN_MAKE_ARRAY_FIXED_TYPEDEFS(Type, TypeSuffix, Size)         \
00278 /** \ingroup arraytypedefs */                                    \
00279 typedef Array<Type, Size, Dynamic> Array##Size##X##TypeSuffix;  \
00280 /** \ingroup arraytypedefs */                                    \
00281 typedef Array<Type, Dynamic, Size> Array##X##Size##TypeSuffix;
00282 
00283 #define EIGEN_MAKE_ARRAY_TYPEDEFS_ALL_SIZES(Type, TypeSuffix) \
00284 EIGEN_MAKE_ARRAY_TYPEDEFS(Type, TypeSuffix, 2, 2) \
00285 EIGEN_MAKE_ARRAY_TYPEDEFS(Type, TypeSuffix, 3, 3) \
00286 EIGEN_MAKE_ARRAY_TYPEDEFS(Type, TypeSuffix, 4, 4) \
00287 EIGEN_MAKE_ARRAY_TYPEDEFS(Type, TypeSuffix, Dynamic, X) \
00288 EIGEN_MAKE_ARRAY_FIXED_TYPEDEFS(Type, TypeSuffix, 2) \
00289 EIGEN_MAKE_ARRAY_FIXED_TYPEDEFS(Type, TypeSuffix, 3) \
00290 EIGEN_MAKE_ARRAY_FIXED_TYPEDEFS(Type, TypeSuffix, 4)
00291 
00292 EIGEN_MAKE_ARRAY_TYPEDEFS_ALL_SIZES(int,                  i)
00293 EIGEN_MAKE_ARRAY_TYPEDEFS_ALL_SIZES(float,                f)
00294 EIGEN_MAKE_ARRAY_TYPEDEFS_ALL_SIZES(double,               d)
00295 EIGEN_MAKE_ARRAY_TYPEDEFS_ALL_SIZES(std::complex<float>,  cf)
00296 EIGEN_MAKE_ARRAY_TYPEDEFS_ALL_SIZES(std::complex<double>, cd)
00297 
00298 #undef EIGEN_MAKE_ARRAY_TYPEDEFS_ALL_SIZES
00299 #undef EIGEN_MAKE_ARRAY_TYPEDEFS
00300 
00301 #undef EIGEN_MAKE_ARRAY_TYPEDEFS_LARGE
00302 
00303 #define EIGEN_USING_ARRAY_TYPEDEFS_FOR_TYPE_AND_SIZE(TypeSuffix, SizeSuffix) \
00304 using Eigen::Matrix##SizeSuffix##TypeSuffix; \
00305 using Eigen::Vector##SizeSuffix##TypeSuffix; \
00306 using Eigen::RowVector##SizeSuffix##TypeSuffix;
00307 
00308 #define EIGEN_USING_ARRAY_TYPEDEFS_FOR_TYPE(TypeSuffix) \
00309 EIGEN_USING_ARRAY_TYPEDEFS_FOR_TYPE_AND_SIZE(TypeSuffix, 2) \
00310 EIGEN_USING_ARRAY_TYPEDEFS_FOR_TYPE_AND_SIZE(TypeSuffix, 3) \
00311 EIGEN_USING_ARRAY_TYPEDEFS_FOR_TYPE_AND_SIZE(TypeSuffix, 4) \
00312 EIGEN_USING_ARRAY_TYPEDEFS_FOR_TYPE_AND_SIZE(TypeSuffix, X) \
00313 
00314 #define EIGEN_USING_ARRAY_TYPEDEFS \
00315 EIGEN_USING_ARRAY_TYPEDEFS_FOR_TYPE(i) \
00316 EIGEN_USING_ARRAY_TYPEDEFS_FOR_TYPE(f) \
00317 EIGEN_USING_ARRAY_TYPEDEFS_FOR_TYPE(d) \
00318 EIGEN_USING_ARRAY_TYPEDEFS_FOR_TYPE(cf) \
00319 EIGEN_USING_ARRAY_TYPEDEFS_FOR_TYPE(cd)
00320 
00321 } // end namespace Eigen
00322 
00323 #endif // EIGEN_ARRAY_H