Array Components

multi_array
multi_array_ref
const_multi_array_ref

Boost.MultiArray defines an array class, multi_array, and two adapter classes, multi_array_ref and const_multi_array_ref. The three classes model MultiArray and so they share a lot of functionality. multi_array_ref differs from multi_array in that the multi_array manages its own memory, while multi_array_ref is passed a block of memory that it expects to be externally managed. const_multi_array_ref differs from multi_array_ref in that the underlying elements it adapts cannot be modified through its interface, though some array properties, including the array shape and index bases, can be altered. Functionality the classes have in common is described below.

Note: Preconditions, Effects, and Implementation. Throughout the following sections, small pieces of C++ code are used to specify constraints such as preconditions, effects, and postconditions. These do not necessarily describe the underlying implementation of array components; rather, they describe the expected input to and behavior of the specified operations. Failure to meet preconditions results in undefined behavior. Not all effects (i.e. copy constructors, etc.) must be mimicked exactly. The code snippets for effects intend to capture the essence of the described operation.

Queries.

element* data(); const element* data() const;: This returns a pointer to the beginning of the contiguous block that contains the array's data. If all dimensions of the array are 0-indexed and stored in ascending order, this is equivalent to origin(). Note that const_multi_array_ref only provides the const version of this function.
element* origin(); const element* origin() const;: This returns the origin element of the multi_array. Note that const_multi_array_ref only provides the const version of this function. (Required by MultiArray)
const index* index_bases();: This returns the index bases for the multi_array. (Required by MultiArray)
const index* strides();: This returns the strides for the multi_array. (Required by MultiArray)
const size_type* shape();: This returns the shape of the multi_array. (Required by MultiArray)

Comparators.

bool operator==(const *array-type*& rhs); bool operator!=(const *array-type*& rhs); bool operator<(const *array-type*& rhs); bool operator>(const *array-type*& rhs); bool operator>=(const *array-type*& rhs); bool operator<=(const *array-type*& rhs);

Each comparator executes a lexicographical compare over the value types of the two arrays. (Required by MultiArray)

Preconditions. element must support the comparator corresponding to that called on multi_array.

Complexity. O(num_elements()).

Modifiers.

template <typename SizeList> void reshape(const SizeList& sizes)

This changes the shape of the multi_array. The number of elements and the index bases remain the same, but the number of values at each level of the nested container hierarchy may change.

SizeList Requirements. SizeList must model Collection.

Preconditions.

std::accumulate(sizes.begin(),sizes.end(),size_type(1),std::times<size_type>()) == this->num_elements();
sizes.size() == NumDims;

Postconditions. std::equal(sizes.begin(),sizes.end(),this->shape) == true;

template <typename BaseList> void reindex(const BaseList& values);

This changes the index bases of the multi_array to correspond to the the values in values.

BaseList Requirements. BaseList must model Collection.

Preconditions. values.size() == NumDims;

Postconditions. std::equal(values.begin(),values.end(),this->index_bases());

void reindex(index value);

This changes the index bases of all dimensions of the multi_array to value.

Postconditions.


std::count_if(this->index_bases(),this->index_bases()+this->num_dimensions(),
              std::bind_2nd(std::equal_to<index>(),value)) == 
              this->num_dimensions();

`multi_array`

multi_array is a multi-dimensional container that supports random access iteration. Its number of dimensions is fixed at compile time, but its shape and the number of elements it contains are specified during its construction. The number of elements will remain fixed for the duration of a multi_array's lifetime, but the shape of the container can be changed. A multi_array manages its data elements using a replaceable allocator.

Model Of. MultiArray, CopyConstructible. Depending on the element type, it may also model EqualityComparable and LessThanComparable.

Synopsis.


