1// Copyright 2002 The Trustees of Indiana University.
2
3// Use, modification and distribution is subject to the Boost Software
4// License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
5// http://www.boost.org/LICENSE_1_0.txt)
6
7// Boost.MultiArray Library
8// Authors: Ronald Garcia
9// Jeremy Siek
10// Andrew Lumsdaine
11// See http://www.boost.org/libs/multi_array for documentation.
12
13#ifndef BOOST_MULTI_ARRAY_BASE_HPP
14#define BOOST_MULTI_ARRAY_BASE_HPP
15
16//
17// base.hpp - some implementation base classes for from which
18// functionality is acquired
19//
20
21#include "boost/multi_array/extent_range.hpp"
22#include "boost/multi_array/extent_gen.hpp"
23#include "boost/multi_array/index_range.hpp"
24#include "boost/multi_array/index_gen.hpp"
25#include "boost/multi_array/storage_order.hpp"
26#include "boost/multi_array/types.hpp"
27#include "boost/config.hpp"
28#include "boost/multi_array/concept_checks.hpp" //for ignore_unused_...
29#include "boost/mpl/eval_if.hpp"
30#include "boost/mpl/if.hpp"
31#include "boost/mpl/size_t.hpp"
32#include "boost/iterator/reverse_iterator.hpp"
33#include "boost/static_assert.hpp"
34#include "boost/type.hpp"
35#include "boost/assert.hpp"
36#include <cstddef>
37#include <memory>
38
39namespace boost {
40
41/////////////////////////////////////////////////////////////////////////
42// class declarations
43/////////////////////////////////////////////////////////////////////////
44
45template<typename T, std::size_t NumDims,
46 typename Allocator = std::allocator<T> >
47class multi_array;
48
49// This is a public interface for use by end users!
50namespace multi_array_types {
51 typedef boost::detail::multi_array::size_type size_type;
52 typedef std::ptrdiff_t difference_type;
53 typedef boost::detail::multi_array::index index;
54 typedef detail::multi_array::index_range<index,size_type> index_range;
55 typedef detail::multi_array::extent_range<index,size_type> extent_range;
56 typedef detail::multi_array::index_gen<0,0> index_gen;
57 typedef detail::multi_array::extent_gen<0> extent_gen;
58}
59
60
61// boost::extents and boost::indices are now a part of the public
62// interface. That way users don't necessarily have to create their
63// own objects. On the other hand, one may not want the overhead of
64// object creation in small-memory environments. Thus, the objects
65// can be left undefined by defining BOOST_MULTI_ARRAY_NO_GENERATORS
66// before loading multi_array.hpp.
67#ifndef BOOST_MULTI_ARRAY_NO_GENERATORS
68namespace {
69 multi_array_types::extent_gen extents;
70 multi_array_types::index_gen indices;
71}
72#endif // BOOST_MULTI_ARRAY_NO_GENERATORS
73
74namespace detail {
75namespace multi_array {
76
77template <typename T, std::size_t NumDims>
78class sub_array;
79
80template <typename T, std::size_t NumDims, typename TPtr = const T*>
81class const_sub_array;
82
83 template <typename T, typename TPtr, typename NumDims, typename Reference,
84 typename IteratorCategory>
85class array_iterator;
86
87template <typename T, std::size_t NumDims, typename TPtr = const T*>
88class const_multi_array_view;
89
90template <typename T, std::size_t NumDims>
91class multi_array_view;
92
93/////////////////////////////////////////////////////////////////////////
94// class interfaces
95/////////////////////////////////////////////////////////////////////////
96
97class multi_array_base {
98public:
99 typedef multi_array_types::size_type size_type;
100 typedef multi_array_types::difference_type difference_type;
101 typedef multi_array_types::index index;
102 typedef multi_array_types::index_range index_range;
103 typedef multi_array_types::extent_range extent_range;
104 typedef multi_array_types::index_gen index_gen;
105 typedef multi_array_types::extent_gen extent_gen;
106};
107
108//
109// value_accessor_n
110// contains the routines for accessing elements from
111// N-dimensional views.
112//
113template<typename T, std::size_t NumDims>
114class value_accessor_n : public multi_array_base {
115 typedef multi_array_base super_type;
116public:
117 typedef typename super_type::index index;
118
119 //
120 // public typedefs used by classes that inherit from this base
121 //
122 typedef T element;
123 typedef boost::multi_array<T,NumDims-1> value_type;
124 typedef sub_array<T,NumDims-1> reference;
125 typedef const_sub_array<T,NumDims-1> const_reference;
126
127protected:
128 // used by array operator[] and iterators to get reference types.
129 template <typename Reference, typename TPtr>
130 Reference access(boost::type<Reference>,index idx,TPtr base,
131 const size_type* extents,
132 const index* strides,
133 const index* index_bases) const {
134
135 BOOST_ASSERT(idx - index_bases[0] >= 0);
136 BOOST_ASSERT(size_type(idx - index_bases[0]) < extents[0]);
137 // return a sub_array<T,NDims-1> proxy object
138 TPtr newbase = base + idx * strides[0];
139 return Reference(newbase,extents+1,strides+1,index_bases+1);
140
141 }
142
143 value_accessor_n() { }
144 ~value_accessor_n() { }
145};
146
147
148
149//
150// value_accessor_one
151// contains the routines for accessing reference elements from
152// 1-dimensional views.
153//
154template<typename T>
155class value_accessor_one : public multi_array_base {
156 typedef multi_array_base super_type;
157public:
158 typedef typename super_type::index index;
159 //
160 // public typedefs for use by classes that inherit it.
161 //
162 typedef T element;
163 typedef T value_type;
164 typedef T& reference;
165 typedef T const& const_reference;
166
167protected:
168 // used by array operator[] and iterators to get reference types.
169 template <typename Reference, typename TPtr>
170 Reference access(boost::type<Reference>,index idx,TPtr base,
171 const size_type* extents,
172 const index* strides,
173 const index* index_bases) const {
174
175 ignore_unused_variable_warning(index_bases);
176 ignore_unused_variable_warning(extents);
177 BOOST_ASSERT(idx - index_bases[0] >= 0);
178 BOOST_ASSERT(size_type(idx - index_bases[0]) < extents[0]);
179 return *(base + idx * strides[0]);
180 }
181
182 value_accessor_one() { }
183 ~value_accessor_one() { }
184};
185
186
187/////////////////////////////////////////////////////////////////////////
188// choose value accessor begins
189//
190
191template <typename T, std::size_t NumDims>
192struct choose_value_accessor_n {
193 typedef value_accessor_n<T,NumDims> type;
194};
195
196template <typename T>
197struct choose_value_accessor_one {
198 typedef value_accessor_one<T> type;
199};
200
201template <typename T, typename NumDims>
202struct value_accessor_generator {
203 BOOST_STATIC_CONSTANT(std::size_t, dimensionality = NumDims::value);
204
205 typedef typename
206 mpl::eval_if_c<(dimensionality == 1),
207 choose_value_accessor_one<T>,
208 choose_value_accessor_n<T,dimensionality>
209 >::type type;
210};
211
212template <class T, class NumDims>
213struct associated_types
214 : value_accessor_generator<T,NumDims>::type
215{};
216
217//
218// choose value accessor ends
219/////////////////////////////////////////////////////////////////////////
220
221// Due to some imprecision in the C++ Standard,
222// MSVC 2010 is broken in debug mode: it requires
223// that an Output Iterator have output_iterator_tag in its iterator_category if
224// that iterator is not bidirectional_iterator or random_access_iterator.
225#if BOOST_WORKAROUND(BOOST_MSVC, >= 1600)
226struct mutable_iterator_tag
227 : boost::random_access_traversal_tag, std::input_iterator_tag
228{
229 operator std::output_iterator_tag() const {
230 return std::output_iterator_tag();
231 }
232};
233#endif
234
235////////////////////////////////////////////////////////////////////////
236// multi_array_base
237////////////////////////////////////////////////////////////////////////
238template <typename T, std::size_t NumDims>
239class multi_array_impl_base
240 :
241 public value_accessor_generator<T,mpl::size_t<NumDims> >::type
242{
243 typedef associated_types<T,mpl::size_t<NumDims> > types;
244public:
245 typedef typename types::index index;
246 typedef typename types::size_type size_type;
247 typedef typename types::element element;
248 typedef typename types::index_range index_range;
249 typedef typename types::value_type value_type;
250 typedef typename types::reference reference;
251 typedef typename types::const_reference const_reference;
252
253 template <std::size_t NDims>
254 struct subarray {
255 typedef boost::detail::multi_array::sub_array<T,NDims> type;
256 };
257
258 template <std::size_t NDims>
259 struct const_subarray {
260 typedef boost::detail::multi_array::const_sub_array<T,NDims> type;
261 };
262
263 template <std::size_t NDims>
264 struct array_view {
265 typedef boost::detail::multi_array::multi_array_view<T,NDims> type;
266 };
267
268 template <std::size_t NDims>
269 struct const_array_view {
270 public:
271 typedef boost::detail::multi_array::const_multi_array_view<T,NDims> type;
272 };
273
274 //
275 // iterator support
276 //
277#if BOOST_WORKAROUND(BOOST_MSVC, >= 1600)
278 // Deal with VC 2010 output_iterator_tag requirement
279 typedef array_iterator<T,T*,mpl::size_t<NumDims>,reference,
280 mutable_iterator_tag> iterator;
281#else
282 typedef array_iterator<T,T*,mpl::size_t<NumDims>,reference,
283 boost::random_access_traversal_tag> iterator;
284#endif
285 typedef array_iterator<T,T const*,mpl::size_t<NumDims>,const_reference,
286 boost::random_access_traversal_tag> const_iterator;
287
288 typedef ::boost::reverse_iterator<iterator> reverse_iterator;
289 typedef ::boost::reverse_iterator<const_iterator> const_reverse_iterator;
290
291 BOOST_STATIC_CONSTANT(std::size_t, dimensionality = NumDims);
292protected:
293
294 multi_array_impl_base() { }
295 ~multi_array_impl_base() { }
296
297 // Used by operator() in our array classes
298 template <typename Reference, typename IndexList, typename TPtr>
299 Reference access_element(boost::type<Reference>,
300 const IndexList& indices,
301 TPtr base,
302 const size_type* extents,
303 const index* strides,
304 const index* index_bases) const {
305 boost::function_requires<
306 CollectionConcept<IndexList> >();
307 ignore_unused_variable_warning(index_bases);
308 ignore_unused_variable_warning(extents);
309#if !defined(NDEBUG) && !defined(BOOST_DISABLE_ASSERTS)
310 for (size_type i = 0; i != NumDims; ++i) {
311 BOOST_ASSERT(indices[i] - index_bases[i] >= 0);
312 BOOST_ASSERT(size_type(indices[i] - index_bases[i]) < extents[i]);
313 }
314#endif
315
316 index offset = 0;
317 {
318 typename IndexList::const_iterator i = indices.begin();
319 size_type n = 0;
320 while (n != NumDims) {
321 offset += (*i) * strides[n];
322 ++n;
323 ++i;
324 }
325 }
326 return base[offset];
327 }
328
329 template <typename StrideList, typename ExtentList>
330 void compute_strides(StrideList& stride_list, ExtentList& extent_list,
331 const general_storage_order<NumDims>& storage)
332 {
333 // invariant: stride = the stride for dimension n
334 index stride = 1;
335 for (size_type n = 0; n != NumDims; ++n) {
336 index stride_sign = +1;
337
338 if (!storage.ascending(storage.ordering(n)))
339 stride_sign = -1;
340
341 // The stride for this dimension is the product of the
342 // lengths of the ranks minor to it.
343 stride_list[storage.ordering(n)] = stride * stride_sign;
344
345 stride *= extent_list[storage.ordering(n)];
346 }
347 }
348
349 // This calculates the offset to the array base pointer due to:
350 // 1. dimensions stored in descending order
351 // 2. non-zero dimension index bases
352 template <typename StrideList, typename ExtentList, typename BaseList>
353 index
354 calculate_origin_offset(const StrideList& stride_list,
355 const ExtentList& extent_list,
356 const general_storage_order<NumDims>& storage,
357 const BaseList& index_base_list)
358 {
359 return
360 calculate_descending_dimension_offset(stride_list,extent_list,
361 storage) +
362 calculate_indexing_offset(stride_list,index_base_list);
363 }
364
365 // This calculates the offset added to the base pointer that are
366 // caused by descending dimensions
367 template <typename StrideList, typename ExtentList>
368 index
369 calculate_descending_dimension_offset(const StrideList& stride_list,
370 const ExtentList& extent_list,
371 const general_storage_order<NumDims>& storage)
372 {
373 index offset = 0;
374 if (!storage.all_dims_ascending())
375 for (size_type n = 0; n != NumDims; ++n)
376 if (!storage.ascending(n))
377 offset -= (extent_list[n] - 1) * stride_list[n];
378
379 return offset;
380 }
381
382 // This is used to reindex array_views, which are no longer
383 // concerned about storage order (specifically, whether dimensions
384 // are ascending or descending) since the viewed array handled it.
385
386 template <typename StrideList, typename BaseList>
387 index
388 calculate_indexing_offset(const StrideList& stride_list,
389 const BaseList& index_base_list)
390 {
391 index offset = 0;
392 for (size_type n = 0; n != NumDims; ++n)
393 offset -= stride_list[n] * index_base_list[n];
394 return offset;
395 }
396
397 // Slicing using an index_gen.
398 // Note that populating an index_gen creates a type that encodes
399 // both the number of dimensions in the current Array (NumDims), and
400 // the Number of dimensions for the resulting view. This allows the
401 // compiler to fail if the dimensions aren't completely accounted
402 // for. For reasons unbeknownst to me, a BOOST_STATIC_ASSERT
403 // within the member function template does not work. I should add a
404 // note to the documentation specifying that you get a damn ugly
405 // error message if you screw up in your slicing code.
406 template <typename ArrayRef, int NDims, typename TPtr>
407 ArrayRef
408 generate_array_view(boost::type<ArrayRef>,
409 const boost::detail::multi_array::
410 index_gen<NumDims,NDims>& indices,
411 const size_type* extents,
412 const index* strides,
413 const index* index_bases,
414 TPtr base) const {
415
416 boost::array<index,NDims> new_strides;
417 boost::array<index,NDims> new_extents;
418
419 index offset = 0;
420 size_type dim = 0;
421 for (size_type n = 0; n != NumDims; ++n) {
422
423 // Use array specs and input specs to produce real specs.
424 const index default_start = index_bases[n];
425 const index default_finish = default_start+extents[n];
426 const index_range& current_range = indices.ranges_[n];
427 index start = current_range.get_start(default_start);
428 index finish = current_range.get_finish(default_finish);
429 index stride = current_range.stride();
430 BOOST_ASSERT(stride != 0);
431
432 // An index range indicates a half-open strided interval
433 // [start,finish) (with stride) which faces upward when stride
434 // is positive and downward when stride is negative,
435
436 // RG: The following code for calculating length suffers from
437 // some representation issues: if finish-start cannot be represented as
438 // by type index, then overflow may result.
439
440 index len;
441 if ((finish - start) / stride < 0) {
442 // [start,finish) is empty according to the direction imposed by
443 // the stride.
444 len = 0;
445 } else {
446 // integral trick for ceiling((finish-start) / stride)
447 // taking into account signs.
448 index shrinkage = stride > 0 ? 1 : -1;
449 len = (finish - start + (stride - shrinkage)) / stride;
450 }
451
452 // start marks the closed side of the range, so it must lie
453 // exactly in the set of legal indices
454 // with a special case for empty arrays
455 BOOST_ASSERT(index_bases[n] <= start &&
456 ((start <= index_bases[n]+index(extents[n])) ||
457 (start == index_bases[n] && extents[n] == 0)));
458
459#ifndef BOOST_DISABLE_ASSERTS
460 // finish marks the open side of the range, so it can go one past
461 // the "far side" of the range (the top if stride is positive, the bottom
462 // if stride is negative).
463 index bound_adjustment = stride < 0 ? 1 : 0;
464 BOOST_ASSERT(((index_bases[n] - bound_adjustment) <= finish) &&
465 (finish <= (index_bases[n] + index(extents[n]) - bound_adjustment)));
466 ignore_unused_variable_warning(bound_adjustment);
467#endif // BOOST_DISABLE_ASSERTS
468
469
470 // the array data pointer is modified to account for non-zero
471 // bases during slicing (see [Garcia] for the math involved)
472 offset += start * strides[n];
473
474 if (!current_range.is_degenerate()) {
475
476 // The stride for each dimension is included into the
477 // strides for the array_view (see [Garcia] for the math involved).
478 new_strides[dim] = stride * strides[n];
479
480 // calculate new extents
481 new_extents[dim] = len;
482 ++dim;
483 }
484 }
485 BOOST_ASSERT(dim == NDims);
486
487 return
488 ArrayRef(base+offset,
489 new_extents,
490 new_strides);
491 }
492
493
494};
495
496} // namespace multi_array
497} // namespace detail
498
499} // namespace boost
500
501#endif
502

source code of include/boost/multi_array/base.hpp