Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_33_1/libs/multi_array/doc/reference.html @ 20

Last change on this file since 20 was 12, checked in by landauf, 18 years ago

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