namespace boost {

template <typename ValueType, 
          std::size_t NumDims, 
          typename Allocator = std::allocator<ValueType> >
class multi_array {
public:
// types:
  typedef ValueType                             element;
  typedef *unspecified*                         value_type;
  typedef *unspecified*                         reference;
  typedef *unspecified*                         const_reference;
  typedef *unspecified*                         difference_type;
  typedef *unspecified*                         iterator;
  typedef *unspecified*                         const_iterator;
  typedef *unspecified*                         reverse_iterator;
  typedef *unspecified*                         const_reverse_iterator;
  typedef multi_array_types::size_type          size_type;
  typedef multi_array_types::index              index;
  typedef multi_array_types::index_gen          index_gen;
  typedef multi_array_types::index_range        index_range;
  typedef multi_array_types::extent_gen         extent_gen;
  typedef multi_array_types::extent_range       extent_range;
  typedef *unspecified*                         storage_order_type;


  // template typedefs
  template <std::size_t Dims> struct            subarray;
  template <std::size_t Dims> struct            const_subarray;
  template <std::size_t Dims> struct            array_view;
  template <std::size_t Dims> struct            const_array_view;
  

  static const std::size_t dimensionality = NumDims;
  

  // constructors and destructors

  multi_array(const Allocator& alloc = Allocator());

  template <typename ExtentList>
  explicit multi_array(const ExtentList& sizes,
                       const storage_order_type& store = c_storage_order(),
                       const Allocator& alloc = Allocator());
  explicit multi_array(const extents_tuple& ranges,
                       const storage_order_type& store = c_storage_order(),
	               const Allocator& alloc = Allocator());
  multi_array(const multi_array& x);
  multi_array(const const_multi_array_ref<ValueType,NumDims>& x,
              const Allocator& alloc = Allocator());
  multi_array(const const_subarray<NumDims>::type& x,
              const Allocator& alloc = Allocator());
  multi_array(const const_array_view<NumDims>::type& x,
              const Allocator& alloc = Allocator());

  multi_array(const multi_array_ref<ValueType,NumDims>& x,
              const Allocator& alloc = Allocator());
  multi_array(const subarray<NumDims>::type& x,
              const Allocator& alloc = Allocator());
  multi_array(const array_view<NumDims>::type& x,
              const Allocator& alloc = Allocator());

  ~multi_array();

  // modifiers

  multi_array& operator=(const multi_array& x);
  template <class Array> multi_array& operator=(const Array& x);

  // iterators:
  iterator				begin();
  iterator				end();
  const_iterator			begin() const;
  const_iterator			end() const;
  reverse_iterator			rbegin();
  reverse_iterator			rend();
  const_reverse_iterator		rbegin() const;
  const_reverse_iterator		rend() const;

  // capacity:
  size_type				size() const;
  size_type				num_elements() const;
  size_type				num_dimensions() const;
 
  // element access:
  template <typename IndexList> 
    element&			operator()(const IndexList& indices);
  template <typename IndexList>
    const element&		operator()(const IndexList& indices) const;
  reference			operator[](index i);
  const_reference		operator[](index i) const;
  array_view<Dims>::type	operator[](const indices_tuple& r);
  const_array_view<Dims>::type	operator[](const indices_tuple& r) const;

  // queries
  element*			data();
  const element*		data() const;
  element*			origin();
  const element*		origin() const;
  const size_type*		shape() const;
  const index*			strides() const;
  const index*			index_bases() const;
  const storage_order_type&     storage_order() const;

  // comparators
  bool operator==(const multi_array& rhs);
  bool operator!=(const multi_array& rhs);
  bool operator<(const multi_array& rhs);
  bool operator>(const multi_array& rhs);
  bool operator>=(const multi_array& rhs);
  bool operator<=(const multi_array& rhs);

