| Brian Silverman | 6137817 | 2018-08-04 23:37:59 -0700 | [diff] [blame^] | 1 | <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Boost.MultiArray Reference Manual</title><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article" title="Boost.MultiArray Reference Manual"><div class="titlepage"><div><div><h2 class="title"><a name="idp2304"></a>Boost.MultiArray Reference Manual</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Ronald</span> <span class="surname">Garcia</span></h3><div class="affiliation"><span class="orgname">Indiana University<br></span> <span class="orgdiv">Open Systems Lab<br></span></div></div></div><div><p class="copyright">Copyright © 2002 The Trustees of Indiana University</p></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#synopsis">Library Synopsis</a></span></dt><dt><span class="sect1"><a href="#MultiArray">MultiArray Concept</a></span></dt><dd><dl><dt><span class="sect2"><a href="#idp18427760">Notation</a></span></dt><dt><span class="sect2"><a href="#idp18446208">Associated Types</a></span></dt><dt><span class="sect2"><a href="#idp18501744">Valid expressions</a></span></dt><dt><span class="sect2"><a href="#idp18588736">Complexity guarantees</a></span></dt><dt><span class="sect2"><a href="#idp18591264">Invariants</a></span></dt><dt><span class="sect2"><a href="#view_types">Associated Types for Views</a></span></dt><dt><span class="sect2"><a href="#idp18737792">Models</a></span></dt></dl></dd><dt><span class="sect1"><a href="#array_types">Array Components</a></span></dt><dd><dl><dt><span class="sect2"><a href="#multi_array_class"><code class="literal">multi_array</code></a></span></dt><dt><span class="sect2"><a href="#multi_array_ref"><code class="literal">multi_array_ref</code></a></span></dt><dt><span class="sect2"><a href="#const_multi_array_ref"><code class="literal">const_multi_array_ref</code></a></span></dt></dl></dd><dt><span class="sect1"><a href="#auxiliary">Auxiliary Components</a></span></dt><dd><dl><dt><span class="sect2"><a href="#multi_array_types"><code class="literal">multi_array_types</code></a></span></dt><dt><span class="sect2"><a href="#extent_range"><code class="classname">extent_range</code></a></span></dt><dt><span class="sect2"><a href="#extent_gen"><code class="classname">extent_gen</code></a></span></dt><dt><span class="sect2"><a href="#idp19487120">Global Objects</a></span></dt><dt><span class="sect2"><a href="#generators">View and SubArray Generators</a></span></dt><dt><span class="sect2"><a href="#memory_layout">Memory Layout Specifiers</a></span></dt><dt><span class="sect2"><a href="#range_checking">Range Checking</a></span></dt></dl></dd></dl></div><p>Boost.MultiArray is composed of several components. |
| 2 | The MultiArray concept defines a generic interface to multidimensional |
| 3 | containers. |
| 4 | <code class="literal">multi_array</code> is a general purpose container class |
| 5 | that models MultiArray. <code class="literal">multi_array_ref</code> |
| 6 | and <code class="literal">const_multi_array_ref</code> are adapter |
| 7 | classes. Using them, |
| 8 | you can manipulate any block of contiguous data as though it were a |
| 9 | <code class="literal">multi_array</code>. |
| 10 | <code class="literal">const_multi_array_ref</code> differs from |
| 11 | <code class="literal">multi_array_ref</code> in that its elements cannot |
| 12 | be modified through its interface. Finally, several auxiliary classes are used |
| 13 | to create and specialize arrays and some global objects are defined as |
| 14 | part of the library interface.</p><div class="sect1" title="Library Synopsis"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="synopsis"></a>Library Synopsis</h2></div></div></div><p>To use Boost.MultiArray, you must include the header |
| 15 | <code class="filename">boost/multi_array.hpp</code> in your source. This file |
| 16 | brings the following declarations into scope:</p><pre class="programlisting"> |
| 17 | namespace boost { |
| 18 | |
| 19 | namespace multi_array_types { |
| 20 | typedef *unspecified* index; |
| 21 | typedef *unspecified* size_type; |
| 22 | typedef *unspecified* difference_type; |
| 23 | typedef *unspecified* index_range; |
| 24 | typedef *unspecified* extent_range; |
| 25 | typedef *unspecified* index_gen; |
| 26 | typedef *unspecified* extent_gen; |
| 27 | } |
| 28 | |
| 29 | template <typename ValueType, |
| 30 | std::size_t NumDims, |
| 31 | typename Allocator = std::allocator<ValueType> > |
| 32 | class multi_array; |
| 33 | |
| 34 | template <typename ValueType, |
| 35 | std::size_t NumDims> |
| 36 | class multi_array_ref; |
| 37 | |
| 38 | template <typename ValueType, |
| 39 | std::size_t NumDims> |
| 40 | class const_multi_array_ref; |
| 41 | |
| 42 | multi_array_types::extent_gen extents; |
| 43 | multi_array_types::index_gen indices; |
| 44 | |
| 45 | template <typename Array, int N> class subarray_gen; |
| 46 | template <typename Array, int N> class const_subarray_gen; |
| 47 | template <typename Array, int N> class array_view_gen; |
| 48 | template <typename Array, int N> class const_array_view_gen; |
| 49 | |
| 50 | class c_storage_order; |
| 51 | class fortran_storage_order; |
| 52 | template <std::size_t NumDims> class general_storage_order; |
| 53 | |
| 54 | } |
| 55 | </pre></div><div class="sect1" title="MultiArray Concept"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="MultiArray"></a>MultiArray Concept</h2></div></div></div><p>The MultiArray |
| 56 | concept defines an interface to hierarchically nested |
| 57 | containers. It specifies operations for accessing elements, |
| 58 | traversing containers, and creating views |
| 59 | of array data. |
| 60 | MultiArray defines |
| 61 | a flexible memory model that accomodates |
| 62 | a variety of data layouts. |
| 63 | </p><p> |
| 64 | At each level (or dimension) of a MultiArray's |
| 65 | container hierarchy lie a set of ordered containers, each of which |
| 66 | contains the same number and type of values. The depth of this |
| 67 | container hierarchy is the MultiArray's <span class="emphasis"><em>dimensionality</em></span>. |
| 68 | MultiArray is recursively defined; the |
| 69 | containers at each level of the container hierarchy model |
| 70 | MultiArray as well. While each dimension of a MultiArray |
| 71 | has its own size, the list of sizes for all dimensions |
| 72 | defines the <span class="emphasis"><em>shape</em></span> of the entire MultiArray. |
| 73 | At the base of this hierarchy lie 1-dimensional |
| 74 | MultiArrays. Their values are the contained |
| 75 | objects of interest and not part of the container hierarchy. These are |
| 76 | the MultiArray's elements. |
| 77 | </p><p> |
| 78 | Like other container concepts, MultiArray exports |
| 79 | iterators to traverse its values. In addition, values can be |
| 80 | addressed directly using the familiar bracket notation. |
| 81 | </p><p> |
| 82 | MultiArray also specifies |
| 83 | routines for creating |
| 84 | specialized views. A <span class="emphasis"><em>view</em></span> lets you treat a |
| 85 | subset of the underlying |
| 86 | elements in a MultiArray as though it were a separate |
| 87 | MultiArray. Since a view refers to the same underlying elements, |
| 88 | changes made to a view's elements will be reflected in the original |
| 89 | MultiArray. For |
| 90 | example, given a 3-dimensional "cube" of elements, a 2-dimensional |
| 91 | slice can be viewed as if it were an independent |
| 92 | MultiArray. |
| 93 | |
| 94 | Views are created using <code class="literal">index_gen</code> and |
| 95 | <code class="literal">index_range</code> objects. |
| 96 | <code class="literal">index_range</code>s denote elements from a certain |
| 97 | dimension that are to be included in a |
| 98 | view. <code class="literal">index_gen</code> aggregates range data and performs |
| 99 | bookkeeping to determine the view type to be returned. |
| 100 | |
| 101 | MultiArray's <code class="literal">operator[]</code> |
| 102 | must be passed the result |
| 103 | of <code class="literal">N</code> chained calls to |
| 104 | <code class="literal">index_gen::operator[]</code>, i.e. |
| 105 | |
| 106 | </p><pre class="programlisting">indices[a0][a1]...[aN]; |
| 107 | </pre><p> |
| 108 | |
| 109 | where <code class="literal">N</code> is the |
| 110 | MultiArray's dimensionality and |
| 111 | <code class="literal">indices</code> an object of type <code class="literal">index_gen</code>. |
| 112 | |
| 113 | The view type is dependent upon the number of degenerate dimensions |
| 114 | specified to <code class="literal">index_gen</code>. A degenerate dimension |
| 115 | occurs when a single-index is specified to |
| 116 | <code class="literal">index_gen</code> for a certain dimension. For example, if |
| 117 | <code class="literal">indices</code> is an object of type |
| 118 | <code class="literal">index_gen</code>, then the following example: |
| 119 | |
| 120 | </p><pre class="programlisting">indices[index_range(0,5)][2][index_range(0,4)]; |
| 121 | </pre><p> |
| 122 | |
| 123 | has a degenerate second dimension. The view generated from the above |
| 124 | specification will have 2 dimensions with shape <code class="literal">5 x 4</code>. |
| 125 | If the "<code class="literal">2</code>" above were replaced with |
| 126 | another <code class="literal">index_range</code> object, for example: |
| 127 | |
| 128 | </p><pre class="programlisting">indices[index_range(0,5)][index_range(0,2)][index_range(0,4)]; |
| 129 | </pre><p> |
| 130 | |
| 131 | then the view would have 3 dimensions.</p><p> |
| 132 | MultiArray exports |
| 133 | information regarding the memory |
| 134 | layout of its contained elements. Its memory model for elements is |
| 135 | completely defined by 4 properties: the origin, shape, index bases, |
| 136 | and strides. The origin is the address in memory of the element |
| 137 | accessed as <code class="literal">a[0][0]...[0]</code>, where |
| 138 | <code class="literal">a</code> is a MultiArray. The shape is a list of numbers |
| 139 | specifying the size of containers at each dimension. For example, the |
| 140 | first extent is the size of the outermost container, the second extent |
| 141 | is the size of its subcontainers, and so on. The index bases are a |
| 142 | list of signed values specifying the index of the first value in a |
| 143 | container. All containers at the same dimension share the same index |
| 144 | base. Note that since positive index bases are |
| 145 | possible, the origin need not exist in order to determine the location |
| 146 | in memory of the MultiArray's elements. |
| 147 | The strides determine how index values are mapped to memory offsets. |
| 148 | They accomodate a |
| 149 | number of possible element layouts. For example, the elements of a 2 |
| 150 | dimensional array can be stored by row (i.e., the elements of each row |
| 151 | are stored contiguously) or by column (i.e., the elements of each |
| 152 | column are stored contiguously). |
| 153 | </p><p> |
| 154 | Two concept checking classes for the MultiArray concepts |
| 155 | (<code class="literal">ConstMultiArrayConcept</code> and |
| 156 | <code class="literal">MutableMultiArrayConcept</code>) are in the namespace |
| 157 | <code class="literal">boost::multi_array_concepts</code> in |
| 158 | <code class="literal"><boost/multi_array/concept_checks.hpp></code>. |
| 159 | </p><div class="sect2" title="Notation"><div class="titlepage"><div><div><h3 class="title"><a name="idp18427760"></a>Notation</h3></div></div></div><p>What follows are the descriptions of symbols that will be used |
| 160 | to describe the MultiArray interface.</p><div class="table"><a name="idp18428768"></a><p class="title"><b>Table 1. Notation</b></p><div class="table-contents"><table summary="Notation" border="1"><colgroup><col><col></colgroup><tbody><tr><td><code class="literal">A</code></td><td>A type that is a model of MultiArray |
| 161 | </td></tr><tr><td><code class="literal">a,b</code></td><td>Objects of type <code class="literal">A</code></td></tr><tr><td><code class="literal">NumDims</code></td><td>The numeric dimension parameter associated with |
| 162 | <code class="literal">A</code>.</td></tr><tr><td><code class="literal">Dims</code></td><td>Some numeric dimension parameter such that |
| 163 | <code class="literal">0<Dims<NumDims</code>. |
| 164 | </td></tr><tr><td><code class="literal">indices</code></td><td>An object created by some number of chained calls |
| 165 | to <code class="literal">index_gen::operator[](index_range)</code>.</td></tr><tr><td><code class="literal">index_list</code></td><td>An object whose type models |
| 166 | <a class="ulink" href="../../utility/Collection.html" target="_top">Collection</a> |
| 167 | </td></tr><tr><td><code class="literal">idx</code></td><td>A signed integral value.</td></tr><tr><td><code class="literal">tmp</code></td><td>An object of type |
| 168 | <code class="literal">boost::array<index,NumDims></code></td></tr></tbody></table></div></div><br class="table-break"></div><div class="sect2" title="Associated Types"><div class="titlepage"><div><div><h3 class="title"><a name="idp18446208"></a>Associated Types</h3></div></div></div><p> |
| 169 | </p><div class="table"><a name="idp18447104"></a><p class="title"><b>Table 2. Associated Types</b></p><div class="table-contents"><table summary="Associated Types" border="1"><colgroup><col><col></colgroup><thead><tr><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">value_type</code></td><td>This is the value type of the container. |
| 170 | If <code class="literal">NumDims == 1</code>, then this is |
| 171 | <code class="literal">element</code>. Otherwise, this is the value type of the |
| 172 | immediately nested containers. |
| 173 | </td></tr><tr><td> |
| 174 | <code class="literal">reference</code> |
| 175 | </td><td> |
| 176 | This is the reference type of the contained value. |
| 177 | If <code class="literal">NumDims == 1</code>, then this is |
| 178 | <code class="literal">element&</code>. Otherwise, this is the same type as |
| 179 | <code class="literal">template subarray<NumDims-1>::type</code>. |
| 180 | </td></tr><tr><td> |
| 181 | <code class="literal">const_reference</code> |
| 182 | </td><td> |
| 183 | This is the const reference type of the contained value. |
| 184 | If <code class="literal">NumDims == 1</code>, then this is |
| 185 | <code class="literal">const element&</code>. Otherwise, this is the same |
| 186 | type as |
| 187 | <code class="literal">template const_subarray<NumDims-1>::type</code>. |
| 188 | </td></tr><tr><td> |
| 189 | <code class="literal">size_type</code> |
| 190 | </td><td> |
| 191 | This is an unsigned integral type. It is primarily used to specify array shape. |
| 192 | </td></tr><tr><td> |
| 193 | <code class="literal">difference_type</code> |
| 194 | </td><td> |
| 195 | This is a signed integral type used to represent the distance between two |
| 196 | iterators. It is the same type as |
| 197 | <code class="literal">std::iterator_traits<iterator>::difference_type</code>. |
| 198 | </td></tr><tr><td><code class="literal">iterator</code></td><td> |
| 199 | This is an iterator over the values of <code class="literal">A</code>. |
| 200 | If <code class="literal">NumDims == 1</code>, then it models |
| 201 | <a class="ulink" href="http://www.boost.org/doc/html/RandomAccessIterator.html" target="_top"> |
| 202 | <code class="literal">Random Access Iterator</code></a>. |
| 203 | Otherwise it models |
| 204 | <a class="ulink" href="./iterator_categories.html#concept_RandomAccessTraversalIterator" target="_top"> |
| 205 | Random Access Traversal Iterator</a>, |
| 206 | <a class="ulink" href="./iterator_categories.html#concept_ReadableIterator" target="_top"> |
| 207 | Readable Iterator</a>, |
| 208 | <a class="ulink" href="./iterator_categories.html#concept_WritableIterator" target="_top"> |
| 209 | Writable Iterator</a>, and |
| 210 | <a class="ulink" href="http://www.boost.org/doc/html/OutputIterator.html" target="_top"> |
| 211 | <code class="literal">Output Iterator</code></a>. |
| 212 | </td></tr><tr><td> |
| 213 | <code class="literal">const_iterator</code> |
| 214 | </td><td> |
| 215 | This is the const iterator over the values of <code class="literal">A</code>. |
| 216 | </td></tr><tr><td> |
| 217 | <code class="literal">reverse_iterator</code> |
| 218 | </td><td> |
| 219 | This is the reversed iterator, used to iterate backwards over the values of |
| 220 | <code class="literal">A</code>. |
| 221 | </td></tr><tr><td> |
| 222 | <code class="literal">const_reverse_iterator</code> |
| 223 | </td><td> |
| 224 | This is the reversed const iterator. |
| 225 | <code class="literal">A</code>. |
| 226 | </td></tr><tr><td> |
| 227 | <code class="literal">element</code> |
| 228 | </td><td> |
| 229 | This is the type of objects stored at the base of the |
| 230 | hierarchy of MultiArrays. It is the same as |
| 231 | <code class="literal">template subarray<1>::value_type</code> |
| 232 | </td></tr><tr><td> |
| 233 | <code class="literal">index</code> |
| 234 | </td><td> |
| 235 | This is a signed integral type used for indexing into <code class="literal">A</code>. It |
| 236 | is also used to represent strides and index bases. |
| 237 | </td></tr><tr><td> |
| 238 | <code class="literal">index_gen</code> |
| 239 | </td><td> |
| 240 | This type is used to create a tuple of <code class="literal">index_range</code>s |
| 241 | passed to <code class="literal">operator[]</code> to create |
| 242 | an <code class="literal">array_view<Dims>::type</code> object. |
| 243 | </td></tr><tr><td> |
| 244 | <code class="literal">index_range</code> |
| 245 | </td><td> |
| 246 | This type specifies a range of indices over some dimension of a |
| 247 | MultiArray. This range will be visible through an |
| 248 | <code class="literal">array_view<Dims>::type</code> object. |
| 249 | </td></tr><tr><td> |
| 250 | <code class="literal">template subarray<Dims>::type</code> |
| 251 | </td><td> |
| 252 | This is subarray type with <code class="literal">Dims</code> dimensions. |
| 253 | It is the reference type of the <code class="literal">(NumDims - Dims)</code> |
| 254 | dimension of <code class="literal">A</code> and also models |
| 255 | MultiArray. |
| 256 | </td></tr><tr><td> |
| 257 | <code class="literal">template const_subarray<Dims>::type</code> |
| 258 | </td><td> |
| 259 | This is the const subarray type. |
| 260 | </td></tr><tr><td> |
| 261 | <code class="literal">template array_view<Dims>::type</code> |
| 262 | </td><td> |
| 263 | This is the view type with <code class="literal">Dims</code> dimensions. It is |
| 264 | returned by calling <code class="literal">operator[](<code class="literal">indices</code>)</code>. |
| 265 | It models MultiArray. |
| 266 | </td></tr><tr><td> |
| 267 | <code class="literal">template |
| 268 | const_array_view<Dims>::type</code> |
| 269 | </td><td> |
| 270 | This is the const view type with <code class="literal">Dims</code> dimensions. |
| 271 | </td></tr></tbody></table></div></div><br class="table-break"></div><div class="sect2" title="Valid expressions"><div class="titlepage"><div><div><h3 class="title"><a name="idp18501744"></a>Valid expressions</h3></div></div></div><div class="table"><a name="idp18502256"></a><p class="title"><b>Table 3. Valid Expressions</b></p><div class="table-contents"><table summary="Valid Expressions" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Expression</th><th>Return type</th><th>Semantics</th></tr></thead><tbody><tr><td><code class="literal">A::dimensionality</code></td><td><code class="literal">size_type</code></td><td>This compile-time constant represents the number of |
| 272 | dimensions of the array (note that |
| 273 | <code class="literal">A::dimensionality == NumDims</code>).</td></tr><tr><td><code class="literal">a.shape()</code></td><td><code class="literal">const size_type*</code></td><td> |
| 274 | This returns a list of <code class="literal">NumDims</code> elements specifying the |
| 275 | extent of each array dimension. |
| 276 | </td></tr><tr><td><code class="literal">a.strides()</code></td><td><code class="literal">const index*</code></td><td> |
| 277 | This returns a list of <code class="literal">NumDims</code> elements specifying the |
| 278 | stride associated with each array dimension. When accessing values, |
| 279 | strides is used to calculate an element's location in memory. |
| 280 | </td></tr><tr><td><code class="literal">a.index_bases()</code></td><td><code class="literal">const index*</code></td><td> |
| 281 | This returns a list of <code class="literal">NumDims</code> elements specifying the |
| 282 | numeric index of the first element for each array dimension. |
| 283 | </td></tr><tr><td><code class="literal">a.origin()</code></td><td> |
| 284 | <code class="literal">element*</code> if <code class="literal">a</code> is mutable, |
| 285 | <code class="literal">const element*</code> otherwise. |
| 286 | </td><td> |
| 287 | This returns the address of the element accessed by the expression |
| 288 | <code class="literal">a[0][0]...[0].</code>. If the index bases are positive, |
| 289 | this element won't exist, but the address can still be used to locate |
| 290 | a valid element given its indices. |
| 291 | </td></tr><tr><td><code class="literal">a.num_dimensions()</code></td><td><code class="literal">size_type</code></td><td>This returns the number of dimensions of the array |
| 292 | (note that <code class="literal">a.num_dimensions() == NumDims</code>).</td></tr><tr><td><code class="literal">a.num_elements()</code></td><td><code class="literal">size_type</code></td><td>This returns the number of elements contained |
| 293 | in the array. It is equivalent to the following code: |
| 294 | <pre class="programlisting"> |
| 295 | std::accumulate(a.shape(),a.shape+a.num_dimensions(), |
| 296 | size_type(1),std::multiplies<size_type>()); |
| 297 | </pre> |
| 298 | </td></tr><tr><td><code class="literal">a.size()</code></td><td><code class="literal">size_type</code></td><td> |
| 299 | This returns the number of values contained in |
| 300 | <code class="literal">a</code>. It is equivalent to <code class="literal">a.shape()[0];</code> |
| 301 | </td></tr><tr><td><code class="literal">a(index_list)</code></td><td> |
| 302 | <code class="literal">element&</code>; if <code class="literal">a</code> is mutable, |
| 303 | <code class="literal">const element&</code> otherwise. |
| 304 | </td><td> |
| 305 | This expression accesses a specific element of |
| 306 | <code class="literal">a</code>.<code class="literal">index_list</code> is the unique set |
| 307 | of indices that address the element returned. It is |
| 308 | equivalent to the following code (disregarding intermediate temporaries): |
| 309 | <pre class="programlisting"> |
| 310 | // multiply indices by strides |
| 311 | std::transform(index_list.begin(), index_list.end(), |
| 312 | a.strides(), tmp.begin(), std::multiplies<index>()), |
| 313 | |
| 314 | // add the sum of the products to the origin |
| 315 | *std::accumulate(tmp.begin(), tmp.end(), a.origin()); |
| 316 | </pre> |
| 317 | </td></tr><tr><td><code class="literal">a.begin()</code></td><td> |
| 318 | <code class="literal">iterator</code> if <code class="literal">a</code> is mutable, |
| 319 | <code class="literal">const_iterator</code> otherwise. |
| 320 | </td><td>This returns an iterator pointing to the beginning of |
| 321 | <code class="literal">a</code>.</td></tr><tr><td><code class="literal">a.end()</code></td><td> |
| 322 | <code class="literal">iterator</code> if <code class="literal">a</code> is mutable, |
| 323 | <code class="literal">const_iterator</code> otherwise. |
| 324 | </td><td>This returns an iterator pointing to the end of |
| 325 | <code class="literal">a</code>.</td></tr><tr><td><code class="literal">a.rbegin()</code></td><td> |
| 326 | <code class="literal">reverse_iterator</code> if <code class="literal">a</code> is mutable, |
| 327 | <code class="literal">const_reverse_iterator</code> otherwise. |
| 328 | </td><td>This returns a reverse iterator pointing to the |
| 329 | beginning of <code class="literal">a</code> reversed. |
| 330 | </td></tr><tr><td><code class="literal">a.rend()</code></td><td> |
| 331 | <code class="literal">reverse_iterator</code> if <code class="literal">a</code> is mutable, |
| 332 | <code class="literal">const_reverse_iterator</code> otherwise. |
| 333 | </td><td> |
| 334 | This returns a reverse iterator pointing to the end of <code class="literal">a</code> |
| 335 | reversed. |
| 336 | </td></tr><tr><td><code class="literal">a[idx]</code></td><td> |
| 337 | <code class="literal">reference</code> if <code class="literal">a</code> is mutable, |
| 338 | <code class="literal">const_reference</code> otherwise. |
| 339 | </td><td> |
| 340 | This returns a reference type that is bound to the index |
| 341 | <code class="literal">idx</code> value of <code class="literal">a</code>. Note that if |
| 342 | <code class="literal">i</code> is the index base for this dimension, the above |
| 343 | expression returns the <code class="literal">(idx-i)</code>th element (counting |
| 344 | from zero). The expression is equivalent to |
| 345 | <code class="literal">*(a.begin()+idx-a.index_bases()[0]);</code>. |
| 346 | </td></tr><tr><td><code class="literal">a[indices]</code></td><td> |
| 347 | <code class="literal">array_view<Dims>::type</code> if |
| 348 | <code class="literal">a</code> is mutable, |
| 349 | <code class="literal">const_array_view<Dims>::type</code> otherwise. |
| 350 | </td><td> |
| 351 | This expression generates a view of the array determined by the |
| 352 | <code class="literal">index_range</code> and <code class="literal">index</code> values |
| 353 | used to construct <code class="literal">indices</code>. |
| 354 | </td></tr><tr><td><code class="literal">a == b</code></td><td>bool</td><td>This performs a lexicographical comparison of the |
| 355 | values of <code class="literal">a</code> and <code class="literal">b</code>. The element |
| 356 | type must model <a class="ulink" href="http://www.sgi.com/tech/stl/EqualityComparable.html" target="_top">EqualityComparable</a> for this |
| 357 | expression to be valid.</td></tr><tr><td><code class="literal">a < b</code></td><td>bool</td><td>This performs a lexicographical comparison of the |
| 358 | values of <code class="literal">a</code> and <code class="literal">b</code>. The element |
| 359 | type must model <a class="ulink" href="http://www.sgi.com/tech/stl/LessThanComparable.html" target="_top">LessThanComparable</a> for this |
| 360 | expression to be valid.</td></tr><tr><td><code class="literal">a <= b</code></td><td>bool</td><td>This performs a lexicographical comparison of the |
| 361 | values of <code class="literal">a</code> and <code class="literal">b</code>. The element |
| 362 | type must model <a class="ulink" href="http://www.sgi.com/tech/stl/EqualityComparable.html" target="_top">EqualityComparable</a> and |
| 363 | <a class="ulink" href="http://www.sgi.com/tech/stl/LessThanComparable.html" target="_top">LessThanComparable</a> for this |
| 364 | expression to be valid.</td></tr><tr><td><code class="literal">a > b</code></td><td>bool</td><td>This performs a lexicographical comparison of the |
| 365 | values of <code class="literal">a</code> and <code class="literal">b</code>. The element |
| 366 | type must model <a class="ulink" href="http://www.sgi.com/tech/stl/EqualityComparable.html" target="_top">EqualityComparable</a> and |
| 367 | <a class="ulink" href="http://www.sgi.com/tech/stl/LessThanComparable.html" target="_top">LessThanComparable</a> for this |
| 368 | expression to be valid.</td></tr><tr><td><code class="literal">a >= b</code></td><td>bool</td><td>This performs a lexicographical comparison of the |
| 369 | values of <code class="literal">a</code> and <code class="literal">b</code>. The element |
| 370 | type must model <a class="ulink" href="http://www.sgi.com/tech/stl/LessThanComparable.html" target="_top">LessThanComparable</a> for this |
| 371 | expression to be valid.</td></tr></tbody></table></div></div><br class="table-break"></div><div class="sect2" title="Complexity guarantees"><div class="titlepage"><div><div><h3 class="title"><a name="idp18588736"></a>Complexity guarantees</h3></div></div></div><code class="literal">begin()</code> and <code class="literal">end()</code> execute in amortized |
| 372 | constant time. |
| 373 | <code class="literal">size()</code> executes in at most linear time in the |
| 374 | MultiArray's size. |
| 375 | </div><div class="sect2" title="Invariants"><div class="titlepage"><div><div><h3 class="title"><a name="idp18591264"></a>Invariants</h3></div></div></div><div class="table"><a name="idp18591904"></a><p class="title"><b>Table 4. Invariants</b></p><div class="table-contents"><table summary="Invariants" border="1"><colgroup><col><col></colgroup><tbody><tr><td>Valid range</td><td><code class="literal">[a.begin(),a.end())</code> is a valid range. |
| 376 | </td></tr><tr><td>Range size</td><td> |
| 377 | <code class="literal">a.size() == std::distance(a.begin(),a.end());</code>. |
| 378 | </td></tr><tr><td>Completeness</td><td> |
| 379 | Iteration through the range |
| 380 | <code class="literal">[a.begin(),a.end())</code> will traverse across every |
| 381 | <code class="literal">value_type</code> of <code class="literal">a</code>. |
| 382 | </td></tr><tr><td>Accessor Equivalence</td><td> |
| 383 | Calling <code class="literal">a[a1][a2]...[aN]</code> where <code class="literal">N==NumDims</code> |
| 384 | yields the same result as calling |
| 385 | <code class="literal">a(index_list)</code>, where <code class="literal">index_list</code> |
| 386 | is a <a class="ulink" href="../../utility/Collection.html" target="_top">Collection</a> containing the values <code class="literal">a1...aN</code>. |
| 387 | </td></tr></tbody></table></div></div><br class="table-break"></div><div class="sect2" title="Associated Types for Views"><div class="titlepage"><div><div><h3 class="title"><a name="view_types"></a>Associated Types for Views</h3></div></div></div><p>The following MultiArray associated |
| 388 | types define the interface for creating views of existing |
| 389 | MultiArrays. Their interfaces and roles in the |
| 390 | concept are described below.</p><div class="sect3" title="index_range"><div class="titlepage"><div><div><h4 class="title"><a name="index_range"></a><code class="literal">index_range</code></h4></div></div></div><p><code class="literal">index_range</code> objects represent half-open |
| 391 | strided intervals. They are aggregated (using an |
| 392 | <code class="literal">index_gen</code> object) and passed to |
| 393 | a MultiArray's <code class="literal">operator[]</code> |
| 394 | to create an array view. When creating a view, |
| 395 | each <code class="literal">index_range</code> denotes a range of |
| 396 | valid indices along one dimension of a MultiArray. |
| 397 | Elements that are accessed through the set of ranges specified will be |
| 398 | included in the constructed view. In some cases, an |
| 399 | <code class="literal">index_range</code> is created without specifying start |
| 400 | or finish values. In those cases, the object is interpreted to |
| 401 | start at the beginning of a MultiArray dimension |
| 402 | and end at its end.</p><p> |
| 403 | <code class="literal">index_range</code> objects can be constructed and modified |
| 404 | several ways in order to allow convenient and clear expression of a |
| 405 | range of indices. To specify ranges, <code class="literal">index_range</code> |
| 406 | supports a set of constructors, mutating member functions, and a novel |
| 407 | specification involving inequality operators. Using inequality |
| 408 | operators, a half open range [5,10) can be specified as follows: |
| 409 | </p><pre class="programlisting">5 <= index_range() < 10;</pre><p> or |
| 410 | </p><pre class="programlisting">4 < index_range() <= 9;</pre><p> and so on. |
| 411 | |
| 412 | The following describes the |
| 413 | <code class="literal">index_range</code> interface. |
| 414 | </p><div class="table"><a name="idp18614960"></a><p class="title"><b>Table 5. Notation</b></p><div class="table-contents"><table summary="Notation" border="1"><colgroup><col><col></colgroup><tbody><tr><td><code class="literal">i</code></td><td>An object of type <code class="literal">index_range</code>.</td></tr><tr><td><code class="literal">idx,idx1,idx2,idx3</code></td><td>Objects of type <code class="literal">index</code>.</td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="idp18620944"></a><p class="title"><b>Table 6. Associated Types</b></p><div class="table-contents"><table summary="Associated Types" border="1"><colgroup><col><col></colgroup><thead><tr><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">index</code></td><td>This is a signed integral type. It is used to |
| 415 | specify the start, finish, and stride values.</td></tr><tr><td><code class="literal">size_type</code></td><td>This is an unsigned integral type. It is used to |
| 416 | report the size of the range an <code class="literal">index_range</code> |
| 417 | represents.</td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="idp18627920"></a><p class="title"><b>Table 7. Valid Expressions</b></p><div class="table-contents"><table summary="Valid Expressions" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Expression</th><th>Return type</th><th>Semantics</th></tr></thead><tbody><tr><td><code class="literal">index_range(idx1,idx2,idx3)</code></td><td><code class="literal">index_range</code></td><td>This constructs an <code class="literal">index_range</code> |
| 418 | representing the interval <code class="literal">[idx1,idx2)</code> |
| 419 | with stride <code class="literal">idx3</code>.</td></tr><tr><td><code class="literal">index_range(idx1,idx2)</code></td><td><code class="literal">index_range</code></td><td>This constructs an <code class="literal">index_range</code> |
| 420 | representing the interval <code class="literal">[idx1,idx2)</code> |
| 421 | with unit stride. It is equivalent to |
| 422 | <code class="literal">index_range(idx1,idx2,1)</code>.</td></tr><tr><td><code class="literal">index_range()</code></td><td><code class="literal">index_range</code></td><td>This construct an <code class="literal">index_range</code> |
| 423 | with unspecified start and finish values.</td></tr><tr><td><code class="literal">i.start(idx1)</code></td><td><code class="literal">index&</code></td><td>This sets the start index of <code class="literal">i</code> to |
| 424 | <code class="literal">idx</code>.</td></tr><tr><td><code class="literal">i.finish(idx)</code></td><td><code class="literal">index&</code></td><td>This sets the finish index of <code class="literal">i</code> to |
| 425 | <code class="literal">idx</code>.</td></tr><tr><td><code class="literal">i.stride(idx)</code></td><td><code class="literal">index&</code></td><td>This sets the stride length of <code class="literal">i</code> to |
| 426 | <code class="literal">idx</code>.</td></tr><tr><td><code class="literal">i.start()</code></td><td><code class="literal">index</code></td><td>This returns the start index of <code class="literal">i</code>.</td></tr><tr><td><code class="literal">i.finish()</code></td><td><code class="literal">index</code></td><td>This returns the finish index of <code class="literal">i</code>.</td></tr><tr><td><code class="literal">i.stride()</code></td><td><code class="literal">index</code></td><td>This returns the stride length of <code class="literal">i</code>.</td></tr><tr><td><code class="literal">i.get_start(idx)</code></td><td><code class="literal">index</code></td><td>If <code class="literal">i</code> specifies a start |
| 427 | value, this is equivalent to <code class="literal">i.start()</code>. Otherwise it |
| 428 | returns <code class="literal">idx</code>.</td></tr><tr><td><code class="literal">i.get_finish(idx)</code></td><td><code class="literal">index</code></td><td>If <code class="literal">i</code> specifies a finish |
| 429 | value, this is equivalent to <code class="literal">i.finish()</code>. Otherwise it |
| 430 | returns <code class="literal">idx</code>.</td></tr><tr><td><code class="literal">i.size(idx)</code></td><td><code class="literal">size_type</code></td><td>If <code class="literal">i</code> specifies a both finish and |
| 431 | start values, this is equivalent to |
| 432 | <code class="literal">(i.finish()-i.start())/i.stride()</code>. Otherwise it |
| 433 | returns <code class="literal">idx</code>.</td></tr><tr><td><code class="literal">i < idx</code></td><td><code class="literal">index</code></td><td>This is another syntax for specifying the finish |
| 434 | value. This notation does not include |
| 435 | <code class="literal">idx</code> in the range of valid indices. It is equivalent to |
| 436 | <code class="literal">index_range(r.start(), idx, r.stride())</code></td></tr><tr><td><code class="literal">i <= idx</code></td><td><code class="literal">index</code></td><td>This is another syntax for specifying the finish |
| 437 | value. This notation includes |
| 438 | <code class="literal">idx</code> in the range of valid indices. It is equivalent to |
| 439 | <code class="literal">index_range(r.start(), idx + 1, r.stride())</code></td></tr><tr><td><code class="literal">idx < i</code></td><td><code class="literal">index</code></td><td>This is another syntax for specifying the start |
| 440 | value. This notation does not include |
| 441 | <code class="literal">idx</code> in the range of valid indices. It is equivalent to |
| 442 | <code class="literal">index_range(idx + 1, i.finish(), i.stride())</code>.</td></tr><tr><td><code class="literal">idx <= i</code></td><td><code class="literal">index</code></td><td>This is another syntax for specifying the start |
| 443 | value. This notation includes |
| 444 | <code class="literal">idx1</code> in the range of valid indices. It is equivalent to |
| 445 | <code class="literal">index_range(idx, i.finish(), i.stride())</code>.</td></tr><tr><td><code class="literal">i + idx</code></td><td><code class="literal">index</code></td><td>This expression shifts the start and finish values |
| 446 | of <code class="literal">i</code> up by <code class="literal">idx</code>. It is equivalent to |
| 447 | <code class="literal">index_range(r.start()+idx1, r.finish()+idx, r.stride())</code></td></tr><tr><td><code class="literal">i - idx</code></td><td><code class="literal">index</code></td><td>This expression shifts the start and finish values |
| 448 | of <code class="literal">i</code> up by <code class="literal">idx</code>. It is equivalent to |
| 449 | <code class="literal">index_range(r.start()-idx1, r.finish()-idx, r.stride())</code></td></tr></tbody></table></div></div><br class="table-break"></div><div class="sect3" title="index_gen"><div class="titlepage"><div><div><h4 class="title"><a name="index_gen"></a><code class="literal">index_gen</code></h4></div></div></div><p> <code class="literal">index_gen</code> aggregates |
| 450 | <code class="literal">index_range</code> objects in order to specify view |
| 451 | parameters. Chained calls to <code class="literal">operator[]</code> store |
| 452 | range and dimension information used to |
| 453 | instantiate a new view into a MultiArray. |
| 454 | </p><div class="table"><a name="idp18699808"></a><p class="title"><b>Table 8. Notation</b></p><div class="table-contents"><table summary="Notation" border="1"><colgroup><col><col></colgroup><tbody><tr><td><code class="literal">Dims,Ranges</code></td><td>Unsigned integral values.</td></tr><tr><td><code class="literal">x</code></td><td>An object of type |
| 455 | <code class="literal">template gen_type<Dims,Ranges>::type</code>.</td></tr><tr><td><code class="literal">i</code></td><td>An object of type |
| 456 | <code class="literal">index_range</code>.</td></tr><tr><td><code class="literal">idx</code></td><td>Objects of type <code class="literal">index</code>.</td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="idp18709408"></a><p class="title"><b>Table 9. Associated Types</b></p><div class="table-contents"><table summary="Associated Types" border="1"><colgroup><col><col></colgroup><thead><tr><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">index</code></td><td>This is a signed integral type. It is used to |
| 457 | specify degenerate dimensions.</td></tr><tr><td><code class="literal">size_type</code></td><td>This is an unsigned integral type. It is used to |
| 458 | report the size of the range an <code class="literal">index_range</code> |
| 459 | represents.</td></tr><tr><td> |
| 460 | <code class="literal">template gen_type::<Dims,Ranges>::type</code></td><td>This type generator names the result of |
| 461 | <code class="literal">Dims</code> chained calls to |
| 462 | <code class="literal">index_gen::operator[]</code>. The |
| 463 | <code class="literal">Ranges</code> parameter is determined by the number of |
| 464 | degenerate ranges specified (i.e. calls to |
| 465 | <code class="literal">operator[](index)</code>). Note that |
| 466 | <code class="classname">index_gen</code> and |
| 467 | <code class="classname">gen_type<0,0>::type</code> are the same type.</td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="idp18721296"></a><p class="title"><b>Table 10. Valid Expressions</b></p><div class="table-contents"><table summary="Valid Expressions" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Expression</th><th>Return type</th><th>Semantics</th></tr></thead><tbody><tr><td><code class="literal">index_gen()</code></td><td><code class="literal">gen_type<0,0>::type</code></td><td>This constructs an <code class="literal">index_gen</code> |
| 468 | object. This object can then be used to generate tuples of |
| 469 | <code class="literal">index_range</code> values.</td></tr><tr><td><code class="literal">x[i]</code></td><td><code class="literal">gen_type<Dims+1,Ranges+1>::type</code> |
| 470 | </td><td>Returns a new object containing all previous |
| 471 | <code class="classname">index_range</code> objects in addition to |
| 472 | <code class="literal">i.</code> Chained calls to |
| 473 | <code class="function">operator[]</code> are the means by which |
| 474 | <code class="classname">index_range</code> objects are aggregated.</td></tr><tr><td><code class="literal">x[idx]</code></td><td><code class="literal">gen_type<Dims,Ranges+1>::type</code> |
| 475 | </td><td>Returns a new object containing all previous |
| 476 | <code class="classname">index_range</code> objects in addition to a degenerate |
| 477 | range, <code class="literal">index_range(idx,idx).</code> Note that this is NOT |
| 478 | equivalent to <code class="literal">x[index_range(idx,idx)].</code>, which will |
| 479 | return an object of type |
| 480 | <code class="literal">gen_type<Dims+1,Ranges+1>::type</code>. |
| 481 | </td></tr></tbody></table></div></div><br class="table-break"></div></div><div class="sect2" title="Models"><div class="titlepage"><div><div><h3 class="title"><a name="idp18737792"></a>Models</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><code class="literal">multi_array</code></li><li class="listitem"><code class="literal">multi_array_ref</code></li><li class="listitem"><code class="literal">const_multi_array_ref</code></li><li class="listitem"><code class="literal">template array_view<Dims>::type</code></li><li class="listitem"><code class="literal">template const_array_view<Dims>::type</code></li><li class="listitem"><code class="literal">template subarray<Dims>::type</code></li><li class="listitem"><code class="literal">template const_subarray<Dims>::type</code></li></ul></div></div></div><div class="sect1" title="Array Components"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="array_types"></a>Array Components</h2></div></div></div><p> |
| 482 | Boost.MultiArray defines an array class, |
| 483 | <code class="literal">multi_array</code>, and two adapter classes, |
| 484 | <code class="literal">multi_array_ref</code> and |
| 485 | <code class="literal">const_multi_array_ref</code>. The three classes model |
| 486 | MultiArray and so they share a lot of functionality. |
| 487 | <code class="literal">multi_array_ref</code> differs from |
| 488 | <code class="literal">multi_array</code> in that the |
| 489 | <code class="literal">multi_array</code> manages its own memory, while |
| 490 | <code class="literal">multi_array_ref</code> is passed a block of memory that it |
| 491 | expects to be externally managed. |
| 492 | <code class="literal">const_multi_array_ref</code> differs from |
| 493 | <code class="literal">multi_array_ref</code> in that the underlying elements it |
| 494 | adapts cannot be modified through its interface, though some array |
| 495 | properties, including the array shape and index bases, can be altered. |
| 496 | Functionality the classes have in common is described |
| 497 | below. |
| 498 | </p><p title="Note: Preconditions, Effects, and Implementation"><b>Note: Preconditions, Effects, and Implementation. </b> |
| 499 | Throughout the following sections, small pieces of C++ code are |
| 500 | used to specify constraints such as preconditions, effects, and |
| 501 | postconditions. These do not necessarily describe the underlying |
| 502 | implementation of array components; rather, they describe the |
| 503 | expected input to and |
| 504 | behavior of the specified operations. Failure to meet |
| 505 | preconditions results in undefined behavior. Not all effects |
| 506 | (i.e. copy constructors, etc.) must be mimicked exactly. The code |
| 507 | snippets for effects intend to capture the essence of the described |
| 508 | operation. |
| 509 | </p><p title="Queries"><b>Queries. </b></p><div class="variablelist"><dl><dt><span class="term"><pre class="programlisting">element* data(); |
| 510 | const element* data() const;</pre></span></dt><dd><p>This returns a pointer to the beginning of the |
| 511 | contiguous block that contains the array's data. If all dimensions of |
| 512 | the array are 0-indexed and stored in ascending order, this is |
| 513 | equivalent to <code class="literal">origin()</code>. Note that |
| 514 | <code class="literal">const_multi_array_ref</code> only provides the const |
| 515 | version of this function. |
| 516 | </p></dd><dt><span class="term"><pre class="programlisting">element* origin(); |
| 517 | const element* origin() const;</pre></span></dt><dd><p>This returns the origin element of the |
| 518 | <code class="literal">multi_array</code>. Note that |
| 519 | <code class="literal">const_multi_array_ref</code> only provides the const |
| 520 | version of this function. (Required by MultiArray) |
| 521 | </p></dd><dt><span class="term"><code class="function">const index* index_bases();</code></span></dt><dd><p>This returns the index bases for the |
| 522 | <code class="literal">multi_array</code>. (Required by MultiArray) |
| 523 | </p></dd><dt><span class="term"><code class="function">const index* strides();</code></span></dt><dd><p>This returns the strides for the |
| 524 | <code class="literal">multi_array</code>. (Required by MultiArray) |
| 525 | </p></dd><dt><span class="term"><code class="function">const size_type* shape();</code></span></dt><dd><p>This returns the shape of the |
| 526 | <code class="literal">multi_array</code>. (Required by MultiArray) |
| 527 | </p></dd></dl></div><p title="Comparators"><b>Comparators. </b></p><div class="variablelist"><dl><dt><span class="term"><pre class="programlisting"> |
| 528 | bool operator==(const *array-type*& rhs); |
| 529 | bool operator!=(const *array-type*& rhs); |
| 530 | bool operator<(const *array-type*& rhs); |
| 531 | bool operator>(const *array-type*& rhs); |
| 532 | bool operator>=(const *array-type*& rhs); |
| 533 | bool operator<=(const *array-type*& rhs);</pre></span></dt><dd><p>Each comparator executes a lexicographical compare over |
| 534 | the value types of the two arrays. |
| 535 | (Required by MultiArray) |
| 536 | </p><p title="Preconditions"><b>Preconditions. </b><code class="literal">element</code> must support the |
| 537 | comparator corresponding to that called on |
| 538 | <code class="literal">multi_array</code>.</p><p title="Complexity"><b>Complexity. </b>O(<code class="literal">num_elements()</code>).</p></dd></dl></div><p title="Modifiers"><b>Modifiers. </b></p><div class="variablelist"><dl><dt><span class="term"> |
| 539 | <pre class="programlisting"> |
| 540 | |
| 541 | template <typename SizeList> |
| 542 | void reshape(const SizeList& sizes) |
| 543 | |
| 544 | </pre> |
| 545 | </span></dt><dd><p>This changes the shape of the <code class="literal">multi_array</code>. The |
| 546 | number of elements and the index bases remain the same, but the number |
| 547 | of values at each level of the nested container hierarchy may |
| 548 | change.</p><p title="SizeList Requirements"><b><code class="literal">SizeList</code> Requirements. </b><code class="literal">SizeList</code> must model |
| 549 | <a class="ulink" href="../../utility/Collection.html" target="_top">Collection</a>.</p><p title="Preconditions"><b>Preconditions. </b> |
| 550 | </p><pre class="programlisting"> |
| 551 | std::accumulate(sizes.begin(),sizes.end(),size_type(1),std::times<size_type>()) == this->num_elements(); |
| 552 | sizes.size() == NumDims; |
| 553 | </pre><p title="Postconditions"><b>Postconditions. </b> |
| 554 | <code class="literal">std::equal(sizes.begin(),sizes.end(),this->shape) == true;</code> |
| 555 | </p></dd><dt><span class="term"> |
| 556 | <pre class="programlisting"> |
| 557 | |
| 558 | template <typename BaseList> |
| 559 | void reindex(const BaseList& values); |
| 560 | |
| 561 | </pre> |
| 562 | </span></dt><dd><p>This changes the index bases of the <code class="literal">multi_array</code> to |
| 563 | correspond to the the values in <code class="literal">values</code>.</p><p title="BaseList Requirements"><b><code class="literal">BaseList</code> Requirements. </b><code class="literal">BaseList</code> must model |
| 564 | <a class="ulink" href="../../utility/Collection.html" target="_top">Collection</a>.</p><p title="Preconditions"><b>Preconditions. </b><code class="literal">values.size() == NumDims;</code></p><p title="Postconditions"><b>Postconditions. </b><code class="literal">std::equal(values.begin(),values.end(),this->index_bases()); |
| 565 | </code></p></dd><dt><span class="term"> |
| 566 | <pre class="programlisting"> |
| 567 | |
| 568 | void reindex(index value); |
| 569 | |
| 570 | </pre> |
| 571 | </span></dt><dd><p>This changes the index bases of all dimensions of the |
| 572 | <code class="literal">multi_array</code> to <code class="literal">value</code>.</p><p title="Postconditions"><b>Postconditions. </b> |
| 573 | </p><pre class="programlisting"> |
| 574 | |
| 575 | std::count_if(this->index_bases(),this->index_bases()+this->num_dimensions(), |
| 576 | std::bind_2nd(std::equal_to<index>(),value)) == |
| 577 | this->num_dimensions(); |
| 578 | |
| 579 | </pre><p title="Postconditions"> |
| 580 | </p></dd></dl></div><div class="sect2" title="multi_array"><div class="titlepage"><div><div><h3 class="title"><a name="multi_array_class"></a><code class="literal">multi_array</code></h3></div></div></div><p> |
| 581 | <code class="literal">multi_array</code> is a multi-dimensional container that |
| 582 | supports random access iteration. Its number of dimensions is |
| 583 | fixed at compile time, but its shape and the number of elements it |
| 584 | contains are specified during its construction. The number of elements |
| 585 | will remain fixed for the duration of a |
| 586 | <code class="literal">multi_array</code>'s lifetime, but the shape of the container can |
| 587 | be changed. A <code class="literal">multi_array</code> manages its data elements |
| 588 | using a replaceable allocator. |
| 589 | </p><p title="Model Of."><b>Model Of. </b> |
| 590 | <a class="link" href="#MultiArray" title="MultiArray Concept">MultiArray</a>, |
| 591 | <a class="ulink" href="../../../libs/utility/CopyConstructible.html" target="_top">CopyConstructible</a>. Depending on the element type, |
| 592 | it may also model <a class="ulink" href="http://www.sgi.com/tech/stl/EqualityComparable.html" target="_top">EqualityComparable</a> and <a class="ulink" href="http://www.sgi.com/tech/stl/LessThanComparable.html" target="_top">LessThanComparable</a>. |
| 593 | </p><p title="Synopsis"><b>Synopsis. </b></p><pre class="programlisting"> |
| 594 | |
| 595 | namespace boost { |
| 596 | |
| 597 | template <typename ValueType, |
| 598 | std::size_t NumDims, |
| 599 | typename Allocator = std::allocator<ValueType> > |
| 600 | class multi_array { |
| 601 | public: |
| 602 | // types: |
| 603 | typedef ValueType element; |
| 604 | typedef *unspecified* value_type; |
| 605 | typedef *unspecified* reference; |
| 606 | typedef *unspecified* const_reference; |
| 607 | typedef *unspecified* difference_type; |
| 608 | typedef *unspecified* iterator; |
| 609 | typedef *unspecified* const_iterator; |
| 610 | typedef *unspecified* reverse_iterator; |
| 611 | typedef *unspecified* const_reverse_iterator; |
| 612 | typedef multi_array_types::size_type size_type; |
| 613 | typedef multi_array_types::index index; |
| 614 | typedef multi_array_types::index_gen index_gen; |
| 615 | typedef multi_array_types::index_range index_range; |
| 616 | typedef multi_array_types::extent_gen extent_gen; |
| 617 | typedef multi_array_types::extent_range extent_range; |
| 618 | typedef *unspecified* storage_order_type; |
| 619 | |
| 620 | |
| 621 | // template typedefs |
| 622 | template <std::size_t Dims> struct subarray; |
| 623 | template <std::size_t Dims> struct const_subarray; |
| 624 | template <std::size_t Dims> struct array_view; |
| 625 | template <std::size_t Dims> struct const_array_view; |
| 626 | |
| 627 | |
| 628 | static const std::size_t dimensionality = NumDims; |
| 629 | |
| 630 | |
| 631 | // constructors and destructors |
| 632 | |
| 633 | multi_array(); |
| 634 | |
| 635 | template <typename ExtentList> |
| 636 | explicit multi_array(const ExtentList& sizes, |
| 637 | const storage_order_type& store = c_storage_order(), |
| 638 | const Allocator& alloc = Allocator()); |
| 639 | explicit multi_array(const extents_tuple& ranges, |
| 640 | const storage_order_type& store = c_storage_order(), |
| 641 | const Allocator& alloc = Allocator()); |
| 642 | multi_array(const multi_array& x); |
| 643 | multi_array(const const_multi_array_ref<ValueType,NumDims>& x); |
| 644 | multi_array(const const_subarray<NumDims>::type& x); |
| 645 | multi_array(const const_array_view<NumDims>::type& x); |
| 646 | |
| 647 | multi_array(const multi_array_ref<ValueType,NumDims>& x); |
| 648 | multi_array(const subarray<NumDims>::type& x); |
| 649 | multi_array(const array_view<NumDims>::type& x); |
| 650 | |
| 651 | ~multi_array(); |
| 652 | |
| 653 | // modifiers |
| 654 | |
| 655 | multi_array& operator=(const multi_array& x); |
| 656 | template <class Array> multi_array& operator=(const Array& x); |
| 657 | |
| 658 | // iterators: |
| 659 | iterator begin(); |
| 660 | iterator end(); |
| 661 | const_iterator begin() const; |
| 662 | const_iterator end() const; |
| 663 | reverse_iterator rbegin(); |
| 664 | reverse_iterator rend(); |
| 665 | const_reverse_iterator rbegin() const; |
| 666 | const_reverse_iterator rend() const; |
| 667 | |
| 668 | // capacity: |
| 669 | size_type size() const; |
| 670 | size_type num_elements() const; |
| 671 | size_type num_dimensions() const; |
| 672 | |
| 673 | // element access: |
| 674 | template <typename IndexList> |
| 675 | element& operator()(const IndexList& indices); |
| 676 | template <typename IndexList> |
| 677 | const element& operator()(const IndexList& indices) const; |
| 678 | reference operator[](index i); |
| 679 | const_reference operator[](index i) const; |
| 680 | array_view<Dims>::type operator[](const indices_tuple& r); |
| 681 | const_array_view<Dims>::type operator[](const indices_tuple& r) const; |
| 682 | |
| 683 | // queries |
| 684 | element* data(); |
| 685 | const element* data() const; |
| 686 | element* origin(); |
| 687 | const element* origin() const; |
| 688 | const size_type* shape() const; |
| 689 | const index* strides() const; |
| 690 | const index* index_bases() const; |
| 691 | const storage_order_type& storage_order() const; |
| 692 | |
| 693 | // comparators |
| 694 | bool operator==(const multi_array& rhs); |
| 695 | bool operator!=(const multi_array& rhs); |
| 696 | bool operator<(const multi_array& rhs); |
| 697 | bool operator>(const multi_array& rhs); |
| 698 | bool operator>=(const multi_array& rhs); |
| 699 | bool operator<=(const multi_array& rhs); |
| 700 | |
| 701 | // modifiers: |
| 702 | template <typename InputIterator> |
| 703 | void assign(InputIterator begin, InputIterator end); |
| 704 | template <typename SizeList> |
| 705 | void reshape(const SizeList& sizes) |
| 706 | template <typename BaseList> void reindex(const BaseList& values); |
| 707 | void reindex(index value); |
| 708 | template <typename ExtentList> |
| 709 | multi_array& resize(const ExtentList& extents); |
| 710 | multi_array& resize(extents_tuple& extents); |
| 711 | }; |
| 712 | |
| 713 | </pre><p title="Constructors"><b>Constructors. </b></p><div class="variablelist"><dl><dt><span class="term"><pre class="programlisting">template <typename ExtentList> |
| 714 | explicit multi_array(const ExtentList& sizes, |
| 715 | const storage_order_type& store = c_storage_order(), |
| 716 | const Allocator& alloc = Allocator()); |
| 717 | </pre></span></dt><dd><p> |
| 718 | This constructs a <code class="literal">multi_array</code> using the specified |
| 719 | parameters. <code class="literal">sizes</code> specifies the shape of the |
| 720 | constructed <code class="literal">multi_array</code>. <code class="literal">store</code> |
| 721 | specifies the storage order or layout in memory of the array |
| 722 | dimensions. <code class="literal">alloc</code> is used to |
| 723 | allocate the contained elements. |
| 724 | </p><p title="ExtentList Requirements"><b><code class="literal">ExtentList</code> Requirements. </b> |
| 725 | <code class="literal">ExtentList</code> must model <a class="ulink" href="../../utility/Collection.html" target="_top">Collection</a>. |
| 726 | </p><p title="Preconditions"><b>Preconditions. </b><code class="literal">sizes.size() == NumDims;</code></p></dd><dt><span class="term"> |
| 727 | <pre class="programlisting">explicit multi_array(extent_gen::gen_type<NumDims>::type ranges, |
| 728 | const storage_order_type& store = c_storage_order(), |
| 729 | const Allocator& alloc = Allocator()); |
| 730 | </pre></span></dt><dd><p> |
| 731 | This constructs a <code class="literal">multi_array</code> using the specified |
| 732 | parameters. <code class="literal">ranges</code> specifies the shape and |
| 733 | index bases of the constructed multi_array. It is the result of |
| 734 | <code class="literal">NumDims</code> chained calls to |
| 735 | <code class="literal">extent_gen::operator[]</code>. <code class="literal">store</code> |
| 736 | specifies the storage order or layout in memory of the array |
| 737 | dimensions. <code class="literal">alloc</code> is the allocator used to |
| 738 | allocate the memory used to store <code class="literal">multi_array</code> |
| 739 | elements. |
| 740 | </p></dd><dt><span class="term"><pre class="programlisting"> |
| 741 | multi_array(const multi_array& x); |
| 742 | multi_array(const const_multi_array_ref<ValueType,NumDims>& x); |
| 743 | multi_array(const const_subarray<NumDims>::type& x); |
| 744 | multi_array(const const_array_view<NumDims>::type& x); |
| 745 | multi_array(const multi_array_ref<ValueType,NumDims>& x); |
| 746 | multi_array(const subarray<NumDims>::type& x); |
| 747 | multi_array(const array_view<NumDims>::type& x); |
| 748 | </pre></span></dt><dd><p>These constructors all constructs a <code class="literal">multi_array</code> and |
| 749 | perform a deep copy of <code class="literal">x</code>. |
| 750 | </p><p title="Complexity"><b>Complexity. </b> This performs O(<code class="literal">x.num_elements()</code>) calls to |
| 751 | <code class="literal">element</code>'s copy |
| 752 | constructor. |
| 753 | </p></dd><dt><span class="term"><pre class="programlisting"> |
| 754 | multi_array(); |
| 755 | </pre></span></dt><dd><p>This constructs a <code class="literal">multi_array</code> whose shape is (0,...,0) and contains no elements. |
| 756 | </p></dd></dl></div><p title="Note on Constructors"><b>Note on Constructors. </b> |
| 757 | The <code class="literal">multi_array</code> construction expressions, |
| 758 | </p><pre class="programlisting"> |
| 759 | multi_array<int,3> A(boost::extents[5][4][3]); |
| 760 | </pre><p title="Note on Constructors"> |
| 761 | and |
| 762 | </p><pre class="programlisting"> |
| 763 | boost::array<multi_array_base::index,3> my_extents = {{5, 4, 3}}; |
| 764 | multi_array<int,3> A(my_extents); |
| 765 | </pre><p title="Note on Constructors"> |
| 766 | are equivalent. |
| 767 | </p><p title="Modifiers"><b>Modifiers. </b></p><div class="variablelist"><dl><dt><span class="term"><pre class="programlisting"> |
| 768 | multi_array& operator=(const multi_array& x); |
| 769 | template <class Array> multi_array& operator=(const Array& x); |
| 770 | </pre> |
| 771 | </span></dt><dd><p>This performs an element-wise copy of <code class="literal">x</code> |
| 772 | into the current <code class="literal">multi_array</code>.</p><p title="Array Requirements"><b><code class="literal">Array</code> Requirements. </b><code class="literal">Array</code> must model MultiArray. |
| 773 | </p><p title="Preconditions"><b>Preconditions. </b> |
| 774 | </p><pre class="programlisting">std::equal(this->shape(),this->shape()+this->num_dimensions(), |
| 775 | x.shape());</pre><p title="Postconditions"><b>Postconditions. </b> |
| 776 | </p><pre class="programlisting">(*.this) == x;</pre><p title="Postconditions"> |
| 777 | </p><p title="Complexity"><b>Complexity. </b>The assignment operators perform |
| 778 | O(<code class="literal">x.num_elements()</code>) calls to <code class="literal">element</code>'s |
| 779 | copy constructor.</p></dd><dt><span class="term"> |
| 780 | <pre class="programlisting"> |
| 781 | |
| 782 | template <typename InputIterator> |
| 783 | void assign(InputIterator begin, InputIterator end); |
| 784 | </pre> |
| 785 | </span></dt><dd><p>This copies the elements in the range |
| 786 | <code class="literal">[begin,end)</code> into the array. It is equivalent to |
| 787 | <code class="literal">std::copy(begin,end,this->data())</code>. |
| 788 | </p><p title="Preconditions"><b>Preconditions. </b><code class="literal">std::distance(begin,end) == this->num_elements();</code> |
| 789 | </p><p title="Complexity"><b>Complexity. </b> |
| 790 | The <code class="literal">assign</code> member function performs |
| 791 | O(<code class="literal">this->num_elements()</code>) calls to |
| 792 | <code class="literal">ValueType</code>'s copy constructor. |
| 793 | </p></dd><dt><span class="term"> |
| 794 | <pre class="programlisting">multi_array& resize(extent_gen::gen_type<NumDims>::type extents); |
| 795 | template <typename ExtentList> |
| 796 | multi_array& resize(const ExtentList& extents); |
| 797 | |
| 798 | </pre></span></dt><dd><p> |
| 799 | This function resizes an array to the shape specified by |
| 800 | <code class="literal">extents</code>, which is either a generated list of |
| 801 | extents or a model of the <code class="literal">Collection</code> concept. The |
| 802 | contents of the array are preserved whenever possible; if the new |
| 803 | array size is smaller, then some data will be lost. Any new elements |
| 804 | created by resizing the array are initialized with the |
| 805 | <code class="literal">element</code> default constructor. |
| 806 | </p></dd></dl></div><p title="Queries"><b>Queries. </b></p><div class="variablelist"><dl><dt><span class="term"><pre class="programlisting"> |
| 807 | storage_order_type& storage_order() const; |
| 808 | </pre> |
| 809 | </span></dt><dd><p>This query returns the storage order object associated with the |
| 810 | <code class="literal">multi_array</code> in question. It can be used to construct a new array with the same storage order.</p></dd></dl></div></div><div class="sect2" title="multi_array_ref"><div class="titlepage"><div><div><h3 class="title"><a name="multi_array_ref"></a><code class="literal">multi_array_ref</code></h3></div></div></div><p> |
| 811 | <code class="literal">multi_array_ref</code> is a multi-dimensional container |
| 812 | adaptor. It provides the MultiArray interface over any contiguous |
| 813 | block of elements. <code class="literal">multi_array_ref</code> exports the |
| 814 | same interface as <code class="literal">multi_array</code>, with the exception |
| 815 | of the constructors. |
| 816 | </p><p title="Model Of."><b>Model Of. </b> |
| 817 | <code class="literal">multi_array_ref</code> models |
| 818 | <a class="link" href="#MultiArray" title="MultiArray Concept">MultiArray</a>, |
| 819 | <a class="ulink" href="../../../libs/utility/CopyConstructible.html" target="_top">CopyConstructible</a>. |
| 820 | and depending on the element type, it may also model |
| 821 | <a class="ulink" href="http://www.sgi.com/tech/stl/EqualityComparable.html" target="_top">EqualityComparable</a> and <a class="ulink" href="http://www.sgi.com/tech/stl/LessThanComparable.html" target="_top">LessThanComparable</a>. |
| 822 | Detailed descriptions are provided here only for operations that are |
| 823 | not described in the <code class="literal">multi_array</code> reference. |
| 824 | </p><p title="Synopsis"><b>Synopsis. </b></p><pre class="programlisting"> |
| 825 | |
| 826 | namespace boost { |
| 827 | |
| 828 | template <typename ValueType, |
| 829 | std::size_t NumDims> |
| 830 | class multi_array_ref { |
| 831 | public: |
| 832 | // types: |
| 833 | typedef ValueType element; |
| 834 | typedef *unspecified* value_type; |
| 835 | typedef *unspecified* reference; |
| 836 | typedef *unspecified* const_reference; |
| 837 | typedef *unspecified* difference_type; |
| 838 | typedef *unspecified* iterator; |
| 839 | typedef *unspecified* const_iterator; |
| 840 | typedef *unspecified* reverse_iterator; |
| 841 | typedef *unspecified* const_reverse_iterator; |
| 842 | typedef multi_array_types::size_type size_type; |
| 843 | typedef multi_array_types::index index; |
| 844 | typedef multi_array_types::index_gen index_gen; |
| 845 | typedef multi_array_types::index_range index_range; |
| 846 | typedef multi_array_types::extent_gen extent_gen; |
| 847 | typedef multi_array_types::extent_range extent_range; |
| 848 | typedef *unspecified* storage_order_type; |
| 849 | |
| 850 | // template typedefs |
| 851 | template <std::size_t Dims> struct subarray; |
| 852 | template <std::size_t Dims> struct const_subarray; |
| 853 | template <std::size_t Dims> struct array_view; |
| 854 | template <std::size_t Dims> struct const_array_view; |
| 855 | |
| 856 | |
| 857 | static const std::size_t dimensionality = NumDims; |
| 858 | |
| 859 | |
| 860 | // constructors and destructors |
| 861 | |
| 862 | template <typename ExtentList> |
| 863 | explicit multi_array_ref(element* data, const ExtentList& sizes, |
| 864 | const storage_order_type& store = c_storage_order()); |
| 865 | explicit multi_array_ref(element* data, const extents_tuple& ranges, |
| 866 | const storage_order_type& store = c_storage_order()); |
| 867 | multi_array_ref(const multi_array_ref& x); |
| 868 | ~multi_array_ref(); |
| 869 | |
| 870 | // modifiers |
| 871 | |
| 872 | multi_array_ref& operator=(const multi_array_ref& x); |
| 873 | template <class Array> multi_array_ref& operator=(const Array& x); |
| 874 | |
| 875 | // iterators: |
| 876 | iterator begin(); |
| 877 | iterator end(); |
| 878 | const_iterator begin() const; |
| 879 | const_iterator end() const; |
| 880 | reverse_iterator rbegin(); |
| 881 | reverse_iterator rend(); |
| 882 | const_reverse_iterator rbegin() const; |
| 883 | const_reverse_iterator rend() const; |
| 884 | |
| 885 | // capacity: |
| 886 | size_type size() const; |
| 887 | size_type num_elements() const; |
| 888 | size_type num_dimensions() const; |
| 889 | |
| 890 | // element access: |
| 891 | template <typename IndexList> |
| 892 | element& operator()(const IndexList& indices); |
| 893 | template <typename IndexList> |
| 894 | const element& operator()(const IndexList& indices) const; |
| 895 | reference operator[](index i); |
| 896 | const_reference operator[](index i) const; |
| 897 | array_view<Dims>::type operator[](const indices_tuple& r); |
| 898 | const_array_view<Dims>::type operator[](const indices_tuple& r) const; |
| 899 | |
| 900 | // queries |
| 901 | element* data(); |
| 902 | const element* data() const; |
| 903 | element* origin(); |
| 904 | const element* origin() const; |
| 905 | const size_type* shape() const; |
| 906 | const index* strides() const; |
| 907 | const index* index_bases() const; |
| 908 | const storage_order_type& storage_order() const; |
| 909 | |
| 910 | // comparators |
| 911 | bool operator==(const multi_array_ref& rhs); |
| 912 | bool operator!=(const multi_array_ref& rhs); |
| 913 | bool operator<(const multi_array_ref& rhs); |
| 914 | bool operator>(const multi_array_ref& rhs); |
| 915 | bool operator>=(const multi_array_ref& rhs); |
| 916 | bool operator<=(const multi_array_ref& rhs); |
| 917 | |
| 918 | // modifiers: |
| 919 | template <typename InputIterator> |
| 920 | void assign(InputIterator begin, InputIterator end); |
| 921 | template <typename SizeList> |
| 922 | void reshape(const SizeList& sizes) |
| 923 | template <typename BaseList> void reindex(const BaseList& values); |
| 924 | void reindex(index value); |
| 925 | }; |
| 926 | |
| 927 | </pre><p title="Constructors"><b>Constructors. </b></p><div class="variablelist"><dl><dt><span class="term"><pre class="programlisting">template <typename ExtentList> |
| 928 | explicit multi_array_ref(element* data, |
| 929 | const ExtentList& sizes, |
| 930 | const storage_order& store = c_storage_order(), |
| 931 | const Allocator& alloc = Allocator()); |
| 932 | </pre></span></dt><dd><p> |
| 933 | This constructs a <code class="literal">multi_array_ref</code> using the specified |
| 934 | parameters. <code class="literal">sizes</code> specifies the shape of the |
| 935 | constructed <code class="literal">multi_array_ref</code>. <code class="literal">store</code> |
| 936 | specifies the storage order or layout in memory of the array |
| 937 | dimensions. <code class="literal">alloc</code> is used to |
| 938 | allocate the contained elements. |
| 939 | </p><p title="ExtentList Requirements"><b><code class="literal">ExtentList</code> Requirements. </b> |
| 940 | <code class="literal">ExtentList</code> must model <a class="ulink" href="../../utility/Collection.html" target="_top">Collection</a>. |
| 941 | </p><p title="Preconditions"><b>Preconditions. </b><code class="literal">sizes.size() == NumDims;</code></p></dd><dt><span class="term"> |
| 942 | <pre class="programlisting">explicit multi_array_ref(element* data, |
| 943 | extent_gen::gen_type<NumDims>::type ranges, |
| 944 | const storage_order& store = c_storage_order()); |
| 945 | </pre></span></dt><dd><p> |
| 946 | This constructs a <code class="literal">multi_array_ref</code> using the specified |
| 947 | parameters. <code class="literal">ranges</code> specifies the shape and |
| 948 | index bases of the constructed multi_array_ref. It is the result of |
| 949 | <code class="literal">NumDims</code> chained calls to |
| 950 | <code class="literal">extent_gen::operator[]</code>. <code class="literal">store</code> |
| 951 | specifies the storage order or layout in memory of the array |
| 952 | dimensions. |
| 953 | </p></dd><dt><span class="term"><pre class="programlisting"> |
| 954 | multi_array_ref(const multi_array_ref& x); |
| 955 | </pre></span></dt><dd><p>This constructs a shallow copy of <code class="literal">x</code>. |
| 956 | </p><p title="Complexity"><b>Complexity. </b> Constant time (for contrast, compare this to |
| 957 | the <code class="literal">multi_array</code> class copy constructor. |
| 958 | </p></dd></dl></div><p title="Modifiers"><b>Modifiers. </b></p><div class="variablelist"><dl><dt><span class="term"><pre class="programlisting"> |
| 959 | multi_array_ref& operator=(const multi_array_ref& x); |
| 960 | template <class Array> multi_array_ref& operator=(const Array& x); |
| 961 | </pre> |
| 962 | </span></dt><dd><p>This performs an element-wise copy of <code class="literal">x</code> |
| 963 | into the current <code class="literal">multi_array_ref</code>.</p><p title="Array Requirements"><b><code class="literal">Array</code> Requirements. </b><code class="literal">Array</code> must model MultiArray. |
| 964 | </p><p title="Preconditions"><b>Preconditions. </b> |
| 965 | </p><pre class="programlisting">std::equal(this->shape(),this->shape()+this->num_dimensions(), |
| 966 | x.shape());</pre><p title="Postconditions"><b>Postconditions. </b> |
| 967 | </p><pre class="programlisting">(*.this) == x;</pre><p title="Postconditions"> |
| 968 | </p><p title="Complexity"><b>Complexity. </b>The assignment operators perform |
| 969 | O(<code class="literal">x.num_elements()</code>) calls to <code class="literal">element</code>'s |
| 970 | copy constructor.</p></dd></dl></div></div><div class="sect2" title="const_multi_array_ref"><div class="titlepage"><div><div><h3 class="title"><a name="const_multi_array_ref"></a><code class="literal">const_multi_array_ref</code></h3></div></div></div><p> |
| 971 | <code class="literal">const_multi_array_ref</code> is a multi-dimensional container |
| 972 | adaptor. It provides the MultiArray interface over any contiguous |
| 973 | block of elements. <code class="literal">const_multi_array_ref</code> exports the |
| 974 | same interface as <code class="literal">multi_array</code>, with the exception |
| 975 | of the constructors. |
| 976 | </p><p title="Model Of."><b>Model Of. </b> |
| 977 | <code class="literal">const_multi_array_ref</code> models |
| 978 | <a class="link" href="#MultiArray" title="MultiArray Concept">MultiArray</a>, |
| 979 | <a class="ulink" href="../../../libs/utility/CopyConstructible.html" target="_top">CopyConstructible</a>. |
| 980 | and depending on the element type, it may also model |
| 981 | <a class="ulink" href="http://www.sgi.com/tech/stl/EqualityComparable.html" target="_top">EqualityComparable</a> and <a class="ulink" href="http://www.sgi.com/tech/stl/LessThanComparable.html" target="_top">LessThanComparable</a>. |
| 982 | |
| 983 | Detailed descriptions are provided here only for operations that are |
| 984 | not described in the <code class="literal">multi_array</code> reference. |
| 985 | </p><p title="Synopsis"><b>Synopsis. </b></p><pre class="programlisting"> |
| 986 | |
| 987 | namespace boost { |
| 988 | |
| 989 | template <typename ValueType, |
| 990 | std::size_t NumDims, |
| 991 | typename TPtr = const T*> |
| 992 | class const_multi_array_ref { |
| 993 | public: |
| 994 | // types: |
| 995 | typedef ValueType element; |
| 996 | typedef *unspecified* value_type; |
| 997 | typedef *unspecified* reference; |
| 998 | typedef *unspecified* const_reference; |
| 999 | typedef *unspecified* difference_type; |
| 1000 | typedef *unspecified* iterator; |
| 1001 | typedef *unspecified* const_iterator; |
| 1002 | typedef *unspecified* reverse_iterator; |
| 1003 | typedef *unspecified* const_reverse_iterator; |
| 1004 | typedef multi_array_types::size_type size_type; |
| 1005 | typedef multi_array_types::index index; |
| 1006 | typedef multi_array_types::index_gen index_gen; |
| 1007 | typedef multi_array_types::index_range index_range; |
| 1008 | typedef multi_array_types::extent_gen extent_gen; |
| 1009 | typedef multi_array_types::extent_range extent_range; |
| 1010 | typedef *unspecified* storage_order_type; |
| 1011 | |
| 1012 | // template typedefs |
| 1013 | template <std::size_t Dims> struct subarray; |
| 1014 | template <std::size_t Dims> struct const_subarray; |
| 1015 | template <std::size_t Dims> struct array_view; |
| 1016 | template <std::size_t Dims> struct const_array_view; |
| 1017 | |
| 1018 | |
| 1019 | // structors |
| 1020 | |
| 1021 | template <typename ExtentList> |
| 1022 | explicit const_multi_array_ref(TPtr data, const ExtentList& sizes, |
| 1023 | const storage_order_type& store = c_storage_order()); |
| 1024 | explicit const_multi_array_ref(TPtr data, const extents_tuple& ranges, |
| 1025 | const storage_order_type& store = c_storage_order()); |
| 1026 | const_multi_array_ref(const const_multi_array_ref& x); |
| 1027 | ~const_multi_array_ref(); |
| 1028 | |
| 1029 | |
| 1030 | |
| 1031 | // iterators: |
| 1032 | const_iterator begin() const; |
| 1033 | const_iterator end() const; |
| 1034 | const_reverse_iterator rbegin() const; |
| 1035 | const_reverse_iterator rend() const; |
| 1036 | |
| 1037 | // capacity: |
| 1038 | size_type size() const; |
| 1039 | size_type num_elements() const; |
| 1040 | size_type num_dimensions() const; |
| 1041 | |
| 1042 | // element access: |
| 1043 | template <typename IndexList> |
| 1044 | const element& operator()(const IndexList& indices) const; |
| 1045 | const_reference operator[](index i) const; |
| 1046 | const_array_view<Dims>::type operator[](const indices_tuple& r) const; |
| 1047 | |
| 1048 | // queries |
| 1049 | const element* data() const; |
| 1050 | const element* origin() const; |
| 1051 | const size_type* shape() const; |
| 1052 | const index* strides() const; |
| 1053 | const index* index_bases() const; |
| 1054 | const storage_order_type& storage_order() const; |
| 1055 | |
| 1056 | // comparators |
| 1057 | bool operator==(const const_multi_array_ref& rhs); |
| 1058 | bool operator!=(const const_multi_array_ref& rhs); |
| 1059 | bool operator<(const const_multi_array_ref& rhs); |
| 1060 | bool operator>(const const_multi_array_ref& rhs); |
| 1061 | bool operator>=(const const_multi_array_ref& rhs); |
| 1062 | bool operator<=(const const_multi_array_ref& rhs); |
| 1063 | |
| 1064 | // modifiers: |
| 1065 | template <typename SizeList> |
| 1066 | void reshape(const SizeList& sizes) |
| 1067 | template <typename BaseList> void reindex(const BaseList& values); |
| 1068 | void reindex(index value); |
| 1069 | }; |
| 1070 | |
| 1071 | </pre><p title="Constructors"><b>Constructors. </b></p><div class="variablelist"><dl><dt><span class="term"><pre class="programlisting">template <typename ExtentList> |
| 1072 | explicit const_multi_array_ref(TPtr data, |
| 1073 | const ExtentList& sizes, |
| 1074 | const storage_order& store = c_storage_order()); |
| 1075 | </pre></span></dt><dd><p> |
| 1076 | This constructs a <code class="literal">const_multi_array_ref</code> using the specified |
| 1077 | parameters. <code class="literal">sizes</code> specifies the shape of the |
| 1078 | constructed <code class="literal">const_multi_array_ref</code>. <code class="literal">store</code> |
| 1079 | specifies the storage order or layout in memory of the array |
| 1080 | dimensions. |
| 1081 | </p><p title="ExtentList Requirements"><b><code class="literal">ExtentList</code> Requirements. </b> |
| 1082 | <code class="literal">ExtentList</code> must model <a class="ulink" href="../../utility/Collection.html" target="_top">Collection</a>. |
| 1083 | </p><p title="Preconditions"><b>Preconditions. </b><code class="literal">sizes.size() == NumDims;</code></p></dd><dt><span class="term"> |
| 1084 | <pre class="programlisting">explicit const_multi_array_ref(TPtr data, |
| 1085 | extent_gen::gen_type<NumDims>::type ranges, |
| 1086 | const storage_order& store = c_storage_order()); |
| 1087 | </pre></span></dt><dd><p title="Effects"><b>Effects. </b> |
| 1088 | This constructs a <code class="literal">const_multi_array_ref</code> using the specified |
| 1089 | parameters. <code class="literal">ranges</code> specifies the shape and |
| 1090 | index bases of the constructed const_multi_array_ref. It is the result of |
| 1091 | <code class="literal">NumDims</code> chained calls to |
| 1092 | <code class="literal">extent_gen::operator[]</code>. <code class="literal">store</code> |
| 1093 | specifies the storage order or layout in memory of the array |
| 1094 | dimensions. |
| 1095 | </p></dd><dt><span class="term"><pre class="programlisting"> |
| 1096 | const_multi_array_ref(const const_multi_array_ref& x); |
| 1097 | </pre></span></dt><dd><p title="Effects"><b>Effects. </b>This constructs a shallow copy of <code class="literal">x</code>. |
| 1098 | </p></dd></dl></div></div></div><div class="sect1" title="Auxiliary Components"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="auxiliary"></a>Auxiliary Components</h2></div></div></div><div class="sect2" title="multi_array_types"><div class="titlepage"><div><div><h3 class="title"><a name="multi_array_types"></a><code class="literal">multi_array_types</code></h3></div></div></div><pre class="programlisting"> |
| 1099 | namespace multi_array_types { |
| 1100 | typedef *unspecified* index; |
| 1101 | typedef *unspecified* size_type; |
| 1102 | typedef *unspecified* difference_type; |
| 1103 | typedef *unspecified* index_range; |
| 1104 | typedef *unspecified* extent_range; |
| 1105 | typedef *unspecified* index_gen; |
| 1106 | typedef *unspecified* extent_gen; |
| 1107 | } |
| 1108 | </pre><p>Namespace <code class="literal">multi_array_types</code> defines types |
| 1109 | associated with <code class="literal">multi_array</code>, |
| 1110 | <code class="literal">multi_array_ref</code>, and |
| 1111 | <code class="literal">const_multi_array_ref</code> that are not |
| 1112 | dependent upon template parameters. These types find common use with |
| 1113 | all Boost.Multiarray components. They are defined |
| 1114 | in a namespace from which they can be accessed conveniently. |
| 1115 | With the exception of <code class="literal">extent_gen</code> and |
| 1116 | <code class="literal">extent_range</code>, these types fulfill the roles of the |
| 1117 | same name required by MultiArray and are described in its |
| 1118 | concept definition. <code class="literal">extent_gen</code> and |
| 1119 | <code class="literal">extent_range</code> are described below. |
| 1120 | </p></div><div class="sect2" title="extent_range"><div class="titlepage"><div><div><h3 class="title"><a name="extent_range"></a><code class="classname">extent_range</code></h3></div></div></div><p><code class="classname">extent_range</code> objects define half open |
| 1121 | intervals. They provide shape and index base information to |
| 1122 | <code class="literal">multi_array</code>, <code class="literal">multi_array_ref</code>, |
| 1123 | and <code class="literal">const_multi_array_ref</code> constructors. |
| 1124 | <code class="classname">extent_range</code>s are passed in |
| 1125 | aggregate to an array constructor (see |
| 1126 | <code class="classname">extent_gen</code> for more details). |
| 1127 | </p><p title="Synopsis"><b>Synopsis. </b></p><pre class="programlisting"> |
| 1128 | class extent_range { |
| 1129 | public: |
| 1130 | typedef multi_array_types::index index; |
| 1131 | typedef multi_array_types::size_type size_type; |
| 1132 | |
| 1133 | // Structors |
| 1134 | extent_range(index start, index finish); |
| 1135 | extent_range(index finish); |
| 1136 | ~extent_range(); |
| 1137 | |
| 1138 | // Queries |
| 1139 | index start(); |
| 1140 | index finish(); |
| 1141 | size_type size(); |
| 1142 | };</pre><p title="Model Of"><b>Model Of. </b>DefaultConstructible,CopyConstructible</p><p title="Methods and Types"><b>Methods and Types. </b></p><div class="variablelist"><dl><dt><span class="term"><code class="function">extent_range(index start, index finish)</code></span></dt><dd><p> This constructor defines the half open interval |
| 1143 | <code class="literal">[start,finish)</code>. The expression |
| 1144 | <code class="literal">finish</code> must be greater than <code class="literal">start</code>. |
| 1145 | </p></dd><dt><span class="term"><code class="function">extent_range(index finish)</code></span></dt><dd><p>This constructor defines the half open interval |
| 1146 | <code class="literal">[0,finish)</code>. The value of <code class="literal">finish</code> |
| 1147 | must be positive.</p></dd><dt><span class="term"><code class="function">index start()</code></span></dt><dd><p>This function returns the first index represented by the range</p></dd><dt><span class="term"><code class="function">index finish()</code></span></dt><dd><p>This function returns the upper boundary value of the half-open |
| 1148 | interval. Note that the range does not include this value.</p></dd><dt><span class="term"><code class="function">size_type size()</code></span></dt><dd><p>This function returns the size of the specified range. It is |
| 1149 | equivalent to <code class="literal">finish()-start()</code>.</p></dd></dl></div></div><div class="sect2" title="extent_gen"><div class="titlepage"><div><div><h3 class="title"><a name="extent_gen"></a><code class="classname">extent_gen</code></h3></div></div></div><p>The <code class="classname">extent_gen</code> class defines an |
| 1150 | interface for aggregating array shape and indexing information to be |
| 1151 | passed to a <code class="literal">multi_array</code>, |
| 1152 | <code class="literal">multi_array_ref</code>, or <code class="literal">const_multi_array_ref</code> |
| 1153 | constructor. Its interface mimics |
| 1154 | the syntax used to declare built-in array types |
| 1155 | in C++. For example, while a 3-dimensional array of |
| 1156 | <code class="classname">int</code> values in C++ would be |
| 1157 | declared as: |
| 1158 | </p><pre class="programlisting">int A[3][4][5],</pre><p> |
| 1159 | a similar <code class="classname">multi_array</code> would be declared: |
| 1160 | </p><pre class="programlisting">multi_array<int,3> A(extents[3][4][5]).</pre><p> |
| 1161 | </p><p title="Synopsis"><b>Synopsis. </b></p><pre class="programlisting"> |
| 1162 | template <std::size_t NumRanges> |
| 1163 | class *implementation_defined* { |
| 1164 | public: |
| 1165 | typedef multi_array_types::index index; |
| 1166 | typedef multi_array_types::size_type size_type; |
| 1167 | |
| 1168 | template <std::size_t NumRanges> class gen_type; |
| 1169 | |
| 1170 | gen_type<NumRanges+1>::type operator[](const range& a_range) const; |
| 1171 | gen_type<NumRanges+1>::type operator[](index idx) const; |
| 1172 | }; |
| 1173 | |
| 1174 | typedef *implementation_defined*<0> extent_gen; |
| 1175 | </pre><p title="Methods and Types"><b>Methods and Types. </b></p><div class="variablelist"><dl><dt><span class="term"><code class="function">template gen_type<Ranges>::type</code></span></dt><dd><p>This type generator is used to specify the result of |
| 1176 | <code class="literal">Ranges</code> chained calls to |
| 1177 | <code class="literal">extent_gen::operator[].</code> The types |
| 1178 | <code class="classname">extent_gen</code> and |
| 1179 | <code class="classname">gen_type<0>::type</code> are the same.</p></dd><dt><span class="term"><code class="function">gen_type<NumRanges+1>::type |
| 1180 | operator[](const extent_range& a_range) const;</code></span></dt><dd><p>This function returns a new object containing all previous |
| 1181 | <code class="classname">extent_range</code> objects in addition to |
| 1182 | <code class="literal">a_range.</code> <code class="classname">extent_range</code> |
| 1183 | objects are aggregated by chained calls to |
| 1184 | <code class="function">operator[]</code>.</p></dd><dt><span class="term"><code class="function">gen_type<NumRanges+1>::type |
| 1185 | operator[](index idx) const;</code></span></dt><dd><p>This function returns a new object containing all previous |
| 1186 | <code class="classname">extent_range</code> objects in addition to |
| 1187 | <code class="literal">extent_range(0,idx).</code> This function gives the array |
| 1188 | constructors a similar syntax to traditional C multidimensional array |
| 1189 | declaration.</p></dd></dl></div></div><div class="sect2" title="Global Objects"><div class="titlepage"><div><div><h3 class="title"><a name="idp19487120"></a>Global Objects</h3></div></div></div><p>For syntactic convenience, Boost.MultiArray defines two |
| 1190 | global objects as part of its |
| 1191 | interface. These objects play the role of object generators; |
| 1192 | expressions involving them create other objects of interest. |
| 1193 | </p><p> Under some circumstances, the two global objects may be |
| 1194 | considered excessive overhead. Their construction can be prevented by |
| 1195 | defining the preprocessor symbol |
| 1196 | <code class="literal">BOOST_MULTI_ARRAY_NO_GENERATORS</code> before including |
| 1197 | <code class="filename">boost/multi_array.hpp.</code></p><div class="sect3" title="extents"><div class="titlepage"><div><div><h4 class="title"><a name="extents"></a><code class="literal">extents</code></h4></div></div></div><pre class="programlisting"> |
| 1198 | namespace boost { |
| 1199 | multi_array_base::extent_gen extents; |
| 1200 | } |
| 1201 | </pre><p>Boost.MultiArray's array classes use the |
| 1202 | <code class="literal">extents</code> global object to specify |
| 1203 | array shape during their construction. |
| 1204 | For example, |
| 1205 | a 3 by 3 by 3 <code class="classname">multi_array</code> is constructed as follows: |
| 1206 | </p><pre class="programlisting">multi_array<int,3> A(extents[3][3][3]);</pre><p> |
| 1207 | The same array could also be created by explicitly declaring an <code class="literal">extent_gen</code> |
| 1208 | object locally,, but the global object makes this declaration unnecessary. |
| 1209 | </p></div><div class="sect3" title="indices"><div class="titlepage"><div><div><h4 class="title"><a name="indices"></a><code class="literal">indices</code></h4></div></div></div><pre class="programlisting"> |
| 1210 | namespace boost { |
| 1211 | multi_array_base::index_gen indices; |
| 1212 | } |
| 1213 | </pre><p>The MultiArray concept specifies an |
| 1214 | <code class="literal">index_gen</code> associated type that is used to |
| 1215 | create views. |
| 1216 | <code class="literal">indices</code> is a global object that serves the role of |
| 1217 | <code class="literal">index_gen</code> for all array components provided by this |
| 1218 | library and their associated subarrays and views. |
| 1219 | </p><p>For example, using the <code class="literal">indices</code> object, |
| 1220 | a view of an array <code class="literal">A</code> is constructed as follows: |
| 1221 | </p><pre class="programlisting"> |
| 1222 | A[indices[index_range(0,5)][2][index_range(2,4)]]; |
| 1223 | </pre><p> |
| 1224 | </p></div></div><div class="sect2" title="View and SubArray Generators"><div class="titlepage"><div><div><h3 class="title"><a name="generators"></a>View and SubArray Generators</h3></div></div></div><p> |
| 1225 | Boost.MultiArray provides traits classes, <code class="literal">subarray_gen</code>, |
| 1226 | <code class="literal">const_subarray_gen</code>, |
| 1227 | <code class="literal">array_view_gen</code>, |
| 1228 | and <code class="literal">const_array_view_gen</code>, for naming of |
| 1229 | array associated types within function templates. |
| 1230 | In general this is no more convenient to use than the nested |
| 1231 | type generators, but the library author found that some C++ compilers do not |
| 1232 | properly handle templates nested within function template parameter types. |
| 1233 | These generators constitute a workaround for this deficit. |
| 1234 | The following code snippet illustrates |
| 1235 | the correspondence between the <code class="literal">array_view_gen</code> |
| 1236 | traits class and the <code class="literal">array_view</code> type associated to |
| 1237 | an array: |
| 1238 | |
| 1239 | </p><pre class="programlisting"> |
| 1240 | template <typename Array> |
| 1241 | void my_function() { |
| 1242 | typedef typename Array::template array_view<3>::type view1_t; |
| 1243 | typedef typename boost::array_view_gen<Array,3>::type view2_t; |
| 1244 | // ... |
| 1245 | } |
| 1246 | </pre><p> |
| 1247 | |
| 1248 | In the above example, <code class="literal">view1_t</code> and |
| 1249 | <code class="literal">view2_t</code> have the same type. |
| 1250 | </p></div><div class="sect2" title="Memory Layout Specifiers"><div class="titlepage"><div><div><h3 class="title"><a name="memory_layout"></a>Memory Layout Specifiers</h3></div></div></div><p> |
| 1251 | While a multidimensional array represents a hierarchy of containers of |
| 1252 | elements, at some point the elements must be laid out in |
| 1253 | memory. As a result, a single multidimensional array |
| 1254 | can be represented in memory more than one way. |
| 1255 | </p><p>For example, consider the two dimensional array shown below in |
| 1256 | matrix notation: |
| 1257 | |
| 1258 | </p><div><img src="matrix.gif"></div><p> |
| 1259 | |
| 1260 | Here is how the above array is expressed in C++: |
| 1261 | </p><pre class="programlisting"> |
| 1262 | int a[3][4] = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11 }; |
| 1263 | </pre><p> |
| 1264 | This is an example of row-major storage, where elements of each row |
| 1265 | are stored contiguously. |
| 1266 | |
| 1267 | While C++ transparently handles accessing elements of an array, you |
| 1268 | can also manage the array and its indexing manually. One way that |
| 1269 | this may be expressed in memory is as follows: |
| 1270 | </p><pre class="programlisting"> |
| 1271 | int a[] = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11 }; |
| 1272 | int s[] = { 4, 1 }; |
| 1273 | </pre><p> |
| 1274 | |
| 1275 | With the latter declaration of <code class="literal">a</code> and |
| 1276 | strides <code class="literal">s</code>, element <code class="literal">a(i,j)</code> |
| 1277 | of the array can be |
| 1278 | accessed using the expression |
| 1279 | </p><pre class="programlisting">*a+i*s[0]+j*s[1]</pre><p>. |
| 1280 | </p><p>The same two dimensional array could be laid out by column as follows: |
| 1281 | |
| 1282 | </p><pre class="programlisting"> |
| 1283 | int a[] = { 0, 4, 8, 1, 5, 9, 2, 6, 10, 3, 7, 11 }; |
| 1284 | int s[] = { 3, 1 }; |
| 1285 | </pre><p> |
| 1286 | Notice that the strides here are different. As a result, |
| 1287 | The expression given above to access values will work with this pair |
| 1288 | of data and strides as well. |
| 1289 | </p><p>In addition to dimension order, it is also possible to |
| 1290 | store any dimension in descending order. For example, returning to the |
| 1291 | first example, the first dimension of the example array, the |
| 1292 | rows, could be stored in |
| 1293 | reverse, resulting in the following: |
| 1294 | |
| 1295 | </p><pre class="programlisting"> |
| 1296 | int data[] = { 8, 9, 10, 11, 4, 5, 6, 7, 0, 1, 2, 3 }; |
| 1297 | int *a = data + 8; |
| 1298 | int s[] = { -4, 1 }; |
| 1299 | </pre><p> |
| 1300 | |
| 1301 | Note that in this example <code class="literal">a</code> must be explicitly set |
| 1302 | to the origin. In the previous examples, the |
| 1303 | first element stored in memory was the origin; here this is no longer |
| 1304 | the case. |
| 1305 | </p><p> |
| 1306 | Alternatively, the second dimension, or the columns, could be reversed |
| 1307 | and the rows stored in ascending order: |
| 1308 | |
| 1309 | </p><pre class="programlisting"> |
| 1310 | int data[] = { 3, 2, 1, 0, 7, 6, 5, 4, 11, 10, 9, 8 }; |
| 1311 | int *a = data + 3; |
| 1312 | int s[] = { 4, -1 }; |
| 1313 | </pre><p> |
| 1314 | </p><p> |
| 1315 | Finally, both dimensions could be stored in descending order: |
| 1316 | |
| 1317 | </p><pre class="programlisting"> |
| 1318 | int data[] = {11, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0}; |
| 1319 | int *a = data + 11; |
| 1320 | int s[] = { -4, -1 }; |
| 1321 | </pre><p> |
| 1322 | <code class="literal"> |
| 1323 | </code> |
| 1324 | </p><p> |
| 1325 | All of the above arrays are equivalent. The expression |
| 1326 | given above for <code class="literal">a(i,j)</code> will yield the same value |
| 1327 | regardless of the memory layout. |
| 1328 | |
| 1329 | Boost.MultiArray arrays can be created with customized storage |
| 1330 | parameters as described above. Thus, existing data can be adapted |
| 1331 | (with <code class="literal">multi_array_ref</code> or |
| 1332 | <code class="literal">const_multi_array_ref</code>) as suited to the array |
| 1333 | abstraction. A common usage of this feature would be to wrap arrays |
| 1334 | that must interoperate with Fortran routines so they can be |
| 1335 | manipulated naturally at both the C++ and Fortran levels. The |
| 1336 | following sections describe the Boost.MultiArray components used to |
| 1337 | specify memory layout. |
| 1338 | </p><div class="sect3" title="c_storage_order"><div class="titlepage"><div><div><h4 class="title"><a name="c_storage_order"></a><code class="literal">c_storage_order</code></h4></div></div></div><pre class="programlisting"> |
| 1339 | class c_storage_order { |
| 1340 | c_storage_order(); |
| 1341 | }; |
| 1342 | </pre><p><code class="literal">c_storage_order</code> is used to specify that an |
| 1343 | array should store its elements using the same layout as that used by |
| 1344 | primitive C++ multidimensional arrays, that is, from last dimension |
| 1345 | to first. This is the default storage order for the arrays provided by |
| 1346 | this library.</p></div><div class="sect3" title="fortran_storage_order"><div class="titlepage"><div><div><h4 class="title"><a name="fortran_storage_order"></a><code class="literal">fortran_storage_order</code></h4></div></div></div><pre class="programlisting"> |
| 1347 | class fortran_storage_order { |
| 1348 | fortran_storage_order(); |
| 1349 | }; |
| 1350 | </pre><p><code class="literal">fortran_storage_order</code> is used to specify that |
| 1351 | an array should store its elements using the same memory layout as a |
| 1352 | Fortran multidimensional array would, that is, from first dimension to |
| 1353 | last.</p></div><div class="sect3" title="general_storage_order"><div class="titlepage"><div><div><h4 class="title"><a name="general_storage_order"></a><code class="literal">general_storage_order</code></h4></div></div></div><pre class="programlisting"> |
| 1354 | template <std::size_t NumDims> |
| 1355 | class general_storage_order { |
| 1356 | |
| 1357 | template <typename OrderingIter, typename AscendingIter> |
| 1358 | general_storage_order(OrderingIter ordering, AscendingIter ascending); |
| 1359 | }; |
| 1360 | </pre><p><code class="literal">general_storage_order</code> allows the user to |
| 1361 | specify an arbitrary memory layout for the contents of an array. The |
| 1362 | constructed object is passed to the array constructor in order to |
| 1363 | specify storage order.</p><p> |
| 1364 | <code class="literal">OrderingIter</code> and <code class="literal">AscendingIter</code> |
| 1365 | must model the <code class="literal">InputIterator</code> concept. Both |
| 1366 | iterators must refer to a range of <code class="literal">NumDims</code> |
| 1367 | elements. <code class="literal">AscendingIter</code> points to objects |
| 1368 | convertible to <code class="literal">bool</code>. A value of |
| 1369 | <code class="literal">true</code> means that a dimension is stored in ascending |
| 1370 | order while <code class="literal">false</code> means that a dimension is stored |
| 1371 | in descending order. <code class="literal">OrderingIter</code> specifies the |
| 1372 | order in which dimensions are stored. |
| 1373 | </p></div></div><div class="sect2" title="Range Checking"><div class="titlepage"><div><div><h3 class="title"><a name="range_checking"></a>Range Checking</h3></div></div></div><p> |
| 1374 | By default, the array access methods <code class="literal">operator()</code> and |
| 1375 | <code class="literal">operator[]</code> perform range |
| 1376 | checking. If a supplied index is out of the range defined for an |
| 1377 | array, an assertion will abort the program. To disable range |
| 1378 | checking (for performance reasons in production releases), define |
| 1379 | the <code class="literal">BOOST_DISABLE_ASSERTS</code> preprocessor macro prior to |
| 1380 | including multi_array.hpp in an application. |
| 1381 | </p></div></div></div></body></html> |