boost/multi_array
2
0
Fork 0
mirror of https://github.com/boostorg/multi_array.git synced 2026-02-03 09:22:12 +00:00
Code Issues Projects Releases Wiki Activity

Full merge from trunk at revision 41356 of entire boost-root tree.

Browse Source 
[SVN r41370]
This commit is contained in:
Beman Dawes
2007-11-25 18:38:02 +00:00
parent de0307c344
commit 1e8a9db226
12 changed files with 175 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
doc/reference.html
View File

@@ -1,4 +1,4 @@
<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.68.1"></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="id729900"></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><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="#id834641">Notation</a></span></dt><dt><span class="sect2"><a href="#id834809">Associated Types</a></span></dt><dt><span class="sect2"><a href="#id835319">Valid expressions</a></span></dt><dt><span class="sect2"><a href="#id836109">Complexity guarantees</a></span></dt><dt><span class="sect2"><a href="#id836133">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="#id837503">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"><code class="literal">multi_array</code></a></span></dt><dt><span class="sect2"><a href="#multi_array_ref"><code class="literal">multi_array_ref</code></a></span></dt><dt><span class="sect2"><a href="#const_multi_array_ref"><code class="literal">const_multi_array_ref</code></a></span></dt></dl></dd><dt><span class="sect1"><a href="#auxiliary">Auxiliary Components</a></span></dt><dd><dl><dt><span class="sect2"><a href="#multi_array_types"><code class="literal">multi_array_types</code></a></span></dt><dt><span class="sect2"><a href="#extent_range"><code class="classname">extent_range</code></a></span></dt><dt><span class="sect2"><a href="#extent_gen"><code class="classname">extent_gen</code></a></span></dt><dt><span class="sect2"><a href="#id862083">Global Objects</a></span></dt><dt><span class="sect2"><a href="#generators">View and SubArray Generators</a></span></dt><dt><span class="sect2"><a href="#memory_layout">Memory Layout Specifiers</a></span></dt><dt><span class="sect2"><a href="#range_checking">Range Checking</a></span></dt></dl></dd></dl></div><p>Boost.MultiArray is composed of several components.
<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.71.1"></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="id823342"></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><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="#id896773">Notation</a></span></dt><dt><span class="sect2"><a href="#id896941">Associated Types</a></span></dt><dt><span class="sect2"><a href="#id897451">Valid expressions</a></span></dt><dt><span class="sect2"><a href="#id898268">Complexity guarantees</a></span></dt><dt><span class="sect2"><a href="#id898293">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="#id899663">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"><code class="literal">multi_array</code></a></span></dt><dt><span class="sect2"><a href="#multi_array_ref"><code class="literal">multi_array_ref</code></a></span></dt><dt><span class="sect2"><a href="#const_multi_array_ref"><code class="literal">const_multi_array_ref</code></a></span></dt></dl></dd><dt><span class="sect1"><a href="#auxiliary">Auxiliary Components</a></span></dt><dd><dl><dt><span class="sect2"><a href="#multi_array_types"><code class="literal">multi_array_types</code></a></span></dt><dt><span class="sect2"><a href="#extent_range"><code class="classname">extent_range</code></a></span></dt><dt><span class="sect2"><a href="#extent_gen"><code class="classname">extent_gen</code></a></span></dt><dt><span class="sect2"><a href="#id906792">Global Objects</a></span></dt><dt><span class="sect2"><a href="#generators">View and SubArray Generators</a></span></dt><dt><span class="sect2"><a href="#memory_layout">Memory Layout Specifiers</a></span></dt><dt><span class="sect2"><a href="#range_checking">Range Checking</a></span></dt></dl></dd></dl></div><p>Boost.MultiArray is composed of several components.
The MultiArray concept defines a generic interface to multidimensional
containers.
<code class="literal">multi_array</code> is a general purpose container class
@@ -150,8 +150,8 @@ number of possible element layouts. For example, the elements of a 2
dimensional array can be stored by row (i.e., the elements of each row
are stored contiguously) or by column (i.e., the elements of each
column are stored contiguously).
</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id834641"></a>Notation</h3></div></div></div><p>What follows are the descriptions of symbols that will be used
to describe the MultiArray interface.</p><div class="table"><a name="id834650"></a><p class="title"><b>Table 1. Notation</b></p><table summary="Notation" border="1"><colgroup><col><col></colgroup><tbody><tr><td><code class="literal">A</code></td><td>A type that is a model of MultiArray
</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id896773"></a>Notation</h3></div></div></div><p>What follows are the descriptions of symbols that will be used
to describe the MultiArray interface.</p><div class="table"><a name="id896782"></a><p class="title"><b>Table 1. Notation</b></p><div class="table-contents"><table summary="Notation" border="1"><colgroup><col><col></colgroup><tbody><tr><td><code class="literal">A</code></td><td>A type that is a model of MultiArray
</td></tr><tr><td><code class="literal">a,b</code></td><td>Objects of type <code class="literal">A</code></td></tr><tr><td><code class="literal">NumDims</code></td><td>The numeric dimension parameter associated with
<code class="literal">A</code>.</td></tr><tr><td><code class="literal">Dims</code></td><td>Some numeric dimension parameter such that
<code class="literal">0&lt;Dims&lt;NumDims</code>.
@@ -159,8 +159,8 @@ to describe the MultiArray interface.</p><div class="table"><a name="id834650"><
to <code class="literal">index_gen::operator[](index_range)</code>.</td></tr><tr><td><code class="literal">index_list</code></td><td>An object whose type models
<a href="../../utility/Collection.html" target="_top">Collection</a>
</td></tr><tr><td><code class="literal">idx</code></td><td>A signed integral value.</td></tr><tr><td><code class="literal">tmp</code></td><td>An object of type
<code class="literal">boost::array&lt;index,NumDims&gt;</code></td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id834809"></a>Associated Types</h3></div></div></div><p>
</p><div class="table"><a name="id834817"></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><code class="literal">value_type</code></td><td>This is the value type of the container.
<code class="literal">boost::array&lt;index,NumDims&gt;</code></td></tr></tbody></table></div></div><br class="table-break"></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id896941"></a>Associated Types</h3></div></div></div><p>
</p><div class="table"><a name="id896949"></a><p class="title"><b>Table 2. Associated Types</b></p><div class="table-contents"><table summary="Associated Types" border="1"><colgroup><col><col></colgroup><thead><tr><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">value_type</code></td><td>This is the value type of the container.
If <code class="literal">NumDims == 1</code>, then this is
<code class="literal">element</code>. Otherwise, this is the value type of the
immediately nested containers.
@@ -260,7 +260,9 @@ It models MultiArray.
const_array_view&lt;Dims&gt;::type</code>
</td><td>
This is the const view type with <code class="literal">Dims</code> dimensions.
</td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id835319"></a>Valid expressions</h3></div></div></div><div class="table"><a name="id835323"></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><code class="literal">a.shape()</code></td><td><code class="literal">const size_type*</code></td><td>
</td></tr></tbody></table></div></div><br class="table-break"></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id897451"></a>Valid expressions</h3></div></div></div><div class="table"><a name="id897455"></a><p class="title"><b>Table 3. Valid Expressions</b></p><div class="table-contents"><table summary="Valid Expressions" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Expression</th><th>Return type</th><th>Semantics</th></tr></thead><tbody><tr><td><code class="literal">A::dimensionality</code></td><td><code class="literal">size_type</code></td><td>This compile-time constant represents the number of
dimensions of the array (note that
<code class="literal">A::dimensionality == NumDims</code>).</td></tr><tr><td><code class="literal">a.shape()</code></td><td><code class="literal">const size_type*</code></td><td>
This returns a list of <code class="literal">NumDims</code> elements specifying the
extent of each array dimension.
</td></tr><tr><td><code class="literal">a.strides()</code></td><td><code class="literal">const index*</code></td><td>
@@ -358,11 +360,11 @@ type must model <a href="http://www.sgi.com/tech/stl/EqualityComparable.html" ta
expression to be valid.</td></tr><tr><td><code class="literal">a &gt;= b</code></td><td>bool</td><td>This performs a lexicographical comparison of the
values of <code class="literal">a</code> and <code class="literal">b</code>. The element
type must model <a href="http://www.sgi.com/tech/stl/LessThanComparable.html" target="_top">LessThanComparable</a> for this
expression to be valid.</td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id836109"></a>Complexity guarantees</h3></div></div></div><code class="literal">begin()</code> and <code class="literal">end()</code> execute in amortized
expression to be valid.</td></tr></tbody></table></div></div><br class="table-break"></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id898268"></a>Complexity guarantees</h3></div></div></div><code class="literal">begin()</code> and <code class="literal">end()</code> execute in amortized
constant time.
<code class="literal">size()</code> executes in at most linear time in the
MultiArray's size.
</div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id836133"></a>Invariants</h3></div></div></div><div class="table"><a name="id836139"></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><code class="literal">[a.begin(),a.end())</code> is a valid range.
</div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id898293"></a>Invariants</h3></div></div></div><div class="table"><a name="id898298"></a><p class="title"><b>Table 4. Invariants</b></p><div class="table-contents"><table summary="Invariants" border="1"><colgroup><col><col></colgroup><tbody><tr><td>Valid range</td><td><code class="literal">[a.begin(),a.end())</code> is a valid range.
</td></tr><tr><td>Range size</td><td>
<code class="literal">a.size() == std::distance(a.begin(),a.end());</code>.
</td></tr><tr><td>Completeness</td><td>
@@ -374,7 +376,7 @@ Calling <code class="literal">a[a1][a2]...[aN]</code> where <code class="literal
yields the same result as calling
<code class="literal">a(index_list)</code>, where <code class="literal">index_list</code>
is a <a href="../../utility/Collection.html" target="_top">Collection</a> containing the values <code class="literal">a1...aN</code>.
</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><p>The following MultiArray associated
</td></tr></tbody></table></div></div><br class="table-break"></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><p>The following MultiArray associated
types define the interface for creating views of existing
MultiArrays. Their interfaces and roles in the
concept are described below.</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="index_range"></a><code class="literal">index_range</code></h4></div></div></div><p><code class="literal">index_range</code> objects represent half-open
@@ -401,10 +403,10 @@ operators, a half open range [5,10) can be specified as follows:
The following describes the
<code class="literal">index_range</code> interface.
</p><div class="table"><a name="id836367"></a><p class="title"><b>Table 5. Notation</b></p><table summary="Notation" border="1"><colgroup><col><col></colgroup><tbody><tr><td><code class="literal">i</code></td><td>An object of type <code class="literal">index_range</code>.</td></tr><tr><td><code class="literal">idx,idx1,idx2,idx3</code></td><td>Objects of type <code class="literal">index</code>.</td></tr></tbody></table></div><div class="table"><a name="id836420"></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><code class="literal">index</code></td><td>This is a signed integral type. It is used to
</p><div class="table"><a name="id898526"></a><p class="title"><b>Table 5. Notation</b></p><div class="table-contents"><table summary="Notation" border="1"><colgroup><col><col></colgroup><tbody><tr><td><code class="literal">i</code></td><td>An object of type <code class="literal">index_range</code>.</td></tr><tr><td><code class="literal">idx,idx1,idx2,idx3</code></td><td>Objects of type <code class="literal">index</code>.</td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="id898580"></a><p class="title"><b>Table 6. Associated Types</b></p><div class="table-contents"><table summary="Associated Types" border="1"><colgroup><col><col></colgroup><thead><tr><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">index</code></td><td>This is a signed integral type. It is used to
specify the start, finish, and stride values.</td></tr><tr><td><code class="literal">size_type</code></td><td>This is an unsigned integral type. It is used to
report the size of the range an <code class="literal">index_range</code>
represents.</td></tr></tbody></table></div><div class="table"><a name="id836483"></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><code class="literal">index_range(idx1,idx2,idx3)</code></td><td><code class="literal">index_range</code></td><td>This constructs an <code class="literal">index_range</code>
represents.</td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="id898642"></a><p class="title"><b>Table 7. Valid Expressions</b></p><div class="table-contents"><table summary="Valid Expressions" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Expression</th><th>Return type</th><th>Semantics</th></tr></thead><tbody><tr><td><code class="literal">index_range(idx1,idx2,idx3)</code></td><td><code class="literal">index_range</code></td><td>This constructs an <code class="literal">index_range</code>
representing the interval <code class="literal">[idx1,idx2)</code>
with stride <code class="literal">idx3</code>.</td></tr><tr><td><code class="literal">index_range(idx1,idx2)</code></td><td><code class="literal">index_range</code></td><td>This constructs an <code class="literal">index_range</code>
representing the interval <code class="literal">[idx1,idx2)</code>
@@ -436,14 +438,14 @@ value. This notation includes
of <code class="literal">i</code> up by <code class="literal">idx</code>. It is equivalent to
<code class="literal">index_range(r.start()+idx1, r.finish()+idx, r.stride())</code></td></tr><tr><td><code class="literal">i - idx</code></td><td><code class="literal">index</code></td><td>This expression shifts the start and finish values
of <code class="literal">i</code> up by <code class="literal">idx</code>. It is equivalent to
<code class="literal">index_range(r.start()-idx1, r.finish()-idx, r.stride())</code></td></tr></tbody></table></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="index_gen"></a><code class="literal">index_gen</code></h4></div></div></div><p> <code class="literal">index_gen</code> aggregates
<code class="literal">index_range(r.start()-idx1, r.finish()-idx, r.stride())</code></td></tr></tbody></table></div></div><br class="table-break"></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="index_gen"></a><code class="literal">index_gen</code></h4></div></div></div><p> <code class="literal">index_gen</code> aggregates
<code class="literal">index_range</code> objects in order to specify view
parameters. Chained calls to <code class="literal">operator[]</code> store
range and dimension information used to
instantiate a new view into a MultiArray.
</p><div class="table"><a name="id837149"></a><p class="title"><b>Table 8. Notation</b></p><table summary="Notation" border="1"><colgroup><col><col></colgroup><tbody><tr><td><code class="literal">Dims,Ranges</code></td><td>Unsigned integral values.</td></tr><tr><td><code class="literal">x</code></td><td>An object of type
</p><div class="table"><a name="id899309"></a><p class="title"><b>Table 8. Notation</b></p><div class="table-contents"><table summary="Notation" border="1"><colgroup><col><col></colgroup><tbody><tr><td><code class="literal">Dims,Ranges</code></td><td>Unsigned integral values.</td></tr><tr><td><code class="literal">x</code></td><td>An object of type
<code class="literal">template gen_type&lt;Dims,Ranges&gt;::type</code>.</td></tr><tr><td><code class="literal">i</code></td><td>An object of type
<code class="literal">index_range</code>.</td></tr><tr><td><code class="literal">idx</code></td><td>Objects of type <code class="literal">index</code>.</td></tr></tbody></table></div><div class="table"><a name="id837235"></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><code class="literal">index</code></td><td>This is a signed integral type. It is used to
<code class="literal">index_range</code>.</td></tr><tr><td><code class="literal">idx</code></td><td>Objects of type <code class="literal">index</code>.</td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="id899395"></a><p class="title"><b>Table 9. Associated Types</b></p><div class="table-contents"><table summary="Associated Types" border="1"><colgroup><col><col></colgroup><thead><tr><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">index</code></td><td>This is a signed integral type. It is used to
specify degenerate dimensions.</td></tr><tr><td><code class="literal">size_type</code></td><td>This is an unsigned integral type. It is used to
report the size of the range an <code class="literal">index_range</code>
represents.</td></tr><tr><td>
@@ -454,7 +456,7 @@ represents.</td></tr><tr><td>
degenerate ranges specified (i.e. calls to
<code class="literal">operator[](index)</code>). Note that
<code class="classname">index_gen</code> and
<code class="classname">gen_type&lt;0,0&gt;::type</code> are the same type.</td></tr></tbody></table></div><div class="table"><a name="id837347"></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><code class="literal">index_gen()</code></td><td><code class="literal">gen_type&lt;0,0&gt;::type</code></td><td>This constructs an <code class="literal">index_gen</code>
<code class="classname">gen_type&lt;0,0&gt;::type</code> are the same type.</td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="id899506"></a><p class="title"><b>Table 10. Valid Expressions</b></p><div class="table-contents"><table summary="Valid Expressions" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Expression</th><th>Return type</th><th>Semantics</th></tr></thead><tbody><tr><td><code class="literal">index_gen()</code></td><td><code class="literal">gen_type&lt;0,0&gt;::type</code></td><td>This constructs an <code class="literal">index_gen</code>
object. This object can then be used to generate tuples of
<code class="literal">index_range</code> values.</td></tr><tr><td><code class="literal">x[i]</code></td><td><code class="literal">gen_type&lt;Dims+1,Ranges+1&gt;::type</code>
</td><td>Returns a new object containing all previous
@@ -468,7 +470,7 @@ range, <code class="literal">index_range(idx,idx).</code> Note that this is NOT
equivalent to <code class="literal">x[index_range(idx,idx)].</code>, which will
return an object of type
<code class="literal">gen_type&lt;Dims+1,Ranges+1&gt;::type</code>.
</td></tr></tbody></table></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id837503"></a>Models</h3></div></div></div><div class="itemizedlist"><ul type="disc"><li><code class="literal">multi_array</code></li><li><code class="literal">multi_array_ref</code></li><li><code class="literal">const_multi_array_ref</code></li><li><code class="literal">template array_view&lt;Dims&gt;::type</code></li><li><code class="literal">template const_array_view&lt;Dims&gt;::type</code></li><li><code class="literal">template subarray&lt;Dims&gt;::type</code></li><li><code class="literal">template const_subarray&lt;Dims&gt;::type</code></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><p>
</td></tr></tbody></table></div></div><br class="table-break"></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id899663"></a>Models</h3></div></div></div><div class="itemizedlist"><ul type="disc"><li><code class="literal">multi_array</code></li><li><code class="literal">multi_array_ref</code></li><li><code class="literal">const_multi_array_ref</code></li><li><code class="literal">template array_view&lt;Dims&gt;::type</code></li><li><code class="literal">template const_array_view&lt;Dims&gt;::type</code></li><li><code class="literal">template subarray&lt;Dims&gt;::type</code></li><li><code class="literal">template const_subarray&lt;Dims&gt;::type</code></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><p>
Boost.MultiArray defines an array class,
<code class="literal">multi_array</code>, and two adapter classes,
<code class="literal">multi_array_ref</code> and
@@ -813,8 +815,7 @@ not described in the <code class="literal">multi_array</code> reference.
namespace boost {
template &lt;typename ValueType,
std::size_t NumDims,
typename Allocator = std::allocator&lt;ValueType&gt; &gt;
std::size_t NumDims&gt;
class multi_array_ref {
public:
// types:
@@ -973,7 +974,7 @@ namespace boost {
template &lt;typename ValueType,
std::size_t NumDims,
typename Allocator = std::allocator&lt;ValueType&gt; &gt;
typename TPtr = const T*&gt;
class const_multi_array_ref {
public:
// types:
@@ -1004,9 +1005,9 @@ public:
// structors
template &lt;typename ExtentList&gt;
explicit const_multi_array_ref(const element* data, const ExtentList&amp; sizes,
explicit const_multi_array_ref(TPtr data, const ExtentList&amp; sizes,
const storage_order_type&amp; store = c_storage_order());
explicit const_multi_array_ref(const element* data, const extents_tuple&amp; ranges,
explicit const_multi_array_ref(TPtr data, const extents_tuple&amp; ranges,
const storage_order_type&amp; store = c_storage_order());
const_multi_array_ref(const const_multi_array_ref&amp; x);
~const_multi_array_ref();
@@ -1054,7 +1055,7 @@ public:
};
</pre><p><b>Constructors. </b></p><div class="variablelist"><dl><dt><span class="term"><pre class="programlisting">template &lt;typename ExtentList&gt;
explicit const_multi_array_ref(const element* data,
explicit const_multi_array_ref(TPtr data,
const ExtentList&amp; sizes,
const storage_order&amp; store = c_storage_order());
</pre></span></dt><dd><p>
@@ -1066,7 +1067,7 @@ dimensions.
</p><p><b><code class="literal">ExtentList</code> Requirements. </b>
<code class="literal">ExtentList</code> must model <a href="../../utility/Collection.html" target="_top">Collection</a>.
</p><p><b>Preconditions. </b><code class="literal">sizes.size() == NumDims;</code></p></dd><dt><span class="term">
<pre class="programlisting">explicit const_multi_array_ref(const element* data,
<pre class="programlisting">explicit const_multi_array_ref(TPtr data,
extent_gen::gen_type&lt;NumDims&gt;::type ranges,
const storage_order&amp; store = c_storage_order());
</pre></span></dt><dd><p><b>Effects. </b>
@@ -1171,7 +1172,7 @@ operator[](index idx) const;</code></span></dt><dd><p>This function returns a ne
<code class="classname">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" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id862083"></a>Global Objects</h3></div></div></div><p>For syntactic convenience, Boost.MultiArray defines two
declaration.</p></dd></dl></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id906792"></a>Global Objects</h3></div></div></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.

15
doc/test_cases.html
View File

@@ -114,6 +114,13 @@ Test re-indexing functionality for the B.M primary components.
</td>
</tr>
<tr>
<td><a href="../test/storage_order_convert.cpp">libs/multi_array/test/storage_order_convert.cpp</a></td>
<td>
Test out conversions among the storage orders data types.
</td>
</tr>
<tr>
<td><a href="../test/storage_order.cpp">libs/multi_array/test/storage_order.cpp</a></td>
<td>
@@ -164,6 +171,14 @@ Ensure that all the array types meet the defined Concepts.
</td>
</tr>
<tr>
<td><a href="../test/assert.cpp">libs/multi_array/test/assert.cpp</a></td>
<td>
Ensure that uses of BOOST_ASSERT within the library can be customized
by library users.
</td>
</tr>
<tr>
<td><a href="../test/generative_tests.hpp">libs/multi_array/test/generative_tests.hpp</a></td>
<td>

44
doc/user.html
View File

@@ -255,7 +255,9 @@ useful for writing dimension-independent code.
</blockquote>
<p>The second method involves passing the constructor an <tt>extent_gen</tt>
object, specifying the matrix dimensions. By default, the library constructs a
object, specifying the matrix dimensions. The <tt>extent_gen</tt> type
is defined in the <tt>multi_array_types</tt> namespace and as a
member of every array type, but by default, the library constructs a
global <tt>extent_gen</tt> object <tt>boost::extents</tt>. In case of
concern about memory used by these objects, defining
<tt>BOOST_MULTI_ARRAY_NO_GENERATORS</tt> before including the library
@@ -316,13 +318,17 @@ already existing array component. It allows you to create a sub-view that
retains the same number of dimensions as the original array or one
that has less dimensions than the original as well.
<p>Sub-view creation occurs by placing a call to operator[], passing it
an <tt>index_gen</tt> type. The <tt>index_gen</tt> is populated by
passing <tt>index_range</tt> objects to its <tt>operator[]</tt>.
Similar to <tt>boost::extents</tt>, the library by default constructs
the object <tt>boost::indices</tt>. You can suppress this object
by defining <tt>BOOST_MULTI_ARRAY_NO_GENERATORS</tt> before
including the library header. A simple sub-view creation example follows.
<p>Sub-view creation occurs by placing a call to operator[], passing
it an <tt>index_gen</tt> type. The <tt>index_gen</tt> is populated by
passing <tt>index_range</tt> objects to its <tt>operator[]</tt>.
The <tt>index_range</tt> and <tt>index_gen</tt> types are defined in
the <tt>multi_array_types</tt> namespace and as nested members of
every array type. Similar to <tt>boost::extents</tt>, the library by
default constructs the object <tt>boost::indices</tt>. You can
suppress this object by
defining <tt>BOOST_MULTI_ARRAY_NO_GENERATORS</tt> before including the
library header. A simple sub-view creation example follows.
<h3>Example</h3>
<blockquote>
<pre>
@@ -335,7 +341,8 @@ including the library header. A simple sub-view creation example follows.
// dim 2: [0,4) (strided by 2),
//
typedef array_type::index_range range;
typedef boost::multi_array_types::index_range range;
// OR typedef array_type::index_range range;
array_type::array_view&lt;3&gt;::type myview =
myarray[ boost::indices[range(0,2)][range(1,3)][range(0,4,2)] ];
@@ -361,7 +368,7 @@ called slicing).
// [0,1,2), 1, [0,2,4)
//
typedef array_type::index_range range;
typedef boost::multi_array_types::index_range range;
array_type::index_gen indices;
array_type::array_view&lt;2&gt;::type myview =
myarray[ indices[range(0,2)][1][range(0,4,2)] ];
@@ -382,7 +389,7 @@ that specify the same range.
// [base,stride,bound)
// [0,2,4)
typedef array_type::index_range range;
typedef boost::multi_array_types::index_range range;
range a_range;
a_range = range(0,4,2);
a_range = range().start(0).finish(4).stride(2);
@@ -402,7 +409,7 @@ dimension it is used to specify.
<h3>Example</h3>
<blockquote>
<pre>
typedef array_type::index_range range;
typedef boost::multi_array_types::index_range range;
range a_range;
// All elements in this dimension
@@ -482,13 +489,16 @@ stored in ascending or descending order.
In some situations, it may be inconvenient or awkward to use an
array that is zero-based.
the Boost.MultiArray components provide two facilities for changing the
bases of an array. One may specify a pair of range values to
the extent_gen constructor in order to set the base value.
bases of an array. One may specify a pair of range values, with
the <tt>extent_range</tt> type, to
the <tt>extent_gen</tt> constructor in order to set the base value.
<h3>Example</h3>
<blockquote>
<pre>
typedef boost::multi_array&lt;double, 3&gt; array_type;
typedef array_type::extent_range range;
typedef boost::multi_array_types::extent_range range;
// OR typedef array_type::extent_range range;
array_type::extent_gen extents;
@@ -507,7 +517,6 @@ reset the bases. To set all bases to the same value, use the
<blockquote>
<pre>
typedef boost::multi_array&lt;double, 3&gt; array_type;
typedef array_type::extent_range range;
array_type::extent_gen extents;
@@ -524,7 +533,6 @@ An alternative is to set each base separately using the
<blockquote>
<pre>
typedef boost::multi_array&lt;double, 3&gt; array_type;
typedef array_type::extent_range range;
array_type::extent_gen extents;
@@ -548,7 +556,6 @@ elements contained remains the same.
<blockquote>
<pre>
typedef boost::multi_array&lt;double, 3&gt; array_type;
typedef array_type::extent_range range;
array_type::extent_gen extents;
array_type A(extents[2][3][4]);
@@ -577,7 +584,6 @@ no longer be available.
<blockquote>
<pre>
typedef boost::multi_array&lt;int, 3&gt; array_type;
typedef array_type::extent_range range;
array_type::extent_gen extents;
array_type A(extents[3][3][3]);

7
doc/xml/MultiArray.xml
View File

@@ -385,6 +385,13 @@ This is the const view type with <literal>Dims</literal> dimensions.
</row>
</thead>
<tbody>
<row>
<entry><literal>A::dimensionality</literal></entry>
<entry><literal>size_type</literal></entry>
<entry>This compile-time constant represents the number of
dimensions of the array (note that
<literal>A::dimensionality == NumDims</literal>).</entry>
</row>
<row>
<entry><literal>a.shape()</literal></entry>
<entry><literal>const size_type*</literal></entry>

10
doc/xml/const_multi_array_ref.xml
View File

@@ -33,7 +33,7 @@ namespace boost {
template <typename ValueType,
std::size_t NumDims,
typename Allocator = std::allocator<ValueType> >
typename TPtr = const T*>
class const_multi_array_ref {
public:
// types:
@@ -64,9 +64,9 @@ public:
// structors
template <typename ExtentList>
explicit const_multi_array_ref(const element* data, const ExtentList& sizes,
explicit const_multi_array_ref(TPtr data, const ExtentList& sizes,
const storage_order_type& store = c_storage_order());
explicit const_multi_array_ref(const element* data, const extents_tuple& ranges,
explicit const_multi_array_ref(TPtr data, const extents_tuple& ranges,
const storage_order_type& store = c_storage_order());
const_multi_array_ref(const const_multi_array_ref& x);
~const_multi_array_ref();
@@ -122,7 +122,7 @@ public:
<variablelist>
<varlistentry>
<term><programlisting>template &lt;typename ExtentList&gt;
explicit const_multi_array_ref(const element* data,
explicit const_multi_array_ref(TPtr data,
const ExtentList&amp; sizes,
const storage_order&amp; store = c_storage_order());
</programlisting></term>
@@ -151,7 +151,7 @@ dimensions.
<varlistentry>
<term>
<programlisting><![CDATA[explicit const_multi_array_ref(const element* data,
<programlisting><![CDATA[explicit const_multi_array_ref(TPtr data,
extent_gen::gen_type<NumDims>::type ranges,
const storage_order& store = c_storage_order());]]>
</programlisting></term>

21
doc/xml/multi_array_ref.xml
View File

@@ -31,27 +31,26 @@ not described in the <literal>multi_array</literal> reference.
namespace boost {
template <typename ValueType,
std::size_t NumDims,
typename Allocator = std::allocator<ValueType> >
std::size_t NumDims>
class multi_array_ref {
public:
// types:
typedef ValueType element;
typedef *implementation-defined* value_type;
typedef *implementation-defined* reference;
typedef *implementation-defined* const_reference;
typedef *implementation-defined* difference_type;
typedef *implementation-defined* iterator;
typedef *implementation-defined* const_iterator;
typedef *implementation-defined* reverse_iterator;
typedef *implementation-defined* const_reverse_iterator;
typedef *unspecified* value_type;
typedef *unspecified* reference;
typedef *unspecified* const_reference;
typedef *unspecified* difference_type;
typedef *unspecified* iterator;
typedef *unspecified* const_iterator;
typedef *unspecified* reverse_iterator;
typedef *unspecified* const_reverse_iterator;
typedef multi_array_types::size_type size_type;
typedef multi_array_types::index index;
typedef multi_array_types::index_gen index_gen;
typedef multi_array_types::index_range index_range;
typedef multi_array_types::extent_gen extent_gen;
typedef multi_array_types::extent_range extent_range;
typedef *implementation-defined* storage_order_type;
typedef *unspecified* storage_order_type;
// template typedefs
template <std::size_t Dims> struct subarray;

2
test/Jamfile.v2
View File

@@ -37,11 +37,13 @@ test-suite multi_array
[ run assign.cpp ../../test/build//boost_test_exec_monitor ]
[ run assign_to_array.cpp ../../test/build//boost_test_exec_monitor ]
[ run index_bases.cpp ../../test/build//boost_test_exec_monitor ]
[ run storage_order_convert.cpp ../../test/build//boost_test_exec_monitor ]
[ run storage_order.cpp ../../test/build//boost_test_exec_monitor ]
[ run reshape.cpp ../../test/build//boost_test_exec_monitor ]
[ run range1.cpp ../../test/build//boost_test_exec_monitor ]
[ run idxgen1.cpp ../../test/build//boost_test_exec_monitor ]
[ run stl_interaction.cpp ../../test/build//boost_test_exec_monitor ]
[ run resize.cpp ../../test/build//boost_test_exec_monitor ]
[ run assert.cpp ../../test/build//boost_test_exec_monitor ]
[ compile concept_checks.cpp ]
;

51
test/assert.cpp Normal file
View File

@@ -0,0 +1,51 @@
// Copyright 2007 The Trustees of Indiana University.
// Use, modification and distribution is subject to the Boost Software
// License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
// http://www.boost.org/LICENSE_1_0.txt)
// Boost.MultiArray Library
// Authors: Ronald Garcia
// Jeremy Siek
// Andrew Lumsdaine
// See http://www.boost.org/libs/multi_array for documentation.
//
// Using the BOOST.ASSERT mechanism to replace library assertions
// with exceptions
//
#include "boost/test/minimal.hpp"
#define BOOST_ENABLE_ASSERT_HANDLER
#include "boost/multi_array.hpp" // includes assert.hpp
#include <stdexcept>
namespace boost {
void assertion_failed(char const* expr, char const* function,
char const* file, long line) {
throw std::runtime_error(expr);
}
} // namespace boost
using namespace boost;
int
test_main(int,char*[]) {
typedef multi_array<int,2> array_t;
array_t A(extents[2][2]);
array_t B(extents[3][3]);
try {
A = B;
BOOST_ERROR("did not throw an exception");
} catch (std::runtime_error&) {
//...all good
}
return boost::exit_success;
}

4
test/concept_checks.cpp
View File

@@ -20,8 +20,8 @@
#include "boost/multi_array.hpp"
#include "boost/cstdlib.hpp"
#define BOOST_INCLUDE_MAIN
#include "boost/test/test_tools.hpp"
#include "boost/test/minimal.hpp"
#include "boost/array.hpp"

8
test/resize.cpp
View File

@@ -114,6 +114,14 @@ int test_main(int,char*[]) {
}
}
// Resizing that changes index bases too (impl bug caused an assert)
{
typedef boost::multi_array<int, 1> ar_t;
typedef ar_t::extent_range range;
ar_t ar;
ar.resize(boost::extents[range(-3, 3)]);
}
return boost::exit_success;
}

22
test/slice.cpp
View File

@@ -90,6 +90,28 @@ void test_views(Array& A, const ViewTraits&) {
BOOST_CHECK(B(elmts) == A[idx0+i][idx1+1][idx2+j*2]);
}
}
// Flip the third dimension
{
typename ViewTraits::array_view3 B = A[
indices[range(idx0+0,idx0+2)]
[range(idx1+0,idx1+2)]
[range(idx2+2,idx2+0,-1)]
];
// typename ViewTraits::array_view3 B =
// A[indices[range(idx0+0,idx0+2)][idx1+1][range(idx2+0,idx2+4,2)]];
for (index i = 0; i != 2; ++i)
for (index j = 0; j != 2; ++j)
for (index k = 0; k != 2; ++k) {
BOOST_CHECK(B[i][j][k] == A[idx0+i][idx1+j][idx2+2-k]);
boost::array<index,3> elmts;
elmts[0]=i; elmts[1]=j; elmts[2]=k;
BOOST_CHECK(B(elmts) == A[idx0+i][idx1+j][idx2+2-k]);
}
}
++tests_run;
}

6
test/storage_order_convert.cpp
View File

@@ -31,9 +31,9 @@ test_main(int,char*[]) {
general_storage_order<5> fortran_storage(fortran_ordering.begin(),
ascending.begin());
BOOST_TEST(c_storage == (general_storage_order<5>) c_storage_order());
BOOST_TEST(fortran_storage ==
BOOST_CHECK(c_storage == (general_storage_order<5>) c_storage_order());
BOOST_CHECK(fortran_storage ==
(general_storage_order<5>) fortran_storage_order());
return boost::report_errors();
return boost::exit_success;
}