boost/multi_array/base.hpp

0001 // Copyright 2002 The Trustees of Indiana University.
0002
0003 // Use, modification and distribution is subject to the Boost Software
0004 // License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
0005 // http://www.boost.org/LICENSE_1_0.txt)
0006
0007 //  Boost.MultiArray Library
0008 //  Authors: Ronald Garcia
0009 //           Jeremy Siek
0010 //           Andrew Lumsdaine
0011 //  See http://www.boost.org/libs/multi_array for documentation.
0012
0013 #ifndef BOOST_MULTI_ARRAY_BASE_HPP
0014 #define BOOST_MULTI_ARRAY_BASE_HPP
0015
0016 //
0017 // base.hpp - some implementation base classes for from which
0018 // functionality is acquired
0019 //
0020
0021 #include "boost/multi_array/extent_range.hpp"
0022 #include "boost/multi_array/extent_gen.hpp"
0023 #include "boost/multi_array/index_range.hpp"
0024 #include "boost/multi_array/index_gen.hpp"
0025 #include "boost/multi_array/storage_order.hpp"
0026 #include "boost/multi_array/types.hpp"
0027 #include "boost/config.hpp"
0028 #include "boost/multi_array/concept_checks.hpp" //for ignore_unused_...
0029 #include "boost/mpl/eval_if.hpp"
0030 #include "boost/mpl/if.hpp"
0031 #include "boost/mpl/size_t.hpp"
0032 #include "boost/iterator/reverse_iterator.hpp"
0033 #include "boost/static_assert.hpp"
0034 #include "boost/type.hpp"
0035 #include "boost/assert.hpp"
0036 #include <cstddef>
0037 #include <memory>
0038
0039 namespace boost {
0040
0041 /////////////////////////////////////////////////////////////////////////
0042 // class declarations
0043 /////////////////////////////////////////////////////////////////////////
0044
0045 template<typename T, std::size_t NumDims,
0046   typename Allocator = std::allocator<T> >
0047 class multi_array;
0048
0049 // This is a public interface for use by end users!
0050 namespace multi_array_types {
0051   typedef boost::detail::multi_array::size_type size_type;
0052   typedef std::ptrdiff_t difference_type;
0053   typedef boost::detail::multi_array::index index;
0054   typedef detail::multi_array::index_range<index,size_type> index_range;
0055   typedef detail::multi_array::extent_range<index,size_type> extent_range;
0056   typedef detail::multi_array::index_gen<0,0> index_gen;
0057   typedef detail::multi_array::extent_gen<0> extent_gen;
0058 }
0059
0060
0061 // boost::extents and boost::indices are now a part of the public
0062 // interface.  That way users don't necessarily have to create their
0063 // own objects.  On the other hand, one may not want the overhead of
0064 // object creation in small-memory environments.  Thus, the objects
0065 // can be left undefined by defining BOOST_MULTI_ARRAY_NO_GENERATORS
0066 // before loading multi_array.hpp.
0067 #ifndef BOOST_MULTI_ARRAY_NO_GENERATORS
0068 namespace {
0069   multi_array_types::extent_gen extents;
0070   multi_array_types::index_gen indices;
0071 }
0072 #endif // BOOST_MULTI_ARRAY_NO_GENERATORS
0073
0074 namespace detail {
0075 namespace multi_array {
0076
0077 template <typename T, std::size_t NumDims>
0078 class sub_array;
0079
0080 template <typename T, std::size_t NumDims, typename TPtr = const T*>
0081 class const_sub_array;
0082
0083   template <typename T, typename TPtr, typename NumDims, typename Reference,
0084             typename IteratorCategory>
0085 class array_iterator;
0086
0087 template <typename T, std::size_t NumDims, typename TPtr = const T*>
0088 class const_multi_array_view;
0089
0090 template <typename T, std::size_t NumDims>
0091 class multi_array_view;
0092
0093 /////////////////////////////////////////////////////////////////////////
0094 // class interfaces
0095 /////////////////////////////////////////////////////////////////////////
0096
0097 class multi_array_base {
0098 public:
0099   typedef multi_array_types::size_type size_type;
0100   typedef multi_array_types::difference_type difference_type;
0101   typedef multi_array_types::index index;
0102   typedef multi_array_types::index_range index_range;
0103   typedef multi_array_types::extent_range extent_range;
0104   typedef multi_array_types::index_gen index_gen;
0105   typedef multi_array_types::extent_gen extent_gen;
0106 };
0107
0108 //
0109 // value_accessor_n
0110 //  contains the routines for accessing elements from
0111 //  N-dimensional views.
0112 //
0113 template<typename T, std::size_t NumDims>
0114 class value_accessor_n : public multi_array_base {
0115   typedef multi_array_base super_type;
0116 public:
0117   typedef typename super_type::index index;
0118
0119   //
0120   // public typedefs used by classes that inherit from this base
0121   //
0122   typedef T element;
0123   typedef boost::multi_array<T,NumDims-1> value_type;
0124   typedef sub_array<T,NumDims-1> reference;
0125   typedef const_sub_array<T,NumDims-1> const_reference;
0126
0127 protected:
0128   // used by array operator[] and iterators to get reference types.
0129   template <typename Reference, typename TPtr>
0130   Reference access(boost::type<Reference>,index idx,TPtr base,
0131                    const size_type* extents,
0132                    const index* strides,
0133                    const index* index_bases) const {
0134
0135     BOOST_ASSERT(idx - index_bases[0] >= 0);
0136     BOOST_ASSERT(size_type(idx - index_bases[0]) < extents[0]);
0137     // return a sub_array<T,NDims-1> proxy object
0138     TPtr newbase = base + idx * strides[0];
0139     return Reference(newbase,extents+1,strides+1,index_bases+1);
0140
0141   }
0142
0143   value_accessor_n() { }
0144   ~value_accessor_n() { }
0145 };
0146
0147
0148
0149 //
0150 // value_accessor_one
0151 //  contains the routines for accessing reference elements from
0152 //  1-dimensional views.
0153 //
0154 template<typename T>
0155 class value_accessor_one : public multi_array_base {
0156   typedef multi_array_base super_type;
0157 public:
0158   typedef typename super_type::index index;
0159   //
0160   // public typedefs for use by classes that inherit it.
0161   //
0162   typedef T element;
0163   typedef T value_type;
0164   typedef T& reference;
0165   typedef T const& const_reference;
0166
0167 protected:
0168   // used by array operator[] and iterators to get reference types.
0169   template <typename Reference, typename TPtr>
0170   Reference access(boost::type<Reference>,index idx,TPtr base,
0171                    const size_type* extents,
0172                    const index* strides,
0173                    const index* index_bases) const {
0174
0175     ignore_unused_variable_warning(index_bases);
0176     ignore_unused_variable_warning(extents);
0177     BOOST_ASSERT(idx - index_bases[0] >= 0);
0178     BOOST_ASSERT(size_type(idx - index_bases[0]) < extents[0]);
0179     return *(base + idx * strides[0]);
0180   }
0181
0182   value_accessor_one() { }
0183   ~value_accessor_one() { }
0184 };
0185
0186
0187 /////////////////////////////////////////////////////////////////////////
0188 // choose value accessor begins
0189 //
0190
0191 template <typename T, std::size_t NumDims>
0192 struct choose_value_accessor_n {
0193   typedef value_accessor_n<T,NumDims> type;
0194 };
0195
0196 template <typename T>
0197 struct choose_value_accessor_one {
0198   typedef value_accessor_one<T> type;
0199 };
0200
0201 template <typename T, typename NumDims>
0202 struct value_accessor_generator {
0203     BOOST_STATIC_CONSTANT(std::size_t, dimensionality = NumDims::value);
0204
0205   typedef typename
0206   mpl::eval_if_c<(dimensionality == 1),
0207                   choose_value_accessor_one<T>,
0208                   choose_value_accessor_n<T,dimensionality>
0209   >::type type;
0210 };
0211
0212 template <class T, class NumDims>
0213 struct associated_types
0214   : value_accessor_generator<T,NumDims>::type
0215 {};
0216
0217 //
0218 // choose value accessor ends
0219 /////////////////////////////////////////////////////////////////////////
0220
0221 // Due to some imprecision in the C++ Standard,
0222 // MSVC 2010 is broken in debug mode: it requires
0223 // that an Output Iterator have output_iterator_tag in its iterator_category if
0224 // that iterator is not bidirectional_iterator or random_access_iterator.
0225 #if BOOST_WORKAROUND(BOOST_MSVC, >= 1600)
0226 struct mutable_iterator_tag
0227  : boost::random_access_traversal_tag, std::input_iterator_tag
0228 {
0229   operator std::output_iterator_tag() const {
0230     return std::output_iterator_tag();
0231   }
0232 };
0233 #endif
0234
0235 ////////////////////////////////////////////////////////////////////////
0236 // multi_array_base
0237 ////////////////////////////////////////////////////////////////////////
0238 template <typename T, std::size_t NumDims>
0239 class multi_array_impl_base
0240   :
0241       public value_accessor_generator<T,mpl::size_t<NumDims> >::type
0242 {
0243   typedef associated_types<T,mpl::size_t<NumDims> > types;
0244 public:
0245   typedef typename types::index index;
0246   typedef typename types::size_type size_type;
0247   typedef typename types::element element;
0248   typedef typename types::index_range index_range;
0249   typedef typename types::value_type value_type;
0250   typedef typename types::reference reference;
0251   typedef typename types::const_reference const_reference;
0252
0253   template <std::size_t NDims>
0254   struct subarray {
0255     typedef boost::detail::multi_array::sub_array<T,NDims> type;
0256   };
0257
0258   template <std::size_t NDims>
0259   struct const_subarray {
0260     typedef boost::detail::multi_array::const_sub_array<T,NDims> type;
0261   };
0262
0263   template <std::size_t NDims>
0264   struct array_view {
0265     typedef boost::detail::multi_array::multi_array_view<T,NDims> type;
0266   };
0267
0268   template <std::size_t NDims>
0269   struct const_array_view {
0270   public:
0271     typedef boost::detail::multi_array::const_multi_array_view<T,NDims> type;
0272   };
0273
0274   //
0275   // iterator support
0276   //
0277 #if BOOST_WORKAROUND(BOOST_MSVC, >= 1600)
0278   // Deal with VC 2010 output_iterator_tag requirement
0279   typedef array_iterator<T,T*,mpl::size_t<NumDims>,reference,
0280                          mutable_iterator_tag> iterator;
0281 #else
0282   typedef array_iterator<T,T*,mpl::size_t<NumDims>,reference,
0283                          boost::random_access_traversal_tag> iterator;
0284 #endif
0285   typedef array_iterator<T,T const*,mpl::size_t<NumDims>,const_reference,
0286                          boost::random_access_traversal_tag> const_iterator;
0287
0288   typedef ::boost::reverse_iterator<iterator> reverse_iterator;
0289   typedef ::boost::reverse_iterator<const_iterator> const_reverse_iterator;
0290
0291   BOOST_STATIC_CONSTANT(std::size_t, dimensionality = NumDims);
0292 protected:
0293
0294   multi_array_impl_base() { }
0295   ~multi_array_impl_base() { }
0296
0297   // Used by operator() in our array classes
0298   template <typename Reference, typename IndexList, typename TPtr>
0299   Reference access_element(boost::type<Reference>,
0300                            const IndexList& indices,
0301                            TPtr base,
0302                            const size_type* extents,
0303                            const index* strides,
0304                            const index* index_bases) const {
0305     boost::function_requires<
0306       CollectionConcept<IndexList> >();
0307     ignore_unused_variable_warning(index_bases);
0308     ignore_unused_variable_warning(extents);
0309 #if !defined(NDEBUG) && !defined(BOOST_DISABLE_ASSERTS)
0310     for (size_type i = 0; i != NumDims; ++i) {
0311       BOOST_ASSERT(indices[i] - index_bases[i] >= 0);
0312       BOOST_ASSERT(size_type(indices[i] - index_bases[i]) < extents[i]);
0313     }
0314 #endif
0315
0316     index offset = 0;
0317     {
0318       typename IndexList::const_iterator i = indices.begin();
0319       size_type n = 0;
0320       while (n != NumDims) {
0321         offset += (*i) * strides[n];
0322         ++n;
0323         ++i;
0324       }
0325     }
0326     return base[offset];
0327   }
0328
0329   template <typename StrideList, typename ExtentList>
0330   void compute_strides(StrideList& stride_list, ExtentList& extent_list,
0331                        const general_storage_order<NumDims>& storage)
0332   {
0333     // invariant: stride = the stride for dimension n
0334     index stride = 1;
0335     for (size_type n = 0; n != NumDims; ++n) {
0336       index stride_sign = +1;
0337
0338       if (!storage.ascending(storage.ordering(n)))
0339         stride_sign = -1;
0340
0341       // The stride for this dimension is the product of the
0342       // lengths of the ranks minor to it.
0343       stride_list[storage.ordering(n)] = stride * stride_sign;
0344
0345       stride *= extent_list[storage.ordering(n)];
0346     }
0347   }
0348
0349   // This calculates the offset to the array base pointer due to:
0350   // 1. dimensions stored in descending order
0351   // 2. non-zero dimension index bases
0352   template <typename StrideList, typename ExtentList, typename BaseList>
0353   index
0354   calculate_origin_offset(const StrideList& stride_list,
0355                           const ExtentList& extent_list,
0356                           const general_storage_order<NumDims>& storage,
0357                           const BaseList& index_base_list)
0358   {
0359     return
0360       calculate_descending_dimension_offset(stride_list,extent_list,
0361                                             storage) +
0362       calculate_indexing_offset(stride_list,index_base_list);
0363   }
0364
0365   // This calculates the offset added to the base pointer that are
0366   // caused by descending dimensions
0367   template <typename StrideList, typename ExtentList>
0368   index
0369   calculate_descending_dimension_offset(const StrideList& stride_list,
0370                                 const ExtentList& extent_list,
0371                                 const general_storage_order<NumDims>& storage)
0372   {
0373     index offset = 0;
0374     if (!storage.all_dims_ascending())
0375       for (size_type n = 0; n != NumDims; ++n)
0376         if (!storage.ascending(n))
0377           offset -= (extent_list[n] - 1) * stride_list[n];
0378
0379     return offset;
0380   }
0381
0382   // This is used to reindex array_views, which are no longer
0383   // concerned about storage order (specifically, whether dimensions
0384   // are ascending or descending) since the viewed array handled it.
0385
0386   template <typename StrideList, typename BaseList>
0387   index
0388   calculate_indexing_offset(const StrideList& stride_list,
0389                           const BaseList& index_base_list)
0390   {
0391     index offset = 0;
0392     for (size_type n = 0; n != NumDims; ++n)
0393         offset -= stride_list[n] * index_base_list[n];
0394     return offset;
0395   }
0396
0397   // Slicing using an index_gen.
0398   // Note that populating an index_gen creates a type that encodes
0399   // both the number of dimensions in the current Array (NumDims), and
0400   // the Number of dimensions for the resulting view.  This allows the
0401   // compiler to fail if the dimensions aren't completely accounted
0402   // for.  For reasons unbeknownst to me, a BOOST_STATIC_ASSERT
0403   // within the member function template does not work. I should add a
0404   // note to the documentation specifying that you get a damn ugly
0405   // error message if you screw up in your slicing code.
0406   template <typename ArrayRef, int NDims, typename TPtr>
0407   ArrayRef
0408   generate_array_view(boost::type<ArrayRef>,
0409                       const boost::detail::multi_array::
0410                       index_gen<NumDims,NDims>& indices,
0411                       const size_type* extents,
0412                       const index* strides,
0413                       const index* index_bases,
0414                       TPtr base) const {
0415
0416     boost::array<index,NDims> new_strides;
0417     boost::array<index,NDims> new_extents;
0418
0419     index offset = 0;
0420     size_type dim = 0;
0421     for (size_type n = 0; n != NumDims; ++n) {
0422
0423       // Use array specs and input specs to produce real specs.
0424       const index default_start = index_bases[n];
0425       const index default_finish = default_start+extents[n];
0426       const index_range& current_range = indices.ranges_[n];
0427       index start = current_range.get_start(default_start);
0428       index finish = current_range.get_finish(default_finish);
0429       index stride = current_range.stride();
0430       BOOST_ASSERT(stride != 0);
0431
0432       // An index range indicates a half-open strided interval
0433       // [start,finish) (with stride) which faces upward when stride
0434       // is positive and downward when stride is negative,
0435
0436       // RG: The following code for calculating length suffers from
0437       // some representation issues: if finish-start cannot be represented as
0438       // by type index, then overflow may result.
0439
0440       index len;
0441       if ((finish - start) / stride < 0) {
0442         // [start,finish) is empty according to the direction imposed by
0443         // the stride.
0444         len = 0;
0445       } else {
0446         // integral trick for ceiling((finish-start) / stride)
0447         // taking into account signs.
0448         index shrinkage = stride > 0 ? 1 : -1;
0449         len = (finish - start + (stride - shrinkage)) / stride;
0450       }
0451
0452       // start marks the closed side of the range, so it must lie
0453       // exactly in the set of legal indices
0454       // with a special case for empty arrays
0455       BOOST_ASSERT(index_bases[n] <= start &&
0456                    ((start <= index_bases[n]+index(extents[n])) ||
0457                      (start == index_bases[n] && extents[n] == 0)));
0458
0459 #ifndef BOOST_DISABLE_ASSERTS
0460       // finish marks the open side of the range, so it can go one past
0461       // the "far side" of the range (the top if stride is positive, the bottom
0462       // if stride is negative).
0463       index bound_adjustment = stride < 0 ? 1 : 0;
0464       BOOST_ASSERT(((index_bases[n] - bound_adjustment) <= finish) &&
0465         (finish <= (index_bases[n] + index(extents[n]) - bound_adjustment)));
0466       ignore_unused_variable_warning(bound_adjustment);
0467 #endif // BOOST_DISABLE_ASSERTS
0468
0469
0470       // the array data pointer is modified to account for non-zero
0471       // bases during slicing (see [Garcia] for the math involved)
0472       offset += start * strides[n];
0473
0474       if (!current_range.is_degenerate()) {
0475
0476         // The stride for each dimension is included into the
0477         // strides for the array_view (see [Garcia] for the math involved).
0478         new_strides[dim] = stride * strides[n];
0479
0480         // calculate new extents
0481         new_extents[dim] = len;
0482         ++dim;
0483       }
0484     }
0485     BOOST_ASSERT(dim == NDims);
0486
0487     return
0488       ArrayRef(base+offset,
0489                new_extents,
0490                new_strides);
0491   }
0492
0493
0494 };
0495
0496 } // namespace multi_array
0497 } // namespace detail
0498
0499 } // namespace boost
0500
0501 #endif