123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387 |
- <sect2 id="multi_array_class">
- <title><literal>multi_array</literal></title>
- <para>
- <literal>multi_array</literal> 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
- <literal>multi_array</literal>'s lifetime, but the shape of the container can
- be changed. A <literal>multi_array</literal> manages its data elements
- using a replaceable allocator.
- </para>
- <formalpara>
- <title>Model Of.</title>
- <para>
- <link linkend="MultiArray">MultiArray</link>,
- <ulink url="../../../libs/utility/CopyConstructible.html">CopyConstructible</ulink>. Depending on the element type,
- it may also model <ulink url="https://www.boost.org/sgi/stl/EqualityComparable.html">EqualityComparable</ulink> and <ulink url="https://www.boost.org/sgi/stl/LessThanComparable.html">LessThanComparable</ulink>.
- </para>
- </formalpara>
- <formalpara>
- <title>Synopsis</title>
- <programlisting>
- <![CDATA[
- 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);
- };
- ]]>
- </programlisting>
- </formalpara>
- <formalpara>
- <title>Constructors</title>
- <variablelist>
- <varlistentry>
- <term><programlisting>template <typename ExtentList>
- explicit multi_array(const ExtentList& sizes,
- const storage_order_type& store = c_storage_order(),
- const Allocator& alloc = Allocator());
- </programlisting></term>
- <listitem>
- <para>
- This constructs a <literal>multi_array</literal> using the specified
- parameters. <literal>sizes</literal> specifies the shape of the
- constructed <literal>multi_array</literal>. <literal>store</literal>
- specifies the storage order or layout in memory of the array
- dimensions. <literal>alloc</literal> is used to
- allocate the contained elements.
- </para>
- <formalpara><title><literal>ExtentList</literal> Requirements</title>
- <para>
- <literal>ExtentList</literal> must model <ulink url="../../utility/Collection.html">Collection</ulink>.
- </para>
- </formalpara>
- <formalpara><title>Preconditions</title>
- <para><literal>sizes.size() == NumDims;</literal></para>
- </formalpara>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <programlisting><![CDATA[explicit multi_array(extent_gen::gen_type<NumDims>::type ranges,
- const storage_order_type& store = c_storage_order(),
- const Allocator& alloc = Allocator());]]>
- </programlisting></term>
- <listitem>
- <para>
- This constructs a <literal>multi_array</literal> using the specified
- parameters. <literal>ranges</literal> specifies the shape and
- index bases of the constructed multi_array. It is the result of
- <literal>NumDims</literal> chained calls to
- <literal>extent_gen::operator[]</literal>. <literal>store</literal>
- specifies the storage order or layout in memory of the array
- dimensions. <literal>alloc</literal> is the allocator used to
- allocate the memory used to store <literal>multi_array</literal>
- elements.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><programlisting>
- <![CDATA[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());]]>
- </programlisting></term>
- <listitem>
- <para>These constructors all constructs a <literal>multi_array</literal> and
- perform a deep copy of <literal>x</literal>.
- </para>
- <formalpara>
- <title>Complexity</title>
- <para> This performs O(<literal>x.num_elements()</literal>) calls to
- <literal>element</literal>'s copy
- constructor.
- </para></formalpara>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><programlisting>
- <![CDATA[multi_array();]]>
- </programlisting></term>
- <listitem>
- <para>This constructs a <literal>multi_array</literal> whose shape is (0,...,0) and contains no elements.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- <formalpara><title>Note on Constructors</title>
- <para>
- The <literal>multi_array</literal> construction expressions,
- <programlisting>
- multi_array<int,3> A(boost::extents[5][4][3]);
- </programlisting>
- and
- <programlisting>
- boost::array<multi_array_base::index,3> my_extents = {{5, 4, 3}};
- multi_array<int,3> A(my_extents);
- </programlisting>
- are equivalent.
- </para>
- </formalpara>
- </formalpara>
- <formalpara>
- <title>Modifiers</title>
- <variablelist>
- <varlistentry>
- <term><programlisting>
- <![CDATA[multi_array& operator=(const multi_array& x);
- template <class Array> multi_array& operator=(const Array& x);]]>
- </programlisting>
- </term>
- <listitem>
- <para>This performs an element-wise copy of <literal>x</literal>
- into the current <literal>multi_array</literal>.</para>
- <formalpara>
- <title><literal>Array</literal> Requirements</title>
- <para><literal>Array</literal> must model MultiArray.
- </para></formalpara>
- <formalpara>
- <title>Preconditions</title>
- <para>
- <programlisting>std::equal(this->shape(),this->shape()+this->num_dimensions(),
- x.shape());</programlisting></para>
- </formalpara>
- <formalpara>
- <title>Postconditions</title>
- <para>
- <programlisting>(*.this) == x;</programlisting>
- </para>
- </formalpara>
- <formalpara>
- <title>Complexity</title>
- <para>The assignment operators perform
- O(<literal>x.num_elements()</literal>) calls to <literal>element</literal>'s
- copy constructor.</para></formalpara>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <programlisting>
- <![CDATA[
- template <typename InputIterator>
- void assign(InputIterator begin, InputIterator end);]]>
- </programlisting>
- </term>
- <listitem>
- <para>This copies the elements in the range
- <literal>[begin,end)</literal> into the array. It is equivalent to
- <literal>std::copy(begin,end,this->data())</literal>.
- </para>
- <formalpara><title>Preconditions</title>
- <para><literal>std::distance(begin,end) == this->num_elements();</literal>
- </para>
- </formalpara>
- <formalpara>
- <title>Complexity</title>
- <para>
- The <literal>assign</literal> member function performs
- O(<literal>this->num_elements()</literal>) calls to
- <literal>ValueType</literal>'s copy constructor.
- </para>
- </formalpara>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <programlisting><![CDATA[multi_array& resize(extent_gen::gen_type<NumDims>::type extents);
- template <typename ExtentList>
- multi_array& resize(const ExtentList& extents);
- ]]>
- </programlisting></term>
- <listitem>
- <para>
- This function resizes an array to the shape specified by
- <literal>extents</literal>, which is either a generated list of
- extents or a model of the <literal>Collection</literal> 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
- <literal>element</literal> default constructor.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </formalpara>
- <formalpara>
- <title>Queries</title>
- <variablelist>
- <varlistentry>
- <term><programlisting>
- <![CDATA[storage_order_type& storage_order() const;]]>
- </programlisting>
- </term>
- <listitem>
- <para>This query returns the storage order object associated with the
- <literal>multi_array</literal> in question. It can be used to construct a new array with the same storage order.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </formalpara>
- </sect2>
|