libs/multi_array/doc/xml/multi_array_ref.xml

   1 <sect2 id="multi_array_ref">
   2 <title><literal>multi_array_ref</literal></title>
   3
   4 <para>
   5 <literal>multi_array_ref</literal> is a multi-dimensional container
   6 adaptor.  It provides the MultiArray interface over any contiguous
   7 block of elements.  <literal>multi_array_ref</literal> exports the
   8 same interface as <literal>multi_array</literal>, with the exception
   9 of the constructors.
  10 </para>
  11
  12
  13 <formalpara>
  14       <title>Model Of.</title>
  15 <para>
  16 <literal>multi_array_ref</literal> models
  17 <link linkend="MultiArray">MultiArray</link>,
  18 <ulink url="../../../libs/utility/CopyConstructible.html">CopyConstructible</ulink>.
  19 and depending on the element type, it may also model
  20 <ulink url="http://www.sgi.com/tech/stl/EqualityComparable.html">EqualityComparable</ulink> and <ulink url="http://www.sgi.com/tech/stl/LessThanComparable.html">LessThanComparable</ulink>.
  21 Detailed descriptions are provided here only for operations that are
  22 not described in the <literal>multi_array</literal> reference.
  23 </para>
  24 </formalpara>
  25
  26 <formalpara>
  27 <title>Synopsis</title>
  28
  29 <programlisting>
  30 <![CDATA[
  31 namespace boost {
  32
  33 template <typename ValueType,
  34           std::size_t NumDims>
  35 class multi_array_ref {
  36 public:
  37 // types:
  38   typedef ValueType                             element;
  39   typedef *unspecified*                         value_type;
  40   typedef *unspecified*                         reference;
  41   typedef *unspecified*                         const_reference;
  42   typedef *unspecified*                         difference_type;
  43   typedef *unspecified*                         iterator;
  44   typedef *unspecified*                         const_iterator;
  45   typedef *unspecified*                         reverse_iterator;
  46   typedef *unspecified*                         const_reverse_iterator;
  47   typedef multi_array_types::size_type          size_type;
  48   typedef multi_array_types::index              index;
  49   typedef multi_array_types::index_gen          index_gen;
  50   typedef multi_array_types::index_range        index_range;
  51   typedef multi_array_types::extent_gen         extent_gen;
  52   typedef multi_array_types::extent_range       extent_range;
  53   typedef *unspecified*                         storage_order_type;
  54
  55   // template typedefs
  56   template <std::size_t Dims> struct            subarray;
  57   template <std::size_t Dims> struct            const_subarray;
  58   template <std::size_t Dims> struct            array_view;
  59   template <std::size_t Dims> struct            const_array_view;
  60
  61
  62   static const std::size_t dimensionality = NumDims;
  63
  64
  65   // constructors and destructors
  66
  67   template <typename ExtentList>
  68   explicit multi_array_ref(element* data, const ExtentList& sizes,
  69                        const storage_order_type& store = c_storage_order());
  70   explicit multi_array_ref(element* data, const extents_tuple& ranges,
  71                        const storage_order_type& store = c_storage_order());
  72   multi_array_ref(const multi_array_ref& x);
  73   ~multi_array_ref();
  74
  75   // modifiers
  76
  77   multi_array_ref& operator=(const multi_array_ref& x);
  78   template <class Array> multi_array_ref& operator=(const Array& x);
  79
  80   // iterators:
  81   iterator                              begin();
  82   iterator                              end();
  83   const_iterator                        begin() const;
  84   const_iterator                        end() const;
  85   reverse_iterator                      rbegin();
  86   reverse_iterator                      rend();
  87   const_reverse_iterator                rbegin() const;
  88   const_reverse_iterator                rend() const;
  89
  90   // capacity:
  91   size_type                             size() const;
  92   size_type                             num_elements() const;
  93   size_type                             num_dimensions() const;
  94
  95   // element access:
  96   template <typename IndexList>
  97     element&                    operator()(const IndexList& indices);
  98   template <typename IndexList>
  99     const element&              operator()(const IndexList& indices) const;
 100   reference                     operator[](index i);
 101   const_reference               operator[](index i) const;
 102   array_view<Dims>::type        operator[](const indices_tuple& r);
 103   const_array_view<Dims>::type  operator[](const indices_tuple& r) const;
 104
 105   // queries
 106   element*                      data();
 107   const element*                data() const;
 108   element*                      origin();
 109   const element*                origin() const;
 110   const size_type*              shape() const;
 111   const index*                  strides() const;
 112   const index*                  index_bases() const;
 113   const storage_order_type&     storage_order() const;
 114
 115   // comparators
 116   bool operator==(const multi_array_ref& rhs);
 117   bool operator!=(const multi_array_ref& rhs);
 118   bool operator<(const multi_array_ref& rhs);
 119   bool operator>(const multi_array_ref& rhs);
 120   bool operator>=(const multi_array_ref& rhs);
 121   bool operator<=(const multi_array_ref& rhs);
 122
 123   // modifiers:
 124   template <typename InputIterator>
 125     void                        assign(InputIterator begin, InputIterator end);
 126   template <typename SizeList>
 127     void                        reshape(const SizeList& sizes)
 128   template <typename BaseList>  void reindex(const BaseList& values);
 129   void                          reindex(index value);
 130 };
 131 ]]>
 132 </programlisting>
 133 </formalpara>
 134
 135 <formalpara>
 136 <title>Constructors</title>
 137
 138 <variablelist>
 139 <varlistentry>
 140 <term><programlisting>template &lt;typename ExtentList&gt;
 141 explicit multi_array_ref(element* data,
 142                      const ExtentList&amp; sizes,
 143                      const storage_order&amp; store = c_storage_order(),
 144                      const Allocator&amp; alloc = Allocator());
 145 </programlisting></term>
 146 <listitem>
 147
 148 <para>
 149 This constructs a <literal>multi_array_ref</literal> using the specified
 150 parameters.  <literal>sizes</literal> specifies the shape of the
 151 constructed <literal>multi_array_ref</literal>.  <literal>store</literal>
 152 specifies the storage order or layout in memory of the array
 153 dimensions.  <literal>alloc</literal> is used to
 154 allocate the contained elements.
 155 </para>
 156
 157 <formalpara><title><literal>ExtentList</literal> Requirements</title>
 158 <para>
 159 <literal>ExtentList</literal> must model <ulink url="../../utility/Collection.html">Collection</ulink>.
 160 </para>
 161 </formalpara>
 162
 163 <formalpara><title>Preconditions</title>
 164 <para><literal>sizes.size() == NumDims;</literal></para>
 165 </formalpara>
 166
 167 </listitem>
 168 </varlistentry>
 169
 170 <varlistentry>
 171 <term>
 172 <programlisting><![CDATA[explicit multi_array_ref(element* data,
 173                      extent_gen::gen_type<NumDims>::type ranges,
 174                      const storage_order& store = c_storage_order());]]>
 175 </programlisting></term>
 176 <listitem>
 177 <para>
 178 This constructs a <literal>multi_array_ref</literal> using the specified
 179     parameters.  <literal>ranges</literal> specifies the shape and
 180 index bases of the constructed multi_array_ref. It is the result of
 181 <literal>NumDims</literal> chained calls to
 182     <literal>extent_gen::operator[]</literal>. <literal>store</literal>
 183 specifies the storage order or layout in memory of the array
 184 dimensions.
 185 </para>
 186 </listitem>
 187 </varlistentry>
 188
 189
 190 <varlistentry>
 191 <term><programlisting>
 192 <![CDATA[multi_array_ref(const multi_array_ref& x);]]>
 193 </programlisting></term>
 194 <listitem>
 195 <para>This constructs a shallow copy of <literal>x</literal>.
 196 </para>
 197
 198 <formalpara>
 199 <title>Complexity</title>
 200 <para> Constant time (for contrast, compare this to
 201 the <literal>multi_array</literal> class copy constructor.
 202 </para></formalpara>
 203 </listitem>
 204 </varlistentry>
 205
 206 </variablelist>
 207
 208 </formalpara>
 209
 210
 211 <formalpara>
 212 <title>Modifiers</title>
 213
 214 <variablelist>
 215 <varlistentry>
 216
 217 <term><programlisting>
 218 <![CDATA[multi_array_ref& operator=(const multi_array_ref& x);
 219 template <class Array> multi_array_ref& operator=(const Array& x);]]>
 220 </programlisting>
 221 </term>
 222
 223 <listitem>
 224 <para>This performs an element-wise copy of <literal>x</literal>
 225 into the current <literal>multi_array_ref</literal>.</para>
 226
 227 <formalpara>
 228 <title><literal>Array</literal> Requirements</title>
 229 <para><literal>Array</literal> must model MultiArray.
 230 </para></formalpara>
 231
 232 <formalpara>
 233 <title>Preconditions</title>
 234 <para>
 235 <programlisting>std::equal(this->shape(),this->shape()+this->num_dimensions(),
 236 x.shape());</programlisting></para>
 237 </formalpara>
 238
 239
 240 <formalpara>
 241 <title>Postconditions</title>
 242 <para>
 243 <programlisting>(*.this) == x;</programlisting>
 244 </para>
 245 </formalpara>
 246
 247 <formalpara>
 248 <title>Complexity</title>
 249 <para>The assignment operators perform
 250 O(<literal>x.num_elements()</literal>) calls to <literal>element</literal>'s
 251 copy constructor.</para></formalpara>
 252 </listitem>
 253 </varlistentry>
 254 </variablelist>
 255
 256 </formalpara>
 257 </sect2>