# `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.