1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<head> 4<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 5<title>Array Components</title> 6<link rel="stylesheet" href="../../doc/src/boostbook.css" type="text/css"> 7<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 8<link rel="home" href="index.html" title="The Boost C++ Libraries BoostBook Documentation Subset"> 9<link rel="up" href="multi_array.html" title="Chapter 27. Boost.MultiArray Reference Manual"> 10<link rel="prev" href="MultiArray.html" title="MultiArray Concept"> 11<link rel="next" href="auxiliary.html" title="Auxiliary Components"> 12</head> 13<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 14<table cellpadding="2" width="100%"><tr> 15<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../boost.png"></td> 16<td align="center"><a href="../../index.html">Home</a></td> 17<td align="center"><a href="../../libs/libraries.htm">Libraries</a></td> 18<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> 19<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> 20<td align="center"><a href="../../more/index.htm">More</a></td> 21</tr></table> 22<hr> 23<div class="spirit-nav"> 24<a accesskey="p" href="MultiArray.html"><img src="../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="multi_array.html"><img src="../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="auxiliary.html"><img src="../../doc/src/images/next.png" alt="Next"></a> 25</div> 26<div class="sect1"> 27<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 28<a name="array_types"></a>Array Components</h2></div></div></div> 29<div class="toc"><dl class="toc"> 30<dt><span class="sect2"><a href="array_types.html#multi_array_class"><code class="literal">multi_array</code></a></span></dt> 31<dt><span class="sect2"><a href="array_types.html#multi_array_ref"><code class="literal">multi_array_ref</code></a></span></dt> 32<dt><span class="sect2"><a href="array_types.html#const_multi_array_ref"><code class="literal">const_multi_array_ref</code></a></span></dt> 33</dl></div> 34<p> 35Boost.MultiArray defines an array class, 36<code class="literal">multi_array</code>, and two adapter classes, 37<code class="literal">multi_array_ref</code> and 38<code class="literal">const_multi_array_ref</code>. The three classes model 39MultiArray and so they share a lot of functionality. 40<code class="literal">multi_array_ref</code> differs from 41<code class="literal">multi_array</code> in that the 42<code class="literal">multi_array</code> manages its own memory, while 43<code class="literal">multi_array_ref</code> is passed a block of memory that it 44expects to be externally managed. 45<code class="literal">const_multi_array_ref</code> differs from 46<code class="literal">multi_array_ref</code> in that the underlying elements it 47adapts cannot be modified through its interface, though some array 48properties, including the array shape and index bases, can be altered. 49Functionality the classes have in common is described 50below. 51</p> 52<p><b>Note: Preconditions, Effects, and Implementation. </b> 53Throughout the following sections, small pieces of C++ code are 54used to specify constraints such as preconditions, effects, and 55postconditions. These do not necessarily describe the underlying 56implementation of array components; rather, they describe the 57expected input to and 58behavior of the specified operations. Failure to meet 59preconditions results in undefined behavior. Not all effects 60(i.e. copy constructors, etc.) must be mimicked exactly. The code 61snippets for effects intend to capture the essence of the described 62operation. 63</p> 64<p><b>Queries. </b></p> 65<div class="variablelist"><dl class="variablelist"> 66<dt><span class="term"><pre class="programlisting">element* data(); 67const element* data() const;</pre></span></dt> 68<dd><p>This returns a pointer to the beginning of the 69contiguous block that contains the array's data. If all dimensions of 70the array are 0-indexed and stored in ascending order, this is 71equivalent to <code class="literal">origin()</code>. Note that 72<code class="literal">const_multi_array_ref</code> only provides the const 73version of this function. 74</p></dd> 75<dt><span class="term"><pre class="programlisting">element* origin(); 76const element* origin() const;</pre></span></dt> 77<dd><p>This returns the origin element of the 78<code class="literal">multi_array</code>. Note that 79<code class="literal">const_multi_array_ref</code> only provides the const 80version of this function. (Required by MultiArray) 81</p></dd> 82<dt><span class="term"><code class="function">const index* index_bases();</code></span></dt> 83<dd><p>This returns the index bases for the 84<code class="literal">multi_array</code>. (Required by MultiArray) 85</p></dd> 86<dt><span class="term"><code class="function">const index* strides();</code></span></dt> 87<dd><p>This returns the strides for the 88<code class="literal">multi_array</code>. (Required by MultiArray) 89</p></dd> 90<dt><span class="term"><code class="function">const size_type* shape();</code></span></dt> 91<dd><p>This returns the shape of the 92<code class="literal">multi_array</code>. (Required by MultiArray) 93</p></dd> 94</dl></div> 95<p><b>Comparators. </b></p> 96<div class="variablelist"><dl class="variablelist"> 97<dt><span class="term"><pre class="programlisting"> 98bool operator==(const *array-type*& rhs); 99bool operator!=(const *array-type*& rhs); 100bool operator<(const *array-type*& rhs); 101bool operator>(const *array-type*& rhs); 102bool operator>=(const *array-type*& rhs); 103bool operator<=(const *array-type*& rhs);</pre></span></dt> 104<dd> 105<p>Each comparator executes a lexicographical compare over 106the value types of the two arrays. 107(Required by MultiArray) 108</p> 109<p><b>Preconditions. </b><code class="literal">element</code> must support the 110comparator corresponding to that called on 111<code class="literal">multi_array</code>.</p> 112<p><b>Complexity. </b>O(<code class="literal">num_elements()</code>).</p> 113</dd> 114</dl></div> 115<p><b>Modifiers. </b></p> 116<div class="variablelist"><dl class="variablelist"> 117<dt><span class="term"> 118<pre class="programlisting"> 119 120template <typename SizeList> 121void reshape(const SizeList& sizes) 122 123</pre> 124</span></dt> 125<dd> 126<p>This changes the shape of the <code class="literal">multi_array</code>. The 127number of elements and the index bases remain the same, but the number 128of values at each level of the nested container hierarchy may 129change.</p> 130<p><b><code class="literal">SizeList</code> Requirements. </b><code class="literal">SizeList</code> must model 131<a href="../../utility/Collection.html" target="_top">Collection</a>.</p> 132<p><b>Preconditions. </b> 133</p> 134<pre class="programlisting"> 135std::accumulate(sizes.begin(),sizes.end(),size_type(1),std::times<size_type>()) == this->num_elements(); 136sizes.size() == NumDims; 137</pre> 138<p><b>Postconditions. </b> 139<code class="literal">std::equal(sizes.begin(),sizes.end(),this->shape) == true;</code> 140</p> 141</dd> 142<dt><span class="term"> 143<pre class="programlisting"> 144 145template <typename BaseList> 146void reindex(const BaseList& values); 147 148</pre> 149</span></dt> 150<dd> 151<p>This changes the index bases of the <code class="literal">multi_array</code> to 152correspond to the the values in <code class="literal">values</code>.</p> 153<p><b><code class="literal">BaseList</code> Requirements. </b><code class="literal">BaseList</code> must model 154<a href="../../utility/Collection.html" target="_top">Collection</a>.</p> 155<p><b>Preconditions. </b><code class="literal">values.size() == NumDims;</code></p> 156<p><b>Postconditions. </b><code class="literal">std::equal(values.begin(),values.end(),this->index_bases()); 157</code></p> 158</dd> 159<dt><span class="term"> 160<pre class="programlisting"> 161 162void reindex(index value); 163 164</pre> 165</span></dt> 166<dd> 167<p>This changes the index bases of all dimensions of the 168<code class="literal">multi_array</code> to <code class="literal">value</code>.</p> 169<p><b>Postconditions. </b> 170</p> 171<pre class="programlisting"> 172 173std::count_if(this->index_bases(),this->index_bases()+this->num_dimensions(), 174 std::bind_2nd(std::equal_to<index>(),value)) == 175 this->num_dimensions(); 176 177</pre> 178<p> 179</p> 180</dd> 181</dl></div> 182<div class="sect2"> 183<div class="titlepage"><div><div><h3 class="title"> 184<a name="multi_array_class"></a><code class="literal">multi_array</code> 185</h3></div></div></div> 186<p> 187<code class="literal">multi_array</code> is a multi-dimensional container that 188supports random access iteration. Its number of dimensions is 189fixed at compile time, but its shape and the number of elements it 190contains are specified during its construction. The number of elements 191will remain fixed for the duration of a 192<code class="literal">multi_array</code>'s lifetime, but the shape of the container can 193be changed. A <code class="literal">multi_array</code> manages its data elements 194using a replaceable allocator. 195</p> 196<p><b>Model Of. </b> 197<a class="link" href="MultiArray.html" title="MultiArray Concept">MultiArray</a>, 198<a href="../../../libs/utility/CopyConstructible.html" target="_top">CopyConstructible</a>. Depending on the element type, 199it may also model <a href="https://www.boost.org/sgi/stl/EqualityComparable.html" target="_top">EqualityComparable</a> and <a href="https://www.boost.org/sgi/stl/LessThanComparable.html" target="_top">LessThanComparable</a>. 200</p> 201<p><b>Synopsis. </b></p> 202<pre class="programlisting"> 203 204namespace boost { 205 206template <typename ValueType, 207 std::size_t NumDims, 208 typename Allocator = std::allocator<ValueType> > 209class multi_array { 210public: 211// types: 212 typedef ValueType element; 213 typedef *unspecified* value_type; 214 typedef *unspecified* reference; 215 typedef *unspecified* const_reference; 216 typedef *unspecified* difference_type; 217 typedef *unspecified* iterator; 218 typedef *unspecified* const_iterator; 219 typedef *unspecified* reverse_iterator; 220 typedef *unspecified* const_reverse_iterator; 221 typedef multi_array_types::size_type size_type; 222 typedef multi_array_types::index index; 223 typedef multi_array_types::index_gen index_gen; 224 typedef multi_array_types::index_range index_range; 225 typedef multi_array_types::extent_gen extent_gen; 226 typedef multi_array_types::extent_range extent_range; 227 typedef *unspecified* storage_order_type; 228 229 230 // template typedefs 231 template <std::size_t Dims> struct subarray; 232 template <std::size_t Dims> struct const_subarray; 233 template <std::size_t Dims> struct array_view; 234 template <std::size_t Dims> struct const_array_view; 235 236 237 static const std::size_t dimensionality = NumDims; 238 239 240 // constructors and destructors 241 242 multi_array(const Allocator& alloc = Allocator()); 243 244 template <typename ExtentList> 245 explicit multi_array(const ExtentList& sizes, 246 const storage_order_type& store = c_storage_order(), 247 const Allocator& alloc = Allocator()); 248 explicit multi_array(const extents_tuple& ranges, 249 const storage_order_type& store = c_storage_order(), 250 const Allocator& alloc = Allocator()); 251 multi_array(const multi_array& x); 252 multi_array(const const_multi_array_ref<ValueType,NumDims>& x, 253 const Allocator& alloc = Allocator()); 254 multi_array(const const_subarray<NumDims>::type& x, 255 const Allocator& alloc = Allocator()); 256 multi_array(const const_array_view<NumDims>::type& x, 257 const Allocator& alloc = Allocator()); 258 259 multi_array(const multi_array_ref<ValueType,NumDims>& x, 260 const Allocator& alloc = Allocator()); 261 multi_array(const subarray<NumDims>::type& x, 262 const Allocator& alloc = Allocator()); 263 multi_array(const array_view<NumDims>::type& x, 264 const Allocator& alloc = Allocator()); 265 266 ~multi_array(); 267 268 // modifiers 269 270 multi_array& operator=(const multi_array& x); 271 template <class Array> multi_array& operator=(const Array& x); 272 273 // iterators: 274 iterator begin(); 275 iterator end(); 276 const_iterator begin() const; 277 const_iterator end() const; 278 reverse_iterator rbegin(); 279 reverse_iterator rend(); 280 const_reverse_iterator rbegin() const; 281 const_reverse_iterator rend() const; 282 283 // capacity: 284 size_type size() const; 285 size_type num_elements() const; 286 size_type num_dimensions() const; 287 288 // element access: 289 template <typename IndexList> 290 element& operator()(const IndexList& indices); 291 template <typename IndexList> 292 const element& operator()(const IndexList& indices) const; 293 reference operator[](index i); 294 const_reference operator[](index i) const; 295 array_view<Dims>::type operator[](const indices_tuple& r); 296 const_array_view<Dims>::type operator[](const indices_tuple& r) const; 297 298 // queries 299 element* data(); 300 const element* data() const; 301 element* origin(); 302 const element* origin() const; 303 const size_type* shape() const; 304 const index* strides() const; 305 const index* index_bases() const; 306 const storage_order_type& storage_order() const; 307 308 // comparators 309 bool operator==(const multi_array& rhs); 310 bool operator!=(const multi_array& rhs); 311 bool operator<(const multi_array& rhs); 312 bool operator>(const multi_array& rhs); 313 bool operator>=(const multi_array& rhs); 314 bool operator<=(const multi_array& rhs); 315 316 // modifiers: 317 template <typename InputIterator> 318 void assign(InputIterator begin, InputIterator end); 319 template <typename SizeList> 320 void reshape(const SizeList& sizes) 321 template <typename BaseList> void reindex(const BaseList& values); 322 void reindex(index value); 323 template <typename ExtentList> 324 multi_array& resize(const ExtentList& extents); 325 multi_array& resize(extents_tuple& extents); 326}; 327 328</pre> 329<p><b>Constructors. </b></p> 330<div class="variablelist"><dl class="variablelist"> 331<dt><span class="term"><pre class="programlisting">template <typename ExtentList> 332explicit multi_array(const ExtentList& sizes, 333 const storage_order_type& store = c_storage_order(), 334 const Allocator& alloc = Allocator()); 335</pre></span></dt> 336<dd> 337<p> 338This constructs a <code class="literal">multi_array</code> using the specified 339parameters. <code class="literal">sizes</code> specifies the shape of the 340constructed <code class="literal">multi_array</code>. <code class="literal">store</code> 341specifies the storage order or layout in memory of the array 342dimensions. <code class="literal">alloc</code> is used to 343allocate the contained elements. 344</p> 345<p><b><code class="literal">ExtentList</code> Requirements. </b> 346<code class="literal">ExtentList</code> must model <a href="../../utility/Collection.html" target="_top">Collection</a>. 347</p> 348<p><b>Preconditions. </b><code class="literal">sizes.size() == NumDims;</code></p> 349</dd> 350<dt><span class="term"> 351<pre class="programlisting">explicit multi_array(extent_gen::gen_type<NumDims>::type ranges, 352 const storage_order_type& store = c_storage_order(), 353 const Allocator& alloc = Allocator()); 354</pre></span></dt> 355<dd><p> 356This constructs a <code class="literal">multi_array</code> using the specified 357 parameters. <code class="literal">ranges</code> specifies the shape and 358index bases of the constructed multi_array. It is the result of 359<code class="literal">NumDims</code> chained calls to 360 <code class="literal">extent_gen::operator[]</code>. <code class="literal">store</code> 361specifies the storage order or layout in memory of the array 362dimensions. <code class="literal">alloc</code> is the allocator used to 363allocate the memory used to store <code class="literal">multi_array</code> 364elements. 365</p></dd> 366<dt><span class="term"><pre class="programlisting"> 367multi_array(const multi_array& x); 368multi_array(const const_multi_array_ref<ValueType,NumDims>& x, 369 const Allocator& alloc = Allocator()); 370multi_array(const const_subarray<NumDims>::type& x, 371 const Allocator& alloc = Allocator()); 372multi_array(const const_array_view<NumDims>::type& x, 373 const Allocator& alloc = Allocator()); 374multi_array(const multi_array_ref<ValueType,NumDims>& x, 375 const Allocator& alloc = Allocator()); 376multi_array(const subarray<NumDims>::type& x, 377 const Allocator& alloc = Allocator()); 378multi_array(const array_view<NumDims>::type& x, 379 const Allocator& alloc = Allocator()); 380</pre></span></dt> 381<dd> 382<p>These constructors all constructs a <code class="literal">multi_array</code> and 383perform a deep copy of <code class="literal">x</code>. 384</p> 385<p><b>Complexity. </b> This performs O(<code class="literal">x.num_elements()</code>) calls to 386<code class="literal">element</code>'s copy 387constructor. 388</p> 389</dd> 390<dt><span class="term"><pre class="programlisting"> 391multi_array(); 392</pre></span></dt> 393<dd><p>This constructs a <code class="literal">multi_array</code> whose shape is (0,...,0) and contains no elements. 394</p></dd> 395</dl></div> 396<p><b>Note on Constructors. </b> 397The <code class="literal">multi_array</code> construction expressions, 398</p> 399<pre class="programlisting"> 400 multi_array<int,3> A(boost::extents[5][4][3]); 401</pre> 402<p> 403and 404</p> 405<pre class="programlisting"> 406 boost::array<multi_array_base::index,3> my_extents = {{5, 4, 3}}; 407 multi_array<int,3> A(my_extents); 408</pre> 409<p> 410are equivalent. 411</p> 412<p><b>Modifiers. </b></p> 413<div class="variablelist"><dl class="variablelist"> 414<dt><span class="term"><pre class="programlisting"> 415multi_array& operator=(const multi_array& x); 416template <class Array> multi_array& operator=(const Array& x); 417</pre> 418</span></dt> 419<dd> 420<p>This performs an element-wise copy of <code class="literal">x</code> 421into the current <code class="literal">multi_array</code>.</p> 422<p><b><code class="literal">Array</code> Requirements. </b><code class="literal">Array</code> must model MultiArray. 423</p> 424<p><b>Preconditions. </b> 425</p> 426<pre class="programlisting">std::equal(this->shape(),this->shape()+this->num_dimensions(), 427x.shape());</pre> 428<p><b>Postconditions. </b> 429</p> 430<pre class="programlisting">(*.this) == x;</pre> 431<p> 432</p> 433<p><b>Complexity. </b>The assignment operators perform 434O(<code class="literal">x.num_elements()</code>) calls to <code class="literal">element</code>'s 435copy constructor.</p> 436</dd> 437<dt><span class="term"> 438<pre class="programlisting"> 439 440template <typename InputIterator> 441void assign(InputIterator begin, InputIterator end); 442</pre> 443</span></dt> 444<dd> 445<p>This copies the elements in the range 446<code class="literal">[begin,end)</code> into the array. It is equivalent to 447<code class="literal">std::copy(begin,end,this->data())</code>. 448</p> 449<p><b>Preconditions. </b><code class="literal">std::distance(begin,end) == this->num_elements();</code> 450</p> 451<p><b>Complexity. </b> 452The <code class="literal">assign</code> member function performs 453O(<code class="literal">this->num_elements()</code>) calls to 454<code class="literal">ValueType</code>'s copy constructor. 455</p> 456</dd> 457<dt><span class="term"> 458<pre class="programlisting">multi_array& resize(extent_gen::gen_type<NumDims>::type extents); 459template <typename ExtentList> 460 multi_array& resize(const ExtentList& extents); 461 462</pre></span></dt> 463<dd><p> 464This function resizes an array to the shape specified by 465<code class="literal">extents</code>, which is either a generated list of 466extents or a model of the <code class="literal">Collection</code> concept. The 467contents of the array are preserved whenever possible; if the new 468array size is smaller, then some data will be lost. Any new elements 469created by resizing the array are initialized with the 470<code class="literal">element</code> default constructor. 471</p></dd> 472</dl></div> 473<p><b>Queries. </b></p> 474<div class="variablelist"><dl class="variablelist"> 475<dt><span class="term"><pre class="programlisting"> 476storage_order_type& storage_order() const; 477</pre> 478</span></dt> 479<dd><p>This query returns the storage order object associated with the 480<code class="literal">multi_array</code> in question. It can be used to construct a new array with the same storage order.</p></dd> 481</dl></div> 482</div> 483<div class="sect2"> 484<div class="titlepage"><div><div><h3 class="title"> 485<a name="multi_array_ref"></a><code class="literal">multi_array_ref</code> 486</h3></div></div></div> 487<p> 488<code class="literal">multi_array_ref</code> is a multi-dimensional container 489adaptor. It provides the MultiArray interface over any contiguous 490block of elements. <code class="literal">multi_array_ref</code> exports the 491same interface as <code class="literal">multi_array</code>, with the exception 492of the constructors. 493</p> 494<p><b>Model Of. </b> 495<code class="literal">multi_array_ref</code> models 496<a class="link" href="MultiArray.html" title="MultiArray Concept">MultiArray</a>, 497<a href="../../../libs/utility/CopyConstructible.html" target="_top">CopyConstructible</a>. 498and depending on the element type, it may also model 499<a href="https://www.boost.org/sgi/stl/EqualityComparable.html" target="_top">EqualityComparable</a> and <a href="https://www.boost.org/sgi/stl/LessThanComparable.html" target="_top">LessThanComparable</a>. 500Detailed descriptions are provided here only for operations that are 501not described in the <code class="literal">multi_array</code> reference. 502</p> 503<p><b>Synopsis. </b></p> 504<pre class="programlisting"> 505 506namespace boost { 507 508template <typename ValueType, 509 std::size_t NumDims> 510class multi_array_ref { 511public: 512// types: 513 typedef ValueType element; 514 typedef *unspecified* value_type; 515 typedef *unspecified* reference; 516 typedef *unspecified* const_reference; 517 typedef *unspecified* difference_type; 518 typedef *unspecified* iterator; 519 typedef *unspecified* const_iterator; 520 typedef *unspecified* reverse_iterator; 521 typedef *unspecified* const_reverse_iterator; 522 typedef multi_array_types::size_type size_type; 523 typedef multi_array_types::index index; 524 typedef multi_array_types::index_gen index_gen; 525 typedef multi_array_types::index_range index_range; 526 typedef multi_array_types::extent_gen extent_gen; 527 typedef multi_array_types::extent_range extent_range; 528 typedef *unspecified* storage_order_type; 529 530 // template typedefs 531 template <std::size_t Dims> struct subarray; 532 template <std::size_t Dims> struct const_subarray; 533 template <std::size_t Dims> struct array_view; 534 template <std::size_t Dims> struct const_array_view; 535 536 537 static const std::size_t dimensionality = NumDims; 538 539 540 // constructors and destructors 541 542 template <typename ExtentList> 543 explicit multi_array_ref(element* data, const ExtentList& sizes, 544 const storage_order_type& store = c_storage_order()); 545 explicit multi_array_ref(element* data, const extents_tuple& ranges, 546 const storage_order_type& store = c_storage_order()); 547 multi_array_ref(const multi_array_ref& x); 548 ~multi_array_ref(); 549 550 // modifiers 551 552 multi_array_ref& operator=(const multi_array_ref& x); 553 template <class Array> multi_array_ref& operator=(const Array& x); 554 555 // iterators: 556 iterator begin(); 557 iterator end(); 558 const_iterator begin() const; 559 const_iterator end() const; 560 reverse_iterator rbegin(); 561 reverse_iterator rend(); 562 const_reverse_iterator rbegin() const; 563 const_reverse_iterator rend() const; 564 565 // capacity: 566 size_type size() const; 567 size_type num_elements() const; 568 size_type num_dimensions() const; 569 570 // element access: 571 template <typename IndexList> 572 element& operator()(const IndexList& indices); 573 template <typename IndexList> 574 const element& operator()(const IndexList& indices) const; 575 reference operator[](index i); 576 const_reference operator[](index i) const; 577 array_view<Dims>::type operator[](const indices_tuple& r); 578 const_array_view<Dims>::type operator[](const indices_tuple& r) const; 579 580 // queries 581 element* data(); 582 const element* data() const; 583 element* origin(); 584 const element* origin() const; 585 const size_type* shape() const; 586 const index* strides() const; 587 const index* index_bases() const; 588 const storage_order_type& storage_order() const; 589 590 // comparators 591 bool operator==(const multi_array_ref& rhs); 592 bool operator!=(const multi_array_ref& rhs); 593 bool operator<(const multi_array_ref& rhs); 594 bool operator>(const multi_array_ref& rhs); 595 bool operator>=(const multi_array_ref& rhs); 596 bool operator<=(const multi_array_ref& rhs); 597 598 // modifiers: 599 template <typename InputIterator> 600 void assign(InputIterator begin, InputIterator end); 601 template <typename SizeList> 602 void reshape(const SizeList& sizes) 603 template <typename BaseList> void reindex(const BaseList& values); 604 void reindex(index value); 605}; 606 607</pre> 608<p><b>Constructors. </b></p> 609<div class="variablelist"><dl class="variablelist"> 610<dt><span class="term"><pre class="programlisting">template <typename ExtentList> 611explicit multi_array_ref(element* data, 612 const ExtentList& sizes, 613 const storage_order& store = c_storage_order(), 614 const Allocator& alloc = Allocator()); 615</pre></span></dt> 616<dd> 617<p> 618This constructs a <code class="literal">multi_array_ref</code> using the specified 619parameters. <code class="literal">sizes</code> specifies the shape of the 620constructed <code class="literal">multi_array_ref</code>. <code class="literal">store</code> 621specifies the storage order or layout in memory of the array 622dimensions. <code class="literal">alloc</code> is used to 623allocate the contained elements. 624</p> 625<p><b><code class="literal">ExtentList</code> Requirements. </b> 626<code class="literal">ExtentList</code> must model <a href="../../utility/Collection.html" target="_top">Collection</a>. 627</p> 628<p><b>Preconditions. </b><code class="literal">sizes.size() == NumDims;</code></p> 629</dd> 630<dt><span class="term"> 631<pre class="programlisting">explicit multi_array_ref(element* data, 632 extent_gen::gen_type<NumDims>::type ranges, 633 const storage_order& store = c_storage_order()); 634</pre></span></dt> 635<dd><p> 636This constructs a <code class="literal">multi_array_ref</code> using the specified 637 parameters. <code class="literal">ranges</code> specifies the shape and 638index bases of the constructed multi_array_ref. It is the result of 639<code class="literal">NumDims</code> chained calls to 640 <code class="literal">extent_gen::operator[]</code>. <code class="literal">store</code> 641specifies the storage order or layout in memory of the array 642dimensions. 643</p></dd> 644<dt><span class="term"><pre class="programlisting"> 645multi_array_ref(const multi_array_ref& x); 646</pre></span></dt> 647<dd> 648<p>This constructs a shallow copy of <code class="literal">x</code>. 649</p> 650<p><b>Complexity. </b> Constant time (for contrast, compare this to 651the <code class="literal">multi_array</code> class copy constructor. 652</p> 653</dd> 654</dl></div> 655<p><b>Modifiers. </b></p> 656<div class="variablelist"><dl class="variablelist"> 657<dt><span class="term"><pre class="programlisting"> 658multi_array_ref& operator=(const multi_array_ref& x); 659template <class Array> multi_array_ref& operator=(const Array& x); 660</pre> 661</span></dt> 662<dd> 663<p>This performs an element-wise copy of <code class="literal">x</code> 664into the current <code class="literal">multi_array_ref</code>.</p> 665<p><b><code class="literal">Array</code> Requirements. </b><code class="literal">Array</code> must model MultiArray. 666</p> 667<p><b>Preconditions. </b> 668</p> 669<pre class="programlisting">std::equal(this->shape(),this->shape()+this->num_dimensions(), 670x.shape());</pre> 671<p><b>Postconditions. </b> 672</p> 673<pre class="programlisting">(*.this) == x;</pre> 674<p> 675</p> 676<p><b>Complexity. </b>The assignment operators perform 677O(<code class="literal">x.num_elements()</code>) calls to <code class="literal">element</code>'s 678copy constructor.</p> 679</dd> 680</dl></div> 681</div> 682<div class="sect2"> 683<div class="titlepage"><div><div><h3 class="title"> 684<a name="const_multi_array_ref"></a><code class="literal">const_multi_array_ref</code> 685</h3></div></div></div> 686<p> 687<code class="literal">const_multi_array_ref</code> is a multi-dimensional container 688adaptor. It provides the MultiArray interface over any contiguous 689block of elements. <code class="literal">const_multi_array_ref</code> exports the 690same interface as <code class="literal">multi_array</code>, with the exception 691of the constructors. 692</p> 693<p><b>Model Of. </b> 694<code class="literal">const_multi_array_ref</code> models 695<a class="link" href="MultiArray.html" title="MultiArray Concept">MultiArray</a>, 696<a href="../../../libs/utility/CopyConstructible.html" target="_top">CopyConstructible</a>. 697and depending on the element type, it may also model 698<a href="https://www.boost.org/sgi/stl/EqualityComparable.html" target="_top">EqualityComparable</a> and <a href="https://www.boost.org/sgi/stl/LessThanComparable.html" target="_top">LessThanComparable</a>. 699 700Detailed descriptions are provided here only for operations that are 701not described in the <code class="literal">multi_array</code> reference. 702</p> 703<p><b>Synopsis. </b></p> 704<pre class="programlisting"> 705 706namespace boost { 707 708template <typename ValueType, 709 std::size_t NumDims, 710 typename TPtr = const T*> 711class const_multi_array_ref { 712public: 713// types: 714 typedef ValueType element; 715 typedef *unspecified* value_type; 716 typedef *unspecified* reference; 717 typedef *unspecified* const_reference; 718 typedef *unspecified* difference_type; 719 typedef *unspecified* iterator; 720 typedef *unspecified* const_iterator; 721 typedef *unspecified* reverse_iterator; 722 typedef *unspecified* const_reverse_iterator; 723 typedef multi_array_types::size_type size_type; 724 typedef multi_array_types::index index; 725 typedef multi_array_types::index_gen index_gen; 726 typedef multi_array_types::index_range index_range; 727 typedef multi_array_types::extent_gen extent_gen; 728 typedef multi_array_types::extent_range extent_range; 729 typedef *unspecified* storage_order_type; 730 731 // template typedefs 732 template <std::size_t Dims> struct subarray; 733 template <std::size_t Dims> struct const_subarray; 734 template <std::size_t Dims> struct array_view; 735 template <std::size_t Dims> struct const_array_view; 736 737 738 // structors 739 740 template <typename ExtentList> 741 explicit const_multi_array_ref(TPtr data, const ExtentList& sizes, 742 const storage_order_type& store = c_storage_order()); 743 explicit const_multi_array_ref(TPtr data, const extents_tuple& ranges, 744 const storage_order_type& store = c_storage_order()); 745 const_multi_array_ref(const const_multi_array_ref& x); 746 ~const_multi_array_ref(); 747 748 749 750 // iterators: 751 const_iterator begin() const; 752 const_iterator end() const; 753 const_reverse_iterator rbegin() const; 754 const_reverse_iterator rend() const; 755 756 // capacity: 757 size_type size() const; 758 size_type num_elements() const; 759 size_type num_dimensions() const; 760 761 // element access: 762 template <typename IndexList> 763 const element& operator()(const IndexList& indices) const; 764 const_reference operator[](index i) const; 765 const_array_view<Dims>::type operator[](const indices_tuple& r) const; 766 767 // queries 768 const element* data() const; 769 const element* origin() const; 770 const size_type* shape() const; 771 const index* strides() const; 772 const index* index_bases() const; 773 const storage_order_type& storage_order() const; 774 775 // comparators 776 bool operator==(const const_multi_array_ref& rhs); 777 bool operator!=(const const_multi_array_ref& rhs); 778 bool operator<(const const_multi_array_ref& rhs); 779 bool operator>(const const_multi_array_ref& rhs); 780 bool operator>=(const const_multi_array_ref& rhs); 781 bool operator<=(const const_multi_array_ref& rhs); 782 783 // modifiers: 784 template <typename SizeList> 785 void reshape(const SizeList& sizes) 786 template <typename BaseList> void reindex(const BaseList& values); 787 void reindex(index value); 788}; 789 790</pre> 791<p><b>Constructors. </b></p> 792<div class="variablelist"><dl class="variablelist"> 793<dt><span class="term"><pre class="programlisting">template <typename ExtentList> 794explicit const_multi_array_ref(TPtr data, 795 const ExtentList& sizes, 796 const storage_order& store = c_storage_order()); 797</pre></span></dt> 798<dd> 799<p> 800This constructs a <code class="literal">const_multi_array_ref</code> using the specified 801parameters. <code class="literal">sizes</code> specifies the shape of the 802constructed <code class="literal">const_multi_array_ref</code>. <code class="literal">store</code> 803specifies the storage order or layout in memory of the array 804dimensions. 805</p> 806<p><b><code class="literal">ExtentList</code> Requirements. </b> 807<code class="literal">ExtentList</code> must model <a href="../../utility/Collection.html" target="_top">Collection</a>. 808</p> 809<p><b>Preconditions. </b><code class="literal">sizes.size() == NumDims;</code></p> 810</dd> 811<dt><span class="term"> 812<pre class="programlisting">explicit const_multi_array_ref(TPtr data, 813 extent_gen::gen_type<NumDims>::type ranges, 814 const storage_order& store = c_storage_order()); 815</pre></span></dt> 816<dd><p><b>Effects. </b> 817This constructs a <code class="literal">const_multi_array_ref</code> using the specified 818 parameters. <code class="literal">ranges</code> specifies the shape and 819index bases of the constructed const_multi_array_ref. It is the result of 820<code class="literal">NumDims</code> chained calls to 821 <code class="literal">extent_gen::operator[]</code>. <code class="literal">store</code> 822specifies the storage order or layout in memory of the array 823dimensions. 824</p></dd> 825<dt><span class="term"><pre class="programlisting"> 826const_multi_array_ref(const const_multi_array_ref& x); 827</pre></span></dt> 828<dd><p><b>Effects. </b>This constructs a shallow copy of <code class="literal">x</code>. 829</p></dd> 830</dl></div> 831</div> 832</div> 833<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 834<td align="left"></td> 835<td align="right"><div class="copyright-footer">Copyright © 2002 The Trustees of Indiana University</div></td> 836</tr></table> 837<hr> 838<div class="spirit-nav"> 839<a accesskey="p" href="MultiArray.html"><img src="../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="multi_array.html"><img src="../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="auxiliary.html"><img src="../../doc/src/images/next.png" alt="Next"></a> 840</div> 841</body> 842</html> 843