  // modifiers:
  template <typename InputIterator>
    void			assign(InputIterator begin, InputIterator end);
  template <typename SizeList>
    void			reshape(const SizeList& sizes)
  template <typename BaseList>	void reindex(const BaseList& values);
    void			reindex(index value);
  template <typename ExtentList>
    multi_array&		resize(const ExtentList& extents);
  multi_array&                  resize(extents_tuple& extents);
};

Constructors.

template <typename ExtentList> explicit multi_array(const ExtentList& sizes, const storage_order_type& store = c_storage_order(), const Allocator& alloc = Allocator());

This constructs a multi_array using the specified parameters. sizes specifies the shape of the constructed multi_array. store specifies the storage order or layout in memory of the array dimensions. alloc is used to allocate the contained elements.

ExtentList Requirements. ExtentList must model Collection.

Preconditions. sizes.size() == NumDims;

explicit multi_array(extent_gen::gen_type<NumDims>::type ranges, const storage_order_type& store = c_storage_order(), const Allocator& alloc = Allocator());

This constructs a multi_array using the specified parameters. ranges specifies the shape and index bases of the constructed multi_array. It is the result of NumDims chained calls to extent_gen::operator[]. store specifies the storage order or layout in memory of the array dimensions. alloc is the allocator used to allocate the memory used to store multi_array elements.

multi_array(const multi_array& x); multi_array(const const_multi_array_ref<ValueType,NumDims>& x, const Allocator& alloc = Allocator()); multi_array(const const_subarray<NumDims>::type& x, const Allocator& alloc = Allocator()); multi_array(const const_array_view<NumDims>::type& x, const Allocator& alloc = Allocator()); multi_array(const multi_array_ref<ValueType,NumDims>& x, const Allocator& alloc = Allocator()); multi_array(const subarray<NumDims>::type& x, const Allocator& alloc = Allocator()); multi_array(const array_view<NumDims>::type& x, const Allocator& alloc = Allocator());

These constructors all constructs a multi_array and perform a deep copy of x.

Complexity. This performs O(x.num_elements()) calls to element's copy constructor.

multi_array();

This constructs a multi_array whose shape is (0,...,0) and contains no elements.

Note on Constructors. The multi_array construction expressions,

     multi_array<int,3> A(boost::extents[5][4][3]);

and

     boost::array<multi_array_base::index,3> my_extents = {{5, 4, 3}};
     multi_array<int,3> A(my_extents);

are equivalent.

Modifiers.

multi_array& operator=(const multi_array& x); template <class Array> multi_array& operator=(const Array& x);

This performs an element-wise copy of x into the current multi_array.

Array Requirements. Array must model MultiArray.

Preconditions.

std::equal(this->shape(),this->shape()+this->num_dimensions(),
x.shape());

Postconditions.

(*.this) == x;

Complexity. The assignment operators perform O(x.num_elements()) calls to element's copy constructor.

template <typename InputIterator> void assign(InputIterator begin, InputIterator end);

This copies the elements in the range [begin,end) into the array. It is equivalent to std::copy(begin,end,this->data()).

Preconditions. std::distance(begin,end) == this->num_elements();

Complexity. The assign member function performs O(this->num_elements()) calls to ValueType's copy constructor.

multi_array& resize(extent_gen::gen_type<NumDims>::type extents); template <typename ExtentList> multi_array& resize(const ExtentList& extents);

This function resizes an array to the shape specified by extents, which is either a generated list of extents or a model of the Collection concept. The contents of the array are preserved whenever possible; if the new array size is smaller, then some data will be lost. Any new elements created by resizing the array are initialized with the element default constructor.

Queries.

storage_order_type& storage_order() const;: This query returns the storage order object associated with the multi_array in question. It can be used to construct a new array with the same storage order.

`multi_array_ref`

multi_array_ref is a multi-dimensional container adaptor. It provides the MultiArray interface over any contiguous block of elements. multi_array_ref exports the same interface as multi_array, with the exception of the constructors.

Model Of. multi_array_ref models MultiArray, CopyConstructible. and depending on the element type, it may also model EqualityComparable and LessThanComparable. Detailed descriptions are provided here only for operations that are not described in the multi_array reference.

Synopsis.


namespace boost {

template <typename ValueType, 
          std::size_t NumDims>
class multi_array_ref {
public:
// types:
  typedef ValueType                             element;
  typedef *unspecified*                         value_type;
  typedef *unspecified*                         reference;
  typedef *unspecified*                         const_reference;
  typedef *unspecified*                         difference_type;
  typedef *unspecified*                         iterator;
  typedef *unspecified*                         const_iterator;
  typedef *unspecified*                         reverse_iterator;
  typedef *unspecified*                         const_reverse_iterator;
  typedef multi_array_types::size_type          size_type;
  typedef multi_array_types::index              index;
  typedef multi_array_types::index_gen          index_gen;
  typedef multi_array_types::index_range        index_range;
  typedef multi_array_types::extent_gen         extent_gen;
  typedef multi_array_types::extent_range       extent_range;
  typedef *unspecified*                         storage_order_type;
  
