• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2<html>
3<head>
4<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
5<title>Auxiliary Components</title>
6<link rel="stylesheet" href="../../doc/src/boostbook.css" type="text/css">
7<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
8<link rel="home" href="index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
9<link rel="up" href="multi_array.html" title="Chapter 27. Boost.MultiArray Reference Manual">
10<link rel="prev" href="array_types.html" title="Array Components">
11<link rel="next" href="poly_collection.html" title="Chapter 28. Boost.PolyCollection">
12</head>
13<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
14<table cellpadding="2" width="100%"><tr>
15<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../boost.png"></td>
16<td align="center"><a href="../../index.html">Home</a></td>
17<td align="center"><a href="../../libs/libraries.htm">Libraries</a></td>
18<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
19<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
20<td align="center"><a href="../../more/index.htm">More</a></td>
21</tr></table>
22<hr>
23<div class="spirit-nav">
24<a accesskey="p" href="array_types.html"><img src="../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="multi_array.html"><img src="../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="poly_collection.html"><img src="../../doc/src/images/next.png" alt="Next"></a>
25</div>
26<div class="sect1">
27<div class="titlepage"><div><div><h2 class="title" style="clear: both">
28<a name="auxiliary"></a>Auxiliary Components</h2></div></div></div>
29<div class="toc"><dl class="toc">
30<dt><span class="sect2"><a href="auxiliary.html#multi_array_types"><code class="literal">multi_array_types</code></a></span></dt>
31<dt><span class="sect2"><a href="auxiliary.html#extent_range"><code class="computeroutput">extent_range</code></a></span></dt>
32<dt><span class="sect2"><a href="auxiliary.html#extent_gen"><code class="computeroutput">extent_gen</code></a></span></dt>
33<dt><span class="sect2"><a href="auxiliary.html#id-1.3.28.7.5">Global Objects</a></span></dt>
34<dt><span class="sect2"><a href="auxiliary.html#generators">View and SubArray Generators</a></span></dt>
35<dt><span class="sect2"><a href="auxiliary.html#memory_layout">Memory Layout Specifiers</a></span></dt>
36<dt><span class="sect2"><a href="auxiliary.html#range_checking">Range Checking</a></span></dt>
37</dl></div>
38<div class="sect2">
39<div class="titlepage"><div><div><h3 class="title">
40<a name="multi_array_types"></a><code class="literal">multi_array_types</code>
41</h3></div></div></div>
42<pre class="programlisting">
43namespace multi_array_types {
44  typedef *unspecified* index;
45  typedef *unspecified* size_type;
46  typedef *unspecified* difference_type;
47  typedef *unspecified* index_range;
48  typedef *unspecified* extent_range;
49  typedef *unspecified* index_gen;
50  typedef *unspecified* extent_gen;
51}
52</pre>
53<p>Namespace <code class="literal">multi_array_types</code> defines types
54associated with <code class="literal">multi_array</code>,
55<code class="literal">multi_array_ref</code>, and
56<code class="literal">const_multi_array_ref</code> that are not
57dependent upon template parameters.  These types find common use with
58all Boost.Multiarray components.  They are defined
59in a namespace from which they can be accessed conveniently.
60With the exception of <code class="literal">extent_gen</code> and
61<code class="literal">extent_range</code>, these types fulfill the roles of the
62same name required by MultiArray and are described in its
63concept definition.  <code class="literal">extent_gen</code> and
64<code class="literal">extent_range</code> are described below.
65</p>
66</div>
67<div class="sect2">
68<div class="titlepage"><div><div><h3 class="title">
69<a name="extent_range"></a><code class="computeroutput">extent_range</code>
70</h3></div></div></div>
71<p><code class="computeroutput">extent_range</code> objects define half open
72intervals.  They provide shape and index base information to
73<code class="literal">multi_array</code>, <code class="literal">multi_array_ref</code>,
74 and <code class="literal">const_multi_array_ref</code> constructors.
75<code class="computeroutput">extent_range</code>s are passed in
76aggregate to an array constructor (see
77<code class="computeroutput">extent_gen</code> for more details).
78</p>
79<p><b>Synopsis. </b></p>
80<pre class="programlisting">
81class extent_range {
82public:
83  typedef multi_array_types::index      index;
84  typedef multi_array_types::size_type  size_type;
85
86  // Structors
87  extent_range(index start, index finish);
88  extent_range(index finish);
89  ~extent_range();
90
91  // Queries
92  index start();
93  index finish();
94  size_type size();
95};</pre>
96<p><b>Model Of. </b>DefaultConstructible,CopyConstructible</p>
97<p><b>Methods and Types. </b></p>
98<div class="variablelist"><dl class="variablelist">
99<dt><span class="term"><code class="function">extent_range(index start, index finish)</code></span></dt>
100<dd><p>  This constructor defines the half open interval
101<code class="literal">[start,finish)</code>. The expression
102<code class="literal">finish</code> must be greater than <code class="literal">start</code>.
103</p></dd>
104<dt><span class="term"><code class="function">extent_range(index finish)</code></span></dt>
105<dd><p>This constructor defines the half open interval
106<code class="literal">[0,finish)</code>. The value of <code class="literal">finish</code>
107must be positive.</p></dd>
108<dt><span class="term"><code class="function">index start()</code></span></dt>
109<dd><p>This function returns the first index represented by the range</p></dd>
110<dt><span class="term"><code class="function">index finish()</code></span></dt>
111<dd><p>This function returns the upper boundary value of the half-open
112interval.  Note that the range does not include this value.</p></dd>
113<dt><span class="term"><code class="function">size_type size()</code></span></dt>
114<dd><p>This function returns the size of the specified range. It is
115equivalent to <code class="literal">finish()-start()</code>.</p></dd>
116</dl></div>
117</div>
118<div class="sect2">
119<div class="titlepage"><div><div><h3 class="title">
120<a name="extent_gen"></a><code class="computeroutput">extent_gen</code>
121</h3></div></div></div>
122<p>The <code class="computeroutput">extent_gen</code> class defines an
123interface for aggregating array shape and indexing information to be
124passed to a <code class="literal">multi_array</code>,
125<code class="literal">multi_array_ref</code>, or <code class="literal">const_multi_array_ref</code>
126constructor. Its interface mimics
127 the syntax used to declare built-in array types
128in C++. For example, while a 3-dimensional array of
129<code class="computeroutput">int</code> values in C++ would be
130declared as:
131</p>
132<pre class="programlisting">int A[3][4][5],</pre>
133<p>
134a similar <code class="computeroutput">multi_array</code> would be declared:
135</p>
136<pre class="programlisting">multi_array&lt;int,3&gt; A(extents[3][4][5]).</pre>
137<p>
138</p>
139<p><b>Synopsis. </b></p>
140<pre class="programlisting">
141template &lt;std::size_t NumRanges&gt;
142class *implementation_defined* {
143public:
144  typedef multi_array_types::index index;
145  typedef multi_array_types::size_type size_type;
146
147  template &lt;std::size_t NumRanges&gt; class gen_type;
148
149  gen_type&lt;NumRanges+1&gt;::type  operator[](const range&amp; a_range) const;
150  gen_type&lt;NumRanges+1&gt;::type  operator[](index idx) const;
151};
152
153typedef *implementation_defined*&lt;0&gt; extent_gen;
154</pre>
155<p><b>Methods and Types. </b></p>
156<div class="variablelist"><dl class="variablelist">
157<dt><span class="term"><code class="function">template gen_type&lt;Ranges&gt;::type</code></span></dt>
158<dd><p>This type generator is used to specify the result of
159<code class="literal">Ranges</code> chained calls to
160<code class="literal">extent_gen::operator[].</code> The types
161<code class="computeroutput">extent_gen</code> and
162<code class="computeroutput">gen_type&lt;0&gt;::type</code> are the same.</p></dd>
163<dt><span class="term"><code class="function">gen_type&lt;NumRanges+1&gt;::type
164operator[](const extent_range&amp; a_range) const;</code></span></dt>
165<dd><p>This function returns a new object containing all previous
166<code class="computeroutput">extent_range</code> objects in addition to
167<code class="literal">a_range.</code> <code class="computeroutput">extent_range</code>
168objects are aggregated by chained calls to
169<code class="function">operator[]</code>.</p></dd>
170<dt><span class="term"><code class="function">gen_type&lt;NumRanges+1&gt;::type
171operator[](index idx) const;</code></span></dt>
172<dd><p>This function returns a new object containing all previous
173<code class="computeroutput">extent_range</code> objects in addition to
174<code class="literal">extent_range(0,idx).</code> This function gives the array
175constructors a similar syntax to traditional C multidimensional array
176declaration.</p></dd>
177</dl></div>
178</div>
179<div class="sect2">
180<div class="titlepage"><div><div><h3 class="title">
181<a name="id-1.3.28.7.5"></a>Global Objects</h3></div></div></div>
182<div class="toc"><dl class="toc">
183<dt><span class="sect3"><a href="auxiliary.html#extents"><code class="literal">extents</code></a></span></dt>
184<dt><span class="sect3"><a href="auxiliary.html#indices"><code class="literal">indices</code></a></span></dt>
185</dl></div>
186<p>For syntactic convenience, Boost.MultiArray defines two
187global objects as part of its
188interface.  These objects play the role of object generators;
189expressions involving them create other objects of interest.
190</p>
191<p> Under some circumstances, the two global objects may be
192considered excessive overhead.  Their construction can be prevented by
193defining the preprocessor symbol
194<code class="literal">BOOST_MULTI_ARRAY_NO_GENERATORS</code> before including
195<code class="filename">boost/multi_array.hpp.</code></p>
196<div class="sect3">
197<div class="titlepage"><div><div><h4 class="title">
198<a name="extents"></a><code class="literal">extents</code>
199</h4></div></div></div>
200<pre class="programlisting">
201namespace boost {
202  multi_array_base::extent_gen extents;
203}
204</pre>
205<p>Boost.MultiArray's array classes use the
206<code class="literal">extents</code> global object to specify
207array shape during their construction.
208For example,
209a 3 by 3 by 3 <code class="computeroutput">multi_array</code> is constructed as follows:
210</p>
211<pre class="programlisting">multi_array&lt;int,3&gt; A(extents[3][3][3]);</pre>
212<p>
213The same array could also be created by explicitly declaring an <code class="literal">extent_gen</code>
214object locally,, but the global object makes this declaration unnecessary.
215</p>
216</div>
217<div class="sect3">
218<div class="titlepage"><div><div><h4 class="title">
219<a name="indices"></a><code class="literal">indices</code>
220</h4></div></div></div>
221<pre class="programlisting">
222namespace boost {
223  multi_array_base::index_gen  indices;
224}
225</pre>
226<p>The MultiArray concept specifies an
227<code class="literal">index_gen</code> associated type that is used to
228create views.
229<code class="literal">indices</code> is a global object that serves the role of
230<code class="literal">index_gen</code> for all array components provided by this
231library and their associated subarrays and views.
232</p>
233<p>For example, using the <code class="literal">indices</code> object,
234a view of an array <code class="literal">A</code> is constructed as follows:
235</p>
236<pre class="programlisting">
237A[indices[index_range(0,5)][2][index_range(2,4)]];
238</pre>
239<p>
240</p>
241</div>
242</div>
243<div class="sect2">
244<div class="titlepage"><div><div><h3 class="title">
245<a name="generators"></a>View and SubArray Generators</h3></div></div></div>
246<p>
247Boost.MultiArray provides traits classes, <code class="literal">subarray_gen</code>,
248<code class="literal">const_subarray_gen</code>,
249<code class="literal">array_view_gen</code>,
250and <code class="literal">const_array_view_gen</code>, for naming of
251array associated types within function templates.
252In general this is no more convenient to use than the nested
253type generators, but the library author found that some C++ compilers do not
254properly handle templates nested within function template parameter types.
255These generators constitute a workaround for this deficit.
256The following code snippet illustrates
257the correspondence between the <code class="literal">array_view_gen</code>
258traits class and the <code class="literal">array_view</code> type associated to
259an array:
260
261</p>
262<pre class="programlisting">
263template &lt;typename Array&gt;
264void my_function() {
265  typedef typename Array::template array_view&lt;3&gt;::type view1_t;
266  typedef typename boost::array_view_gen&lt;Array,3&gt;::type view2_t;
267  // ...
268}
269</pre>
270<p>
271
272In the above example, <code class="literal">view1_t</code> and
273<code class="literal">view2_t</code> have the same type.
274</p>
275</div>
276<div class="sect2">
277<div class="titlepage"><div><div><h3 class="title">
278<a name="memory_layout"></a>Memory Layout Specifiers</h3></div></div></div>
279<div class="toc"><dl class="toc">
280<dt><span class="sect3"><a href="auxiliary.html#c_storage_order"><code class="literal">c_storage_order</code></a></span></dt>
281<dt><span class="sect3"><a href="auxiliary.html#fortran_storage_order"><code class="literal">fortran_storage_order</code></a></span></dt>
282<dt><span class="sect3"><a href="auxiliary.html#general_storage_order"><code class="literal">general_storage_order</code></a></span></dt>
283</dl></div>
284<p>
285While a multidimensional array represents a hierarchy of containers of
286elements, at some point the elements must be laid out in
287memory.  As a result, a single multidimensional array
288can be represented in memory more than one way.
289</p>
290<p>For example, consider the two dimensional array shown below in
291matrix notation:
292
293</p>
294<div><img src="matrix.gif"></div>
295<p>
296
297Here is how the above array is expressed in C++:
298</p>
299<pre class="programlisting">
300int a[3][4] = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11 };
301</pre>
302<p>
303This is an example of row-major storage, where elements of each row
304are stored contiguously.
305
306While C++ transparently handles accessing elements of an array, you
307can also manage the array and its indexing manually.  One way that
308this may be expressed in memory is as follows:
309</p>
310<pre class="programlisting">
311int a[] = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11 };
312int s[] = { 4, 1 };
313</pre>
314<p>
315
316With the latter declaration of <code class="literal">a</code> and
317strides <code class="literal">s</code>, element <code class="literal">a(i,j)</code>
318of the array can be
319accessed using the expression
320</p>
321<pre class="programlisting">*a+i*s[0]+j*s[1]</pre>
322<p>.
323</p>
324<p>The same two dimensional array could be laid out by column as follows:
325
326</p>
327<pre class="programlisting">
328int a[] = { 0, 4, 8, 1, 5, 9, 2, 6, 10, 3, 7, 11 };
329int s[] = { 3, 1 };
330</pre>
331<p>
332Notice that the strides here are different. As a result,
333The expression given above to access values will work with this pair
334of data and strides as well.
335</p>
336<p>In addition to dimension order, it is also possible to
337store any dimension in descending order. For example, returning to the
338first example, the first dimension of the example array, the
339rows,  could be stored in
340reverse, resulting in the following:
341
342</p>
343<pre class="programlisting">
344int data[] = { 8, 9, 10, 11, 4, 5, 6, 7, 0, 1, 2, 3 };
345int *a = data + 8;
346int s[] = { -4, 1 };
347</pre>
348<p>
349
350Note that in this example <code class="literal">a</code> must be explicitly set
351to the origin. In the previous examples, the
352first element stored in memory was the origin; here this is no longer
353the case.
354</p>
355<p>
356Alternatively, the second dimension, or the columns, could be reversed
357and the rows stored in ascending order:
358
359</p>
360<pre class="programlisting">
361int data[] = { 3, 2, 1, 0,  7, 6, 5, 4, 11, 10, 9, 8 };
362int *a = data + 3;
363int s[] = { 4, -1 };
364</pre>
365<p>
366</p>
367<p>
368Finally, both dimensions could be stored in descending order:
369
370</p>
371<pre class="programlisting">
372int data[] = {11, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0};
373int *a = data + 11;
374int s[] = { -4, -1 };
375</pre>
376<p>
377<code class="literal">
378</code>
379</p>
380<p>
381All of the above arrays are equivalent. The expression
382given above for <code class="literal">a(i,j)</code> will yield the same value
383regardless of the memory layout.
384
385Boost.MultiArray arrays can be created with customized storage
386parameters as described above. Thus, existing data can be adapted
387(with <code class="literal">multi_array_ref</code> or
388<code class="literal">const_multi_array_ref</code>) as suited to the array
389abstraction.  A common usage of this feature would be to wrap arrays
390that must interoperate with Fortran routines so they can be
391manipulated naturally at both the C++ and Fortran levels. The
392following sections describe the Boost.MultiArray components used to
393specify memory layout.
394</p>
395<div class="sect3">
396<div class="titlepage"><div><div><h4 class="title">
397<a name="c_storage_order"></a><code class="literal">c_storage_order</code>
398</h4></div></div></div>
399<pre class="programlisting">
400class c_storage_order {
401  c_storage_order();
402};
403</pre>
404<p><code class="literal">c_storage_order</code> is used to specify that an
405array should store its elements using the same layout as that used by
406primitive C++ multidimensional arrays, that is, from last dimension
407to first. This is the default storage order for the arrays provided by
408this library.</p>
409</div>
410<div class="sect3">
411<div class="titlepage"><div><div><h4 class="title">
412<a name="fortran_storage_order"></a><code class="literal">fortran_storage_order</code>
413</h4></div></div></div>
414<pre class="programlisting">
415class fortran_storage_order {
416  fortran_storage_order();
417};
418</pre>
419<p><code class="literal">fortran_storage_order</code> is used to specify that
420an array should store its elements using the same memory layout as a
421Fortran multidimensional array would, that is, from first dimension to
422last.</p>
423</div>
424<div class="sect3">
425<div class="titlepage"><div><div><h4 class="title">
426<a name="general_storage_order"></a><code class="literal">general_storage_order</code>
427</h4></div></div></div>
428<pre class="programlisting">
429template &lt;std::size_t NumDims&gt;
430class general_storage_order {
431
432  template &lt;typename OrderingIter, typename AscendingIter&gt;
433  general_storage_order(OrderingIter ordering, AscendingIter ascending);
434};
435</pre>
436<p><code class="literal">general_storage_order</code> allows the user to
437specify an arbitrary memory layout for the contents of an array.  The
438constructed object is passed to the array constructor in order to
439specify storage order.</p>
440<p>
441<code class="literal">OrderingIter</code> and <code class="literal">AscendingIter</code>
442must model the <code class="literal">InputIterator</code> concept.  Both
443iterators must refer to a range of <code class="literal">NumDims</code>
444elements.  <code class="literal">AscendingIter</code> points to objects
445convertible to <code class="literal">bool</code>.  A value of
446<code class="literal">true</code> means that a dimension is stored in ascending
447order while <code class="literal">false</code> means that a dimension is stored
448in descending order.  <code class="literal">OrderingIter</code> specifies the
449order in which dimensions are stored.
450</p>
451</div>
452</div>
453<div class="sect2">
454<div class="titlepage"><div><div><h3 class="title">
455<a name="range_checking"></a>Range Checking</h3></div></div></div>
456<p>
457By default, the array access methods <code class="literal">operator()</code> and
458<code class="literal">operator[]</code> perform range
459checking.  If a supplied index is out of the range defined for an
460array, an assertion will abort the program.  To disable range
461checking (for performance reasons in production releases), define
462the <code class="literal">BOOST_DISABLE_ASSERTS</code> preprocessor macro prior to
463including multi_array.hpp in an application.
464</p>
465</div>
466</div>
467<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
468<td align="left"></td>
469<td align="right"><div class="copyright-footer">Copyright © 2002 The Trustees of Indiana University</div></td>
470</tr></table>
471<hr>
472<div class="spirit-nav">
473<a accesskey="p" href="array_types.html"><img src="../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="multi_array.html"><img src="../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="poly_collection.html"><img src="../../doc/src/images/next.png" alt="Next"></a>
474</div>
475</body>
476</html>
477