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>MultiArray Concept</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="multi_array.html" title="Chapter 27. Boost.MultiArray Reference Manual"> 11<link rel="next" href="array_types.html" title="Array 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="multi_array.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="array_types.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="MultiArray"></a>MultiArray Concept</h2></div></div></div> 29<div class="toc"><dl class="toc"> 30<dt><span class="sect2"><a href="MultiArray.html#id-1.3.28.5.8">Notation</a></span></dt> 31<dt><span class="sect2"><a href="MultiArray.html#id-1.3.28.5.9">Associated Types</a></span></dt> 32<dt><span class="sect2"><a href="MultiArray.html#id-1.3.28.5.10">Valid expressions</a></span></dt> 33<dt><span class="sect2"><a href="MultiArray.html#id-1.3.28.5.11">Complexity guarantees</a></span></dt> 34<dt><span class="sect2"><a href="MultiArray.html#id-1.3.28.5.12">Invariants</a></span></dt> 35<dt><span class="sect2"><a href="MultiArray.html#view_types">Associated Types for Views</a></span></dt> 36<dt><span class="sect2"><a href="MultiArray.html#id-1.3.28.5.14">Models</a></span></dt> 37</dl></div> 38<p>The MultiArray 39concept defines an interface to hierarchically nested 40containers. It specifies operations for accessing elements, 41traversing containers, and creating views 42of array data. 43MultiArray defines 44a flexible memory model that accomodates 45a variety of data layouts. 46</p> 47<p> 48At each level (or dimension) of a MultiArray's 49container hierarchy lie a set of ordered containers, each of which 50contains the same number and type of values. The depth of this 51container hierarchy is the MultiArray's <span class="emphasis"><em>dimensionality</em></span>. 52MultiArray is recursively defined; the 53containers at each level of the container hierarchy model 54MultiArray as well. While each dimension of a MultiArray 55has its own size, the list of sizes for all dimensions 56defines the <span class="emphasis"><em>shape</em></span> of the entire MultiArray. 57At the base of this hierarchy lie 1-dimensional 58MultiArrays. Their values are the contained 59objects of interest and not part of the container hierarchy. These are 60the MultiArray's elements. 61</p> 62<p> 63Like other container concepts, MultiArray exports 64iterators to traverse its values. In addition, values can be 65addressed directly using the familiar bracket notation. 66</p> 67<p> 68MultiArray also specifies 69routines for creating 70specialized views. A <span class="emphasis"><em>view</em></span> lets you treat a 71subset of the underlying 72elements in a MultiArray as though it were a separate 73MultiArray. Since a view refers to the same underlying elements, 74changes made to a view's elements will be reflected in the original 75MultiArray. For 76example, given a 3-dimensional "cube" of elements, a 2-dimensional 77slice can be viewed as if it were an independent 78MultiArray. 79 80Views are created using <code class="literal">index_gen</code> and 81<code class="literal">index_range</code> objects. 82<code class="literal">index_range</code>s denote elements from a certain 83dimension that are to be included in a 84view. <code class="literal">index_gen</code> aggregates range data and performs 85bookkeeping to determine the view type to be returned. 86 87MultiArray's <code class="literal">operator[]</code> 88 must be passed the result 89of <code class="literal">N</code> chained calls to 90<code class="literal">index_gen::operator[]</code>, i.e. 91 92</p> 93<pre class="programlisting">indices[a0][a1]...[aN]; 94</pre> 95<p> 96 97where <code class="literal">N</code> is the 98MultiArray's dimensionality and 99<code class="literal">indices</code> an object of type <code class="literal">index_gen</code>. 100 101The view type is dependent upon the number of degenerate dimensions 102specified to <code class="literal">index_gen</code>. A degenerate dimension 103occurs when a single-index is specified to 104<code class="literal">index_gen</code> for a certain dimension. For example, if 105<code class="literal">indices</code> is an object of type 106<code class="literal">index_gen</code>, then the following example: 107 108</p> 109<pre class="programlisting">indices[index_range(0,5)][2][index_range(0,4)]; 110</pre> 111<p> 112 113has a degenerate second dimension. The view generated from the above 114specification will have 2 dimensions with shape <code class="literal">5 x 4</code>. 115If the "<code class="literal">2</code>" above were replaced with 116another <code class="literal">index_range</code> object, for example: 117 118</p> 119<pre class="programlisting">indices[index_range(0,5)][index_range(0,2)][index_range(0,4)]; 120</pre> 121<p> 122 123then the view would have 3 dimensions.</p> 124<p> 125MultiArray exports 126information regarding the memory 127layout of its contained elements. Its memory model for elements is 128completely defined by 4 properties: the origin, shape, index bases, 129and strides. The origin is the address in memory of the element 130accessed as <code class="literal">a[0][0]...[0]</code>, where 131<code class="literal">a</code> is a MultiArray. The shape is a list of numbers 132specifying the size of containers at each dimension. For example, the 133first extent is the size of the outermost container, the second extent 134is the size of its subcontainers, and so on. The index bases are a 135list of signed values specifying the index of the first value in a 136container. All containers at the same dimension share the same index 137base. Note that since positive index bases are 138possible, the origin need not exist in order to determine the location 139in memory of the MultiArray's elements. 140 The strides determine how index values are mapped to memory offsets. 141They accomodate a 142number of possible element layouts. For example, the elements of a 2 143dimensional array can be stored by row (i.e., the elements of each row 144are stored contiguously) or by column (i.e., the elements of each 145column are stored contiguously). 146</p> 147<p> 148Two concept checking classes for the MultiArray concepts 149(<code class="literal">ConstMultiArrayConcept</code> and 150<code class="literal">MutableMultiArrayConcept</code>) are in the namespace 151<code class="literal">boost::multi_array_concepts</code> in 152<code class="literal"><boost/multi_array/concept_checks.hpp></code>. 153</p> 154<div class="sect2"> 155<div class="titlepage"><div><div><h3 class="title"> 156<a name="id-1.3.28.5.8"></a>Notation</h3></div></div></div> 157<p>What follows are the descriptions of symbols that will be used 158to describe the MultiArray interface.</p> 159<div class="table"> 160<a name="id-1.3.28.5.8.3"></a><p class="title"><b>Table 27.1. Notation</b></p> 161<div class="table-contents"><table class="table" summary="Notation"> 162<colgroup> 163<col> 164<col> 165</colgroup> 166<tbody> 167<tr> 168<td><code class="literal">A</code></td> 169<td>A type that is a model of MultiArray 170</td> 171</tr> 172<tr> 173<td><code class="literal">a,b</code></td> 174<td>Objects of type <code class="literal">A</code> 175</td> 176</tr> 177<tr> 178<td><code class="literal">NumDims</code></td> 179<td>The numeric dimension parameter associated with 180<code class="literal">A</code>.</td> 181</tr> 182<tr> 183<td><code class="literal">Dims</code></td> 184<td>Some numeric dimension parameter such that 185<code class="literal">0<Dims<NumDims</code>. 186</td> 187</tr> 188<tr> 189<td><code class="literal">indices</code></td> 190<td>An object created by some number of chained calls 191to <code class="literal">index_gen::operator[](index_range)</code>.</td> 192</tr> 193<tr> 194<td><code class="literal">index_list</code></td> 195<td>An object whose type models 196<a href="../../utility/Collection.html" target="_top">Collection</a> 197</td> 198</tr> 199<tr> 200<td><code class="literal">idx</code></td> 201<td>A signed integral value.</td> 202</tr> 203<tr> 204<td><code class="literal">tmp</code></td> 205<td>An object of type 206 <code class="literal">boost::array<index,NumDims></code> 207</td> 208</tr> 209</tbody> 210</table></div> 211</div> 212<br class="table-break"> 213</div> 214<div class="sect2"> 215<div class="titlepage"><div><div><h3 class="title"> 216<a name="id-1.3.28.5.9"></a>Associated Types</h3></div></div></div> 217<p> 218</p> 219<div class="table"> 220<a name="id-1.3.28.5.9.3"></a><p class="title"><b>Table 27.2. Associated Types</b></p> 221<div class="table-contents"><table class="table" summary="Associated Types"> 222<colgroup> 223<col> 224<col> 225</colgroup> 226<thead><tr> 227<th>Type</th> 228<th>Description</th> 229</tr></thead> 230<tbody> 231<tr> 232<td><code class="literal">value_type</code></td> 233<td>This is the value type of the container. 234 If <code class="literal">NumDims == 1</code>, then this is 235<code class="literal">element</code>. Otherwise, this is the value type of the 236immediately nested containers. 237</td> 238</tr> 239<tr> 240<td> 241<code class="literal">reference</code> 242</td> 243<td> 244This is the reference type of the contained value. 245If <code class="literal">NumDims == 1</code>, then this is 246<code class="literal">element&</code>. Otherwise, this is the same type as 247<code class="literal">template subarray<NumDims-1>::type</code>. 248</td> 249</tr> 250<tr> 251<td> 252<code class="literal">const_reference</code> 253</td> 254<td> 255This is the const reference type of the contained value. 256If <code class="literal">NumDims == 1</code>, then this is 257<code class="literal">const element&</code>. Otherwise, this is the same 258type as 259<code class="literal">template const_subarray<NumDims-1>::type</code>. 260</td> 261</tr> 262<tr> 263<td> 264<code class="literal">size_type</code> 265</td> 266<td> 267This is an unsigned integral type. It is primarily used to specify array shape. 268</td> 269</tr> 270<tr> 271<td> 272<code class="literal">difference_type</code> 273</td> 274<td> 275This is a signed integral type used to represent the distance between two 276iterators. It is the same type as 277<code class="literal">std::iterator_traits<iterator>::difference_type</code>. 278</td> 279</tr> 280<tr> 281<td><code class="literal">iterator</code></td> 282<td> 283This is an iterator over the values of <code class="literal">A</code>. 284If <code class="literal">NumDims == 1</code>, then it models 285<a href="http://www.boost.org/doc/html/RandomAccessIterator.html" target="_top"> 286<code class="literal">Random Access Iterator</code></a>. 287Otherwise it models 288<a href="./iterator_categories.html#concept_RandomAccessTraversalIterator" target="_top"> 289Random Access Traversal Iterator</a>, 290<a href="./iterator_categories.html#concept_ReadableIterator" target="_top"> 291Readable Iterator</a>, 292<a href="./iterator_categories.html#concept_WritableIterator" target="_top"> 293Writable Iterator</a>, and 294<a href="http://www.boost.org/doc/html/OutputIterator.html" target="_top"> 295<code class="literal">Output Iterator</code></a>. 296</td> 297</tr> 298<tr> 299<td> 300<code class="literal">const_iterator</code> 301</td> 302<td> 303This is the const iterator over the values of <code class="literal">A</code>. 304</td> 305</tr> 306<tr> 307<td> 308<code class="literal">reverse_iterator</code> 309</td> 310<td> 311This is the reversed iterator, used to iterate backwards over the values of 312<code class="literal">A</code>. 313</td> 314</tr> 315<tr> 316<td> 317<code class="literal">const_reverse_iterator</code> 318</td> 319<td> 320This is the reversed const iterator. 321<code class="literal">A</code>. 322</td> 323</tr> 324<tr> 325<td> 326<code class="literal">element</code> 327</td> 328<td> 329This is the type of objects stored at the base of the 330hierarchy of MultiArrays. It is the same as 331<code class="literal">template subarray<1>::value_type</code> 332</td> 333</tr> 334<tr> 335<td> 336<code class="literal">index</code> 337</td> 338<td> 339This is a signed integral type used for indexing into <code class="literal">A</code>. It 340is also used to represent strides and index bases. 341</td> 342</tr> 343<tr> 344<td> 345<code class="literal">index_gen</code> 346</td> 347<td> 348This type is used to create a tuple of <code class="literal">index_range</code>s 349passed to <code class="literal">operator[]</code> to create 350an <code class="literal">array_view<Dims>::type</code> object. 351</td> 352</tr> 353<tr> 354<td> 355<code class="literal">index_range</code> 356</td> 357<td> 358This type specifies a range of indices over some dimension of a 359MultiArray. This range will be visible through an 360<code class="literal">array_view<Dims>::type</code> object. 361</td> 362</tr> 363<tr> 364<td> 365<code class="literal">template subarray<Dims>::type</code> 366</td> 367<td> 368This is subarray type with <code class="literal">Dims</code> dimensions. 369It is the reference type of the <code class="literal">(NumDims - Dims)</code> 370dimension of <code class="literal">A</code> and also models 371MultiArray. 372</td> 373</tr> 374<tr> 375<td> 376<code class="literal">template const_subarray<Dims>::type</code> 377</td> 378<td> 379This is the const subarray type. 380</td> 381</tr> 382<tr> 383<td> 384<code class="literal">template array_view<Dims>::type</code> 385</td> 386<td> 387This is the view type with <code class="literal">Dims</code> dimensions. It is 388returned by calling <code class="literal">operator[](<code class="literal">indices</code>)</code>. 389It models MultiArray. 390</td> 391</tr> 392<tr> 393<td> 394<code class="literal">template 395const_array_view<Dims>::type</code> 396</td> 397<td> 398This is the const view type with <code class="literal">Dims</code> dimensions. 399</td> 400</tr> 401</tbody> 402</table></div> 403</div> 404<br class="table-break"> 405</div> 406<div class="sect2"> 407<div class="titlepage"><div><div><h3 class="title"> 408<a name="id-1.3.28.5.10"></a>Valid expressions</h3></div></div></div> 409<div class="table"> 410<a name="id-1.3.28.5.10.2"></a><p class="title"><b>Table 27.3. Valid Expressions</b></p> 411<div class="table-contents"><table class="table" summary="Valid Expressions"> 412<colgroup> 413<col> 414<col> 415<col> 416</colgroup> 417<thead><tr> 418<th>Expression</th> 419<th>Return type</th> 420<th>Semantics</th> 421</tr></thead> 422<tbody> 423<tr> 424<td><code class="literal">A::dimensionality</code></td> 425<td><code class="literal">size_type</code></td> 426<td>This compile-time constant represents the number of 427dimensions of the array (note that 428<code class="literal">A::dimensionality == NumDims</code>).</td> 429</tr> 430<tr> 431<td><code class="literal">a.shape()</code></td> 432<td><code class="literal">const size_type*</code></td> 433<td> 434This returns a list of <code class="literal">NumDims</code> elements specifying the 435extent of each array dimension. 436</td> 437</tr> 438<tr> 439<td><code class="literal">a.strides()</code></td> 440<td><code class="literal">const index*</code></td> 441<td> 442This returns a list of <code class="literal">NumDims</code> elements specifying the 443stride associated with each array dimension. When accessing values, 444strides is used to calculate an element's location in memory. 445</td> 446</tr> 447<tr> 448<td><code class="literal">a.index_bases()</code></td> 449<td><code class="literal">const index*</code></td> 450<td> 451This returns a list of <code class="literal">NumDims</code> elements specifying the 452numeric index of the first element for each array dimension. 453</td> 454</tr> 455<tr> 456<td><code class="literal">a.origin()</code></td> 457<td> 458<code class="literal">element*</code> if <code class="literal">a</code> is mutable, 459<code class="literal">const element*</code> otherwise. 460</td> 461<td> 462This returns the address of the element accessed by the expression 463<code class="literal">a[0][0]...[0].</code>. If the index bases are positive, 464this element won't exist, but the address can still be used to locate 465a valid element given its indices. 466</td> 467</tr> 468<tr> 469<td><code class="literal">a.num_dimensions()</code></td> 470<td><code class="literal">size_type</code></td> 471<td>This returns the number of dimensions of the array 472(note that <code class="literal">a.num_dimensions() == NumDims</code>).</td> 473</tr> 474<tr> 475<td><code class="literal">a.num_elements()</code></td> 476<td><code class="literal">size_type</code></td> 477<td>This returns the number of elements contained 478in the array. It is equivalent to the following code: 479<pre class="programlisting"> 480std::accumulate(a.shape(),a.shape+a.num_dimensions(), 481 size_type(1),std::multiplies<size_type>()); 482</pre> 483</td> 484</tr> 485<tr> 486<td><code class="literal">a.size()</code></td> 487<td><code class="literal">size_type</code></td> 488<td> 489This returns the number of values contained in 490<code class="literal">a</code>. It is equivalent to <code class="literal">a.shape()[0];</code> 491</td> 492</tr> 493<tr> 494<td><code class="literal">a(index_list)</code></td> 495<td> 496<code class="literal">element&</code>; if <code class="literal">a</code> is mutable, 497<code class="literal">const element&</code> otherwise. 498 </td> 499<td> 500This expression accesses a specific element of 501<code class="literal">a</code>.<code class="literal">index_list</code> is the unique set 502of indices that address the element returned. It is 503equivalent to the following code (disregarding intermediate temporaries): 504<pre class="programlisting"> 505 // multiply indices by strides 506 std::transform(index_list.begin(), index_list.end(), 507 a.strides(), tmp.begin(), std::multiplies<index>()), 508 509 // add the sum of the products to the origin 510 *std::accumulate(tmp.begin(), tmp.end(), a.origin()); 511</pre> 512</td> 513</tr> 514<tr> 515<td><code class="literal">a.begin()</code></td> 516<td> 517<code class="literal">iterator</code> if <code class="literal">a</code> is mutable, 518<code class="literal">const_iterator</code> otherwise. 519 </td> 520<td>This returns an iterator pointing to the beginning of 521<code class="literal">a</code>.</td> 522</tr> 523<tr> 524<td><code class="literal">a.end()</code></td> 525<td> 526<code class="literal">iterator</code> if <code class="literal">a</code> is mutable, 527<code class="literal">const_iterator</code> otherwise. 528 </td> 529<td>This returns an iterator pointing to the end of 530<code class="literal">a</code>.</td> 531</tr> 532<tr> 533<td><code class="literal">a.rbegin()</code></td> 534<td> 535<code class="literal">reverse_iterator</code> if <code class="literal">a</code> is mutable, 536<code class="literal">const_reverse_iterator</code> otherwise. 537 </td> 538<td>This returns a reverse iterator pointing to the 539beginning of <code class="literal">a</code> reversed. 540</td> 541</tr> 542<tr> 543<td><code class="literal">a.rend()</code></td> 544<td> 545<code class="literal">reverse_iterator</code> if <code class="literal">a</code> is mutable, 546<code class="literal">const_reverse_iterator</code> otherwise. 547</td> 548<td> 549This returns a reverse iterator pointing to the end of <code class="literal">a</code> 550reversed. 551</td> 552</tr> 553<tr> 554<td><code class="literal">a[idx]</code></td> 555<td> 556<code class="literal">reference</code> if <code class="literal">a</code> is mutable, 557<code class="literal">const_reference</code> otherwise. 558 </td> 559<td> 560This returns a reference type that is bound to the index 561<code class="literal">idx</code> value of <code class="literal">a</code>. Note that if 562<code class="literal">i</code> is the index base for this dimension, the above 563expression returns the <code class="literal">(idx-i)</code>th element (counting 564from zero). The expression is equivalent to 565<code class="literal">*(a.begin()+idx-a.index_bases()[0]);</code>. 566</td> 567</tr> 568<tr> 569<td><code class="literal">a[indices]</code></td> 570<td> 571<code class="literal">array_view<Dims>::type</code> if 572<code class="literal">a</code> is mutable, 573<code class="literal">const_array_view<Dims>::type</code> otherwise. 574 </td> 575<td> 576This expression generates a view of the array determined by the 577<code class="literal">index_range</code> and <code class="literal">index</code> values 578 used to construct <code class="literal">indices</code>. 579</td> 580</tr> 581<tr> 582<td><code class="literal">a == b</code></td> 583<td>bool</td> 584<td>This performs a lexicographical comparison of the 585values of <code class="literal">a</code> and <code class="literal">b</code>. The element 586type must model <a href="https://www.boost.org/sgi/stl/EqualityComparable.html" target="_top">EqualityComparable</a> for this 587expression to be valid.</td> 588</tr> 589<tr> 590<td><code class="literal">a < b</code></td> 591<td>bool</td> 592<td>This performs a lexicographical comparison of the 593values of <code class="literal">a</code> and <code class="literal">b</code>. The element 594type must model <a href="https://www.boost.org/sgi/stl/LessThanComparable.html" target="_top">LessThanComparable</a> for this 595expression to be valid.</td> 596</tr> 597<tr> 598<td><code class="literal">a <= b</code></td> 599<td>bool</td> 600<td>This performs a lexicographical comparison of the 601values of <code class="literal">a</code> and <code class="literal">b</code>. The element 602type must model <a href="https://www.boost.org/sgi/stl/EqualityComparable.html" target="_top">EqualityComparable</a> and 603<a href="https://www.boost.org/sgi/stl/LessThanComparable.html" target="_top">LessThanComparable</a> for this 604expression to be valid.</td> 605</tr> 606<tr> 607<td><code class="literal">a > b</code></td> 608<td>bool</td> 609<td>This performs a lexicographical comparison of the 610values of <code class="literal">a</code> and <code class="literal">b</code>. The element 611type must model <a href="https://www.boost.org/sgi/stl/EqualityComparable.html" target="_top">EqualityComparable</a> and 612<a href="https://www.boost.org/sgi/stl/LessThanComparable.html" target="_top">LessThanComparable</a> for this 613expression to be valid.</td> 614</tr> 615<tr> 616<td><code class="literal">a >= b</code></td> 617<td>bool</td> 618<td>This performs a lexicographical comparison of the 619values of <code class="literal">a</code> and <code class="literal">b</code>. The element 620type must model <a href="https://www.boost.org/sgi/stl/LessThanComparable.html" target="_top">LessThanComparable</a> for this 621expression to be valid.</td> 622</tr> 623</tbody> 624</table></div> 625</div> 626<br class="table-break"> 627</div> 628<div class="sect2"> 629<div class="titlepage"><div><div><h3 class="title"> 630<a name="id-1.3.28.5.11"></a>Complexity guarantees</h3></div></div></div> 631<code class="literal">begin()</code> and <code class="literal">end()</code> execute in amortized 632constant time. 633<code class="literal">size()</code> executes in at most linear time in the 634MultiArray's size. 635</div> 636<div class="sect2"> 637<div class="titlepage"><div><div><h3 class="title"> 638<a name="id-1.3.28.5.12"></a>Invariants</h3></div></div></div> 639<div class="table"> 640<a name="id-1.3.28.5.12.2"></a><p class="title"><b>Table 27.4. Invariants</b></p> 641<div class="table-contents"><table class="table" summary="Invariants"> 642<colgroup> 643<col> 644<col> 645</colgroup> 646<tbody> 647<tr> 648<td>Valid range</td> 649<td> 650<code class="literal">[a.begin(),a.end())</code> is a valid range. 651 </td> 652</tr> 653<tr> 654<td>Range size</td> 655<td> 656<code class="literal">a.size() == std::distance(a.begin(),a.end());</code>. 657</td> 658</tr> 659<tr> 660<td>Completeness</td> 661<td> 662Iteration through the range 663<code class="literal">[a.begin(),a.end())</code> will traverse across every 664<code class="literal">value_type</code> of <code class="literal">a</code>. 665</td> 666</tr> 667<tr> 668<td>Accessor Equivalence</td> 669<td> 670Calling <code class="literal">a[a1][a2]...[aN]</code> where <code class="literal">N==NumDims</code> 671yields the same result as calling 672<code class="literal">a(index_list)</code>, where <code class="literal">index_list</code> 673is a <a href="../../utility/Collection.html" target="_top">Collection</a> containing the values <code class="literal">a1...aN</code>. 674</td> 675</tr> 676</tbody> 677</table></div> 678</div> 679<br class="table-break"> 680</div> 681<div class="sect2"> 682<div class="titlepage"><div><div><h3 class="title"> 683<a name="view_types"></a>Associated Types for Views</h3></div></div></div> 684<div class="toc"><dl class="toc"> 685<dt><span class="sect3"><a href="MultiArray.html#index_range"><code class="literal">index_range</code></a></span></dt> 686<dt><span class="sect3"><a href="MultiArray.html#index_gen"><code class="literal">index_gen</code></a></span></dt> 687</dl></div> 688<p>The following MultiArray associated 689types define the interface for creating views of existing 690MultiArrays. Their interfaces and roles in the 691concept are described below.</p> 692<div class="sect3"> 693<div class="titlepage"><div><div><h4 class="title"> 694<a name="index_range"></a><code class="literal">index_range</code> 695</h4></div></div></div> 696<p><code class="literal">index_range</code> objects represent half-open 697strided intervals. They are aggregated (using an 698<code class="literal">index_gen</code> object) and passed to 699a MultiArray's <code class="literal">operator[]</code> 700to create an array view. When creating a view, 701each <code class="literal">index_range</code> denotes a range of 702valid indices along one dimension of a MultiArray. 703Elements that are accessed through the set of ranges specified will be 704included in the constructed view. In some cases, an 705<code class="literal">index_range</code> is created without specifying start 706or finish values. In those cases, the object is interpreted to 707start at the beginning of a MultiArray dimension 708and end at its end.</p> 709<p> 710<code class="literal">index_range</code> objects can be constructed and modified 711several ways in order to allow convenient and clear expression of a 712range of indices. To specify ranges, <code class="literal">index_range</code> 713supports a set of constructors, mutating member functions, and a novel 714specification involving inequality operators. Using inequality 715operators, a half open range [5,10) can be specified as follows: 716</p> 717<pre class="programlisting">5 <= index_range() < 10;</pre> 718<p> or 719</p> 720<pre class="programlisting">4 < index_range() <= 9;</pre> 721<p> and so on. 722 723The following describes the 724<code class="literal">index_range</code> interface. 725</p> 726<div class="table"> 727<a name="id-1.3.28.5.13.3.4"></a><p class="title"><b>Table 27.5. Notation</b></p> 728<div class="table-contents"><table class="table" summary="Notation"> 729<colgroup> 730<col> 731<col> 732</colgroup> 733<tbody> 734<tr> 735<td><code class="literal">i</code></td> 736<td>An object of type <code class="literal">index_range</code>.</td> 737</tr> 738<tr> 739<td><code class="literal">idx,idx1,idx2,idx3</code></td> 740<td>Objects of type <code class="literal">index</code>.</td> 741</tr> 742</tbody> 743</table></div> 744</div> 745<br class="table-break"><div class="table"> 746<a name="id-1.3.28.5.13.3.5"></a><p class="title"><b>Table 27.6. Associated Types</b></p> 747<div class="table-contents"><table class="table" summary="Associated Types"> 748<colgroup> 749<col> 750<col> 751</colgroup> 752<thead><tr> 753<th>Type</th> 754<th>Description</th> 755</tr></thead> 756<tbody> 757<tr> 758<td><code class="literal">index</code></td> 759<td>This is a signed integral type. It is used to 760specify the start, finish, and stride values.</td> 761</tr> 762<tr> 763<td><code class="literal">size_type</code></td> 764<td>This is an unsigned integral type. It is used to 765report the size of the range an <code class="literal">index_range</code> 766represents.</td> 767</tr> 768</tbody> 769</table></div> 770</div> 771<br class="table-break"><div class="table"> 772<a name="id-1.3.28.5.13.3.6"></a><p class="title"><b>Table 27.7. Valid Expressions</b></p> 773<div class="table-contents"><table class="table" summary="Valid Expressions"> 774<colgroup> 775<col> 776<col> 777<col> 778</colgroup> 779<thead><tr> 780<th>Expression</th> 781<th>Return type</th> 782<th>Semantics</th> 783</tr></thead> 784<tbody> 785<tr> 786<td><code class="literal">index_range(idx1,idx2,idx3)</code></td> 787<td><code class="literal">index_range</code></td> 788<td>This constructs an <code class="literal">index_range</code> 789 representing the interval <code class="literal">[idx1,idx2)</code> 790 with stride <code class="literal">idx3</code>.</td> 791</tr> 792<tr> 793<td><code class="literal">index_range(idx1,idx2)</code></td> 794<td><code class="literal">index_range</code></td> 795<td>This constructs an <code class="literal">index_range</code> 796 representing the interval <code class="literal">[idx1,idx2)</code> 797 with unit stride. It is equivalent to 798 <code class="literal">index_range(idx1,idx2,1)</code>.</td> 799</tr> 800<tr> 801<td><code class="literal">index_range()</code></td> 802<td><code class="literal">index_range</code></td> 803<td>This construct an <code class="literal">index_range</code> 804with unspecified start and finish values.</td> 805</tr> 806<tr> 807<td><code class="literal">i.start(idx1)</code></td> 808<td><code class="literal">index&</code></td> 809<td>This sets the start index of <code class="literal">i</code> to 810 <code class="literal">idx</code>.</td> 811</tr> 812<tr> 813<td><code class="literal">i.finish(idx)</code></td> 814<td><code class="literal">index&</code></td> 815<td>This sets the finish index of <code class="literal">i</code> to 816 <code class="literal">idx</code>.</td> 817</tr> 818<tr> 819<td><code class="literal">i.stride(idx)</code></td> 820<td><code class="literal">index&</code></td> 821<td>This sets the stride length of <code class="literal">i</code> to 822 <code class="literal">idx</code>.</td> 823</tr> 824<tr> 825<td><code class="literal">i.start()</code></td> 826<td><code class="literal">index</code></td> 827<td>This returns the start index of <code class="literal">i</code>.</td> 828</tr> 829<tr> 830<td><code class="literal">i.finish()</code></td> 831<td><code class="literal">index</code></td> 832<td>This returns the finish index of <code class="literal">i</code>.</td> 833</tr> 834<tr> 835<td><code class="literal">i.stride()</code></td> 836<td><code class="literal">index</code></td> 837<td>This returns the stride length of <code class="literal">i</code>.</td> 838</tr> 839<tr> 840<td><code class="literal">i.get_start(idx)</code></td> 841<td><code class="literal">index</code></td> 842<td>If <code class="literal">i</code> specifies a start 843value, this is equivalent to <code class="literal">i.start()</code>. Otherwise it 844returns <code class="literal">idx</code>.</td> 845</tr> 846<tr> 847<td><code class="literal">i.get_finish(idx)</code></td> 848<td><code class="literal">index</code></td> 849<td>If <code class="literal">i</code> specifies a finish 850value, this is equivalent to <code class="literal">i.finish()</code>. Otherwise it 851returns <code class="literal">idx</code>.</td> 852</tr> 853<tr> 854<td><code class="literal">i.size(idx)</code></td> 855<td><code class="literal">size_type</code></td> 856<td>If <code class="literal">i</code> specifies a both finish and 857start values, this is equivalent to 858<code class="literal">(i.finish()-i.start())/i.stride()</code>. Otherwise it 859returns <code class="literal">idx</code>.</td> 860</tr> 861<tr> 862<td><code class="literal">i < idx</code></td> 863<td><code class="literal">index</code></td> 864<td>This is another syntax for specifying the finish 865value. This notation does not include 866<code class="literal">idx</code> in the range of valid indices. It is equivalent to 867<code class="literal">index_range(r.start(), idx, r.stride())</code> 868</td> 869</tr> 870<tr> 871<td><code class="literal">i <= idx</code></td> 872<td><code class="literal">index</code></td> 873<td>This is another syntax for specifying the finish 874value. This notation includes 875<code class="literal">idx</code> in the range of valid indices. It is equivalent to 876<code class="literal">index_range(r.start(), idx + 1, r.stride())</code> 877</td> 878</tr> 879<tr> 880<td><code class="literal">idx < i</code></td> 881<td><code class="literal">index</code></td> 882<td>This is another syntax for specifying the start 883value. This notation does not include 884<code class="literal">idx</code> in the range of valid indices. It is equivalent to 885<code class="literal">index_range(idx + 1, i.finish(), i.stride())</code>.</td> 886</tr> 887<tr> 888<td><code class="literal">idx <= i</code></td> 889<td><code class="literal">index</code></td> 890<td>This is another syntax for specifying the start 891value. This notation includes 892<code class="literal">idx1</code> in the range of valid indices. It is equivalent to 893<code class="literal">index_range(idx, i.finish(), i.stride())</code>.</td> 894</tr> 895<tr> 896<td><code class="literal">i + idx</code></td> 897<td><code class="literal">index</code></td> 898<td>This expression shifts the start and finish values 899of <code class="literal">i</code> up by <code class="literal">idx</code>. It is equivalent to 900<code class="literal">index_range(r.start()+idx1, r.finish()+idx, r.stride())</code> 901</td> 902</tr> 903<tr> 904<td><code class="literal">i - idx</code></td> 905<td><code class="literal">index</code></td> 906<td>This expression shifts the start and finish values 907of <code class="literal">i</code> up by <code class="literal">idx</code>. It is equivalent to 908<code class="literal">index_range(r.start()-idx1, r.finish()-idx, r.stride())</code> 909</td> 910</tr> 911</tbody> 912</table></div> 913</div> 914<br class="table-break"> 915</div> 916<div class="sect3"> 917<div class="titlepage"><div><div><h4 class="title"> 918<a name="index_gen"></a><code class="literal">index_gen</code> 919</h4></div></div></div> 920<p> <code class="literal">index_gen</code> aggregates 921<code class="literal">index_range</code> objects in order to specify view 922parameters. Chained calls to <code class="literal">operator[]</code> store 923range and dimension information used to 924instantiate a new view into a MultiArray. 925</p> 926<div class="table"> 927<a name="id-1.3.28.5.13.4.3"></a><p class="title"><b>Table 27.8. Notation</b></p> 928<div class="table-contents"><table class="table" summary="Notation"> 929<colgroup> 930<col> 931<col> 932</colgroup> 933<tbody> 934<tr> 935<td><code class="literal">Dims,Ranges</code></td> 936<td>Unsigned integral values.</td> 937</tr> 938<tr> 939<td><code class="literal">x</code></td> 940<td>An object of type 941<code class="literal">template gen_type<Dims,Ranges>::type</code>.</td> 942</tr> 943<tr> 944<td><code class="literal">i</code></td> 945<td>An object of type 946<code class="literal">index_range</code>.</td> 947</tr> 948<tr> 949<td><code class="literal">idx</code></td> 950<td>Objects of type <code class="literal">index</code>.</td> 951</tr> 952</tbody> 953</table></div> 954</div> 955<br class="table-break"><div class="table"> 956<a name="id-1.3.28.5.13.4.4"></a><p class="title"><b>Table 27.9. Associated Types</b></p> 957<div class="table-contents"><table class="table" summary="Associated Types"> 958<colgroup> 959<col> 960<col> 961</colgroup> 962<thead><tr> 963<th>Type</th> 964<th>Description</th> 965</tr></thead> 966<tbody> 967<tr> 968<td><code class="literal">index</code></td> 969<td>This is a signed integral type. It is used to 970specify degenerate dimensions.</td> 971</tr> 972<tr> 973<td><code class="literal">size_type</code></td> 974<td>This is an unsigned integral type. It is used to 975report the size of the range an <code class="literal">index_range</code> 976represents.</td> 977</tr> 978<tr> 979<td> 980<code class="literal">template gen_type::<Dims,Ranges>::type</code> 981</td> 982<td>This type generator names the result of 983<code class="literal">Dims</code> chained calls to 984<code class="literal">index_gen::operator[]</code>. The 985<code class="literal">Ranges</code> parameter is determined by the number of 986degenerate ranges specified (i.e. calls to 987<code class="literal">operator[](index)</code>). Note that 988<code class="computeroutput">index_gen</code> and 989<code class="computeroutput">gen_type<0,0>::type</code> are the same type.</td> 990</tr> 991</tbody> 992</table></div> 993</div> 994<br class="table-break"><div class="table"> 995<a name="id-1.3.28.5.13.4.5"></a><p class="title"><b>Table 27.10. Valid Expressions</b></p> 996<div class="table-contents"><table class="table" summary="Valid Expressions"> 997<colgroup> 998<col> 999<col> 1000<col> 1001</colgroup> 1002<thead><tr> 1003<th>Expression</th> 1004<th>Return type</th> 1005<th>Semantics</th> 1006</tr></thead> 1007<tbody> 1008<tr> 1009<td><code class="literal">index_gen()</code></td> 1010<td><code class="literal">gen_type<0,0>::type</code></td> 1011<td>This constructs an <code class="literal">index_gen</code> 1012object. This object can then be used to generate tuples of 1013<code class="literal">index_range</code> values.</td> 1014</tr> 1015<tr> 1016<td><code class="literal">x[i]</code></td> 1017<td> 1018<code class="literal">gen_type<Dims+1,Ranges+1>::type</code> 1019</td> 1020<td>Returns a new object containing all previous 1021<code class="computeroutput">index_range</code> objects in addition to 1022<code class="literal">i.</code> Chained calls to 1023<code class="function">operator[]</code> are the means by which 1024<code class="computeroutput">index_range</code> objects are aggregated.</td> 1025</tr> 1026<tr> 1027<td><code class="literal">x[idx]</code></td> 1028<td> 1029<code class="literal">gen_type<Dims,Ranges+1>::type</code> 1030</td> 1031<td>Returns a new object containing all previous 1032<code class="computeroutput">index_range</code> objects in addition to a degenerate 1033range, <code class="literal">index_range(idx,idx).</code> Note that this is NOT 1034equivalent to <code class="literal">x[index_range(idx,idx)].</code>, which will 1035return an object of type 1036<code class="literal">gen_type<Dims+1,Ranges+1>::type</code>. 1037</td> 1038</tr> 1039</tbody> 1040</table></div> 1041</div> 1042<br class="table-break"> 1043</div> 1044</div> 1045<div class="sect2"> 1046<div class="titlepage"><div><div><h3 class="title"> 1047<a name="id-1.3.28.5.14"></a>Models</h3></div></div></div> 1048<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 1049<li class="listitem"><code class="literal">multi_array</code></li> 1050<li class="listitem"><code class="literal">multi_array_ref</code></li> 1051<li class="listitem"><code class="literal">const_multi_array_ref</code></li> 1052<li class="listitem"><code class="literal">template array_view<Dims>::type</code></li> 1053<li class="listitem"><code class="literal">template const_array_view<Dims>::type</code></li> 1054<li class="listitem"><code class="literal">template subarray<Dims>::type</code></li> 1055<li class="listitem"><code class="literal">template const_subarray<Dims>::type</code></li> 1056</ul></div> 1057</div> 1058</div> 1059<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 1060<td align="left"></td> 1061<td align="right"><div class="copyright-footer">Copyright © 2002 The Trustees of Indiana University</div></td> 1062</tr></table> 1063<hr> 1064<div class="spirit-nav"> 1065<a accesskey="p" href="multi_array.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="array_types.html"><img src="../../doc/src/images/next.png" alt="Next"></a> 1066</div> 1067</body> 1068</html> 1069
