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