  // template typedefs
  template <std::size_t Dims> struct            subarray;
  template <std::size_t Dims> struct            const_subarray;
  template <std::size_t Dims> struct            array_view;
  template <std::size_t Dims> struct            const_array_view;
  

  static const std::size_t dimensionality = NumDims;


  // constructors and destructors

  template <typename ExtentList>
  explicit multi_array_ref(element* data, const ExtentList& sizes,
                       const storage_order_type& store = c_storage_order());
  explicit multi_array_ref(element* data, const extents_tuple& ranges,
                       const storage_order_type& store = c_storage_order());
  multi_array_ref(const multi_array_ref& x);
  ~multi_array_ref();

  // modifiers

  multi_array_ref& operator=(const multi_array_ref& x);
  template <class Array> multi_array_ref& operator=(const Array& x);

  // iterators:
  iterator				begin();
  iterator				end();
  const_iterator			begin() const;
  const_iterator			end() const;
  reverse_iterator			rbegin();
  reverse_iterator			rend();
  const_reverse_iterator		rbegin() const;
  const_reverse_iterator		rend() const;

  // capacity:
  size_type				size() const;
  size_type				num_elements() const;
  size_type				num_dimensions() const;
 
  // element access:
  template <typename IndexList> 
    element&			operator()(const IndexList& indices);
  template <typename IndexList>
    const element&		operator()(const IndexList& indices) const;
  reference			operator[](index i);
  const_reference		operator[](index i) const;
  array_view<Dims>::type	operator[](const indices_tuple& r);
  const_array_view<Dims>::type	operator[](const indices_tuple& r) const;

  // queries
  element*			data();
  const element*		data() const;
  element*			origin();
  const element*		origin() const;
  const size_type*		shape() const;
  const index*			strides() const;
  const index*			index_bases() const;
  const storage_order_type&     storage_order() const;

  // comparators
  bool operator==(const multi_array_ref& rhs);
  bool operator!=(const multi_array_ref& rhs);
  bool operator<(const multi_array_ref& rhs);
  bool operator>(const multi_array_ref& rhs);
  bool operator>=(const multi_array_ref& rhs);
  bool operator<=(const multi_array_ref& rhs);

