ceph/src/boost/libs/multi_array/doc/xml/multi_array.xml

   1 <sect2 id="multi_array_class">
   2 <title><literal>multi_array</literal></title>
   3
   4 <para>
   5 <literal>multi_array</literal> is a multi-dimensional container that
   6 supports random access iteration. Its number of dimensions is
   7 fixed at compile time, but its shape and the number of elements it
   8 contains are specified during its construction. The number of elements
   9 will remain fixed for the duration of a
  10 <literal>multi_array</literal>'s lifetime, but the shape of the container can
  11 be changed. A <literal>multi_array</literal> manages its data elements
  12 using a replaceable allocator.
  13 </para>
  14
  15
  16 <formalpara>
  17       <title>Model Of.</title>
  18 <para>
  19 <link linkend="MultiArray">MultiArray</link>,
  20 <ulink url="../../../libs/utility/CopyConstructible.html">CopyConstructible</ulink>. Depending on the element type,
  21 it may also model <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>.
  22 </para>
  23 </formalpara>
  24
  25 <formalpara>
  26 <title>Synopsis</title>
  27
  28 <programlisting>
  29 <![CDATA[
  30 namespace boost {
  31
  32 template <typename ValueType,
  33           std::size_t NumDims,
  34           typename Allocator = std::allocator<ValueType> >
  35 class multi_array {
  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
  56   // template typedefs
  57   template <std::size_t Dims> struct            subarray;
  58   template <std::size_t Dims> struct            const_subarray;
  59   template <std::size_t Dims> struct            array_view;
  60   template <std::size_t Dims> struct            const_array_view;
  61
  62
  63   static const std::size_t dimensionality = NumDims;
  64
  65
  66   // constructors and destructors
  67
  68   multi_array();
  69
  70   template <typename ExtentList>
  71   explicit multi_array(const ExtentList& sizes,
  72                        const storage_order_type& store = c_storage_order(),
  73                        const Allocator& alloc = Allocator());
  74   explicit multi_array(const extents_tuple& ranges,
  75                        const storage_order_type& store = c_storage_order(),
  76                        const Allocator& alloc = Allocator());
  77   multi_array(const multi_array& x);
  78   multi_array(const const_multi_array_ref<ValueType,NumDims>& x);
  79   multi_array(const const_subarray<NumDims>::type& x);
  80   multi_array(const const_array_view<NumDims>::type& x);
  81
  82   multi_array(const multi_array_ref<ValueType,NumDims>& x);
  83   multi_array(const subarray<NumDims>::type& x);
  84   multi_array(const array_view<NumDims>::type& x);
  85
  86   ~multi_array();
  87
  88   // modifiers
  89
  90   multi_array& operator=(const multi_array& x);
  91   template <class Array> multi_array& operator=(const Array& x);
  92
  93   // iterators:
  94   iterator                              begin();
  95   iterator                              end();
  96   const_iterator                        begin() const;
  97   const_iterator                        end() const;
  98   reverse_iterator                      rbegin();
  99   reverse_iterator                      rend();
 100   const_reverse_iterator                rbegin() const;
 101   const_reverse_iterator                rend() const;
 102
 103   // capacity:
 104   size_type                             size() const;
 105   size_type                             num_elements() const;
 106   size_type                             num_dimensions() const;
 107
 108   // element access:
 109   template <typename IndexList>
 110     element&                    operator()(const IndexList& indices);
 111   template <typename IndexList>
 112     const element&              operator()(const IndexList& indices) const;
 113   reference                     operator[](index i);
 114   const_reference               operator[](index i) const;
 115   array_view<Dims>::type        operator[](const indices_tuple& r);
 116   const_array_view<Dims>::type  operator[](const indices_tuple& r) const;
 117
 118   // queries
 119   element*                      data();
 120   const element*                data() const;
 121   element*                      origin();
 122   const element*                origin() const;
 123   const size_type*              shape() const;
 124   const index*                  strides() const;
 125   const index*                  index_bases() const;
 126   const storage_order_type&     storage_order() const;
 127
 128   // comparators
 129   bool operator==(const multi_array& rhs);
 130   bool operator!=(const multi_array& rhs);
 131   bool operator<(const multi_array& rhs);
 132   bool operator>(const multi_array& rhs);
 133   bool operator>=(const multi_array& rhs);
 134   bool operator<=(const multi_array& rhs);
 135
 136   // modifiers:
 137   template <typename InputIterator>
 138     void                        assign(InputIterator begin, InputIterator end);
 139   template <typename SizeList>
 140     void                        reshape(const SizeList& sizes)
 141   template <typename BaseList>  void reindex(const BaseList& values);
 142     void                        reindex(index value);
 143   template <typename ExtentList>
 144     multi_array&                resize(const ExtentList& extents);
 145   multi_array&                  resize(extents_tuple& extents);
 146 };
 147 ]]>
 148 </programlisting>
 149 </formalpara>
 150
 151 <formalpara>
 152 <title>Constructors</title>
 153
 154 <variablelist>
 155 <varlistentry>
 156 <term><programlisting>template &lt;typename ExtentList&gt;
 157 explicit multi_array(const ExtentList&amp; sizes,
 158                      const storage_order_type&amp; store = c_storage_order(),
 159                      const Allocator&amp; alloc = Allocator());
 160 </programlisting></term>
 161 <listitem>
 162
 163 <para>
 164 This constructs a <literal>multi_array</literal> using the specified
 165 parameters.  <literal>sizes</literal> specifies the shape of the
 166 constructed <literal>multi_array</literal>.  <literal>store</literal>
 167 specifies the storage order or layout in memory of the array
 168 dimensions.  <literal>alloc</literal> is used to
 169 allocate the contained elements.
 170 </para>
 171
 172 <formalpara><title><literal>ExtentList</literal> Requirements</title>
 173 <para>
 174 <literal>ExtentList</literal> must model <ulink url="../../utility/Collection.html">Collection</ulink>.
 175 </para>
 176 </formalpara>
 177
 178 <formalpara><title>Preconditions</title>
 179 <para><literal>sizes.size() == NumDims;</literal></para>
 180 </formalpara>
 181
 182 </listitem>
 183 </varlistentry>
 184
 185 <varlistentry>
 186 <term>
 187 <programlisting><![CDATA[explicit multi_array(extent_gen::gen_type<NumDims>::type ranges,
 188                      const storage_order_type& store = c_storage_order(),
 189                      const Allocator& alloc = Allocator());]]>
 190 </programlisting></term>
 191 <listitem>
 192 <para>
 193 This constructs a <literal>multi_array</literal> using the specified
 194     parameters.  <literal>ranges</literal> specifies the shape and
 195 index bases of the constructed multi_array. It is the result of
 196 <literal>NumDims</literal> chained calls to
 197     <literal>extent_gen::operator[]</literal>. <literal>store</literal>
 198 specifies the storage order or layout in memory of the array
 199 dimensions.  <literal>alloc</literal> is the allocator used to
 200 allocate the memory used to store <literal>multi_array</literal>
 201 elements.
 202 </para>
 203 </listitem>
 204 </varlistentry>
 205
 206
 207 <varlistentry>
 208 <term><programlisting>
 209 <![CDATA[multi_array(const multi_array& x);
 210 multi_array(const const_multi_array_ref<ValueType,NumDims>& x);
 211 multi_array(const const_subarray<NumDims>::type& x);
 212 multi_array(const const_array_view<NumDims>::type& x);
 213 multi_array(const multi_array_ref<ValueType,NumDims>& x);
 214 multi_array(const subarray<NumDims>::type& x);
 215 multi_array(const array_view<NumDims>::type& x);]]>
 216 </programlisting></term>
 217 <listitem>
 218 <para>These constructors all constructs a <literal>multi_array</literal> and
 219 perform a deep copy of <literal>x</literal>.
 220 </para>
 221
 222 <formalpara>
 223 <title>Complexity</title>
 224 <para> This performs O(<literal>x.num_elements()</literal>) calls to
 225 <literal>element</literal>'s copy
 226 constructor.
 227 </para></formalpara>
 228 </listitem>
 229 </varlistentry>
 230
 231 <varlistentry>
 232 <term><programlisting>
 233 <![CDATA[multi_array();]]>
 234 </programlisting></term>
 235 <listitem>
 236 <para>This constructs a <literal>multi_array</literal> whose shape is (0,...,0) and contains no elements.
 237 </para>
 238 </listitem>
 239 </varlistentry>
 240
 241 </variablelist>
 242
 243 <formalpara><title>Note on Constructors</title>
 244 <para>
 245 The  <literal>multi_array</literal> construction expressions,
 246 <programlisting>
 247      multi_array&lt;int,3&gt; A(boost::extents[5][4][3]);
 248 </programlisting>
 249 and
 250 <programlisting>
 251      boost::array&lt;multi_array_base::index,3&gt; my_extents = {{5, 4, 3}};
 252      multi_array&lt;int,3&gt; A(my_extents);
 253 </programlisting>
 254 are equivalent.
 255 </para>
 256 </formalpara>
 257 </formalpara>
 258
 259 <formalpara>
 260 <title>Modifiers</title>
 261
 262 <variablelist>
 263
 264 <varlistentry>
 265 <term><programlisting>
 266 <![CDATA[multi_array& operator=(const multi_array& x);
 267 template <class Array> multi_array& operator=(const Array& x);]]>
 268 </programlisting>
 269 </term>
 270
 271 <listitem>
 272 <para>This performs an element-wise copy of <literal>x</literal>
 273 into the current <literal>multi_array</literal>.</para>
 274
 275 <formalpara>
 276 <title><literal>Array</literal> Requirements</title>
 277 <para><literal>Array</literal> must model MultiArray.
 278 </para></formalpara>
 279
 280 <formalpara>
 281 <title>Preconditions</title>
 282 <para>
 283 <programlisting>std::equal(this->shape(),this->shape()+this->num_dimensions(),
 284 x.shape());</programlisting></para>
 285 </formalpara>
 286
 287 <formalpara>
 288 <title>Postconditions</title>
 289 <para>
 290 <programlisting>(*.this) == x;</programlisting>
 291 </para>
 292 </formalpara>
 293
 294 <formalpara>
 295 <title>Complexity</title>
 296 <para>The assignment operators perform
 297 O(<literal>x.num_elements()</literal>) calls to <literal>element</literal>'s
 298 copy constructor.</para></formalpara>
 299 </listitem>
 300 </varlistentry>
 301
 302 <varlistentry>
 303 <term>
 304 <programlisting>
 305 <![CDATA[
 306 template <typename InputIterator>
 307 void assign(InputIterator begin, InputIterator end);]]>
 308 </programlisting>
 309 </term>
 310
 311 <listitem>
 312  <para>This copies the elements in the range
 313 <literal>[begin,end)</literal> into the array.  It is equivalent to
 314 <literal>std::copy(begin,end,this->data())</literal>.
 315 </para>
 316
 317 <formalpara><title>Preconditions</title>
 318 <para><literal>std::distance(begin,end) == this->num_elements();</literal>
 319 </para>
 320 </formalpara>
 321
 322 <formalpara>
 323 <title>Complexity</title>
 324 <para>
 325 The <literal>assign</literal> member function performs
 326 O(<literal>this->num_elements()</literal>) calls to
 327 <literal>ValueType</literal>'s copy constructor.
 328 </para>
 329 </formalpara>
 330 </listitem>
 331 </varlistentry>
 332
 333 <varlistentry>
 334 <term>
 335 <programlisting><![CDATA[multi_array& resize(extent_gen::gen_type<NumDims>::type extents);
 336 template <typename ExtentList>
 337   multi_array& resize(const ExtentList& extents);
 338 ]]>
 339 </programlisting></term>
 340 <listitem>
 341 <para>
 342 This function resizes an array to the shape specified by
 343 <literal>extents</literal>, which is either a generated list of
 344 extents or a model of the <literal>Collection</literal> concept. The
 345 contents of the array are preserved whenever possible; if the new
 346 array size is smaller, then some data will be lost. Any new elements
 347 created by resizing the array are initialized with the
 348 <literal>element</literal> default constructor.
 349 </para>
 350 </listitem>
 351 </varlistentry>
 352
 353 </variablelist>
 354 </formalpara>
 355
 356
 357 <formalpara>
 358 <title>Queries</title>
 359
 360 <variablelist>
 361
 362 <varlistentry>
 363 <term><programlisting>
 364 <![CDATA[storage_order_type& storage_order() const;]]>
 365 </programlisting>
 366 </term>
 367
 368 <listitem>
 369 <para>This query returns the storage order object associated with the
 370 <literal>multi_array</literal> in question.  It can be used to construct a new array with the same storage order.</para>
 371 </listitem>
 372 </varlistentry>
 373 </variablelist>
 374 </formalpara>
 375 </sect2>