  // modifiers:
  template <typename InputIterator>
    void			assign(InputIterator begin, InputIterator end);
  template <typename SizeList>
    void			reshape(const SizeList& sizes)
  template <typename BaseList>	void reindex(const BaseList& values);
  void				reindex(index value);
};

Constructors.

template <typename ExtentList> explicit multi_array_ref(element* data, const ExtentList& sizes, const storage_order& store = c_storage_order(), const Allocator& alloc = Allocator());

This constructs a multi_array_ref using the specified parameters. sizes specifies the shape of the constructed multi_array_ref. store specifies the storage order or layout in memory of the array dimensions. alloc is used to allocate the contained elements.

ExtentList Requirements. ExtentList must model Collection.

Preconditions. sizes.size() == NumDims;

explicit multi_array_ref(element* data, extent_gen::gen_type<NumDims>::type ranges, const storage_order& store = c_storage_order());

This constructs a multi_array_ref using the specified parameters. ranges specifies the shape and index bases of the constructed multi_array_ref. It is the result of NumDims chained calls to extent_gen::operator[]. store specifies the storage order or layout in memory of the array dimensions.

multi_array_ref(const multi_array_ref& x);

This constructs a shallow copy of x.

Complexity. Constant time (for contrast, compare this to the multi_array class copy constructor.

Modifiers.

multi_array_ref& operator=(const multi_array_ref& x); template <class Array> multi_array_ref& operator=(const Array& x);

This performs an element-wise copy of x into the current multi_array_ref.

Array Requirements. Array must model MultiArray.

Preconditions.

std::equal(this->shape(),this->shape()+this->num_dimensions(),
x.shape());

Postconditions.

(*.this) == x;

Complexity. The assignment operators perform O(x.num_elements()) calls to element's copy constructor.

`const_multi_array_ref`

const_multi_array_ref is a multi-dimensional container adaptor. It provides the MultiArray interface over any contiguous block of elements. const_multi_array_ref exports the same interface as multi_array, with the exception of the constructors.

Model Of. const_multi_array_ref models MultiArray, CopyConstructible. and depending on the element type, it may also model EqualityComparable and LessThanComparable. Detailed descriptions are provided here only for operations that are not described in the multi_array reference.

Synopsis.


namespace boost {

template <typename ValueType, 
          std::size_t NumDims, 
          typename TPtr = const T*>
class const_multi_array_ref {
public:
// types:
  typedef ValueType                             element;
  typedef *unspecified*                         value_type;
  typedef *unspecified*                         reference;
  typedef *unspecified*                         const_reference;
  typedef *unspecified*                         difference_type;
  typedef *unspecified*                         iterator;
  typedef *unspecified*                         const_iterator;
  typedef *unspecified*                         reverse_iterator;
  typedef *unspecified*                         const_reverse_iterator;
  typedef multi_array_types::size_type          size_type;
  typedef multi_array_types::index              index;
  typedef multi_array_types::index_gen          index_gen;
  typedef multi_array_types::index_range        index_range;
  typedef multi_array_types::extent_gen         extent_gen;
  typedef multi_array_types::extent_range       extent_range;
  typedef *unspecified*                         storage_order_type;
  
  // template typedefs
  template <std::size_t Dims> struct            subarray;
  template <std::size_t Dims> struct            const_subarray;
  template <std::size_t Dims> struct            array_view;
  template <std::size_t Dims> struct            const_array_view;
  

  // structors

  template <typename ExtentList>
  explicit const_multi_array_ref(TPtr data, const ExtentList& sizes,
                       const storage_order_type& store = c_storage_order());
  explicit const_multi_array_ref(TPtr data, const extents_tuple& ranges,
                       const storage_order_type& store = c_storage_order());
  const_multi_array_ref(const const_multi_array_ref& x);
  ~const_multi_array_ref();



  // iterators:
  const_iterator			begin() const;
  const_iterator			end() const;
  const_reverse_iterator		rbegin() const;
  const_reverse_iterator		rend() const;

  // capacity:
  size_type				size() const;
  size_type				num_elements() const;
  size_type				num_dimensions() const;
 
  // element access:
  template <typename IndexList>
    const element&		operator()(const IndexList& indices) const;
  const_reference		operator[](index i) const;
  const_array_view<Dims>::type	operator[](const indices_tuple& r) const;

  // queries
  const element*		data() const;
  const element*		origin() const;
  const size_type*		shape() const;
  const index*			strides() const;
  const index*			index_bases() const;
  const storage_order_type&     storage_order() const;

  // comparators
  bool operator==(const const_multi_array_ref& rhs);
  bool operator!=(const const_multi_array_ref& rhs);
  bool operator<(const const_multi_array_ref& rhs);
  bool operator>(const const_multi_array_ref& rhs);
  bool operator>=(const const_multi_array_ref& rhs);
  bool operator<=(const const_multi_array_ref& rhs);

  // modifiers:
  template <typename SizeList>
  void			reshape(const SizeList& sizes)
  template <typename BaseList>	void reindex(const BaseList& values);
  void				reindex(index value);
};

Constructors.

template <typename ExtentList> explicit const_multi_array_ref(TPtr data, const ExtentList& sizes, const storage_order& store = c_storage_order());

This constructs a const_multi_array_ref using the specified parameters. sizes specifies the shape of the constructed const_multi_array_ref. store specifies the storage order or layout in memory of the array dimensions.

ExtentList Requirements. ExtentList must model Collection.

Preconditions. sizes.size() == NumDims;

explicit const_multi_array_ref(TPtr data, extent_gen::gen_type<NumDims>::type ranges, const storage_order& store = c_storage_order());

Effects. This constructs a const_multi_array_ref using the specified parameters. ranges specifies the shape and index bases of the constructed const_multi_array_ref. It is the result of NumDims chained calls to extent_gen::operator[]. store specifies the storage order or layout in memory of the array dimensions.

const_multi_array_ref(const const_multi_array_ref& x);

Effects. This constructs a shallow copy of x.

Boost C++ Libraries