fixed a typo.

[SVN r25727]
This commit is contained in:
Ronald Garcia 2004-10-14 14:24:17 +00:00
parent e46df1945b
commit e4e242bf4f

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.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="id800084"></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="#id800530">Notation</a></span></dt><dt><span class="sect2"><a href="#id800698">Associated Types</a></span></dt><dt><span class="sect2"><a href="#id801197">Valid expressions</a></span></dt><dt><span class="sect2"><a href="#id801966">Complexity guarantees</a></span></dt><dt><span class="sect2"><a href="#id801990">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="#id803337">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="#id828246">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.
<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.
The MultiArray concept defines a generic interface to multidimensional
containers.
<tt class="literal">multi_array</tt> is a general purpose container class
@ -121,7 +121,7 @@ occurs when a single-index is specified to
</pre><p>
has a degenerate second dimension. The view generated from the above
specification will have 2 dimensions with shape <tt class="literal">5 x 2</tt>.
specification will have 2 dimensions with shape <tt class="literal">5 x 4</tt>.
If the "<tt class="literal">2</tt>" above were replaced with
another <tt class="literal">index_range</tt> object, for example:
@ -150,16 +150,16 @@ 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="id800530"></a>Notation</h3></div></div><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="id800540"></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
</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
to 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
</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
<tt class="literal">A</tt>.</td></tr><tr><td><tt class="literal">Dims</tt></td><td>Some numeric dimension parameter such that
<tt class="literal">0&lt;Dims&lt;NumDims</tt>.
</td></tr><tr><td><tt class="literal">indices</tt></td><td>An object created by some number of chained calls
to <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
<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
<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="id800698"></a>Associated Types</h3></div></div><div></div></div><p>
</p><div class="table"><a name="id800706"></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.
<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>
</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.
If <tt class="literal">NumDims == 1</tt>, then this is
<tt class="literal">element</tt>. Otherwise, this is the value type of the
immediately nested containers.
@ -228,7 +228,7 @@ It models MultiArray.
</td></tr><tr><td><tt class="literal">template
const_array_view&lt;Dims&gt;::type</tt></td><td>
This is the const view type with <tt class="literal">Dims</tt> dimensions.
</td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id801197"></a>Valid expressions</h3></div></div><div></div></div><div class="table"><a name="id801201"></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>
</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>
This returns a list of <tt class="literal">NumDims</tt> elements specifying the
extent of each array dimension.
</td></tr><tr><td><tt class="literal">a.strides()</tt></td><td><tt class="literal">const index*</tt></td><td>
@ -315,11 +315,11 @@ type must model <a href="http://www.sgi.com/tech/stl/EqualityComparable.html" ta
expression 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
values of <tt class="literal">a</tt> and <tt class="literal">b</tt>. 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="id801966"></a>Complexity guarantees</h3></div></div><div></div></div><tt class="literal">begin()</tt> and <tt class="literal">end()</tt> execute in amortized
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="id833954"></a>Complexity guarantees</h3></div></div><div></div></div><tt class="literal">begin()</tt> and <tt class="literal">end()</tt> execute in amortized
constant time.
<tt class="literal">size()</tt> 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="id801990"></a>Invariants</h3></div></div><div></div></div><div class="table"><a name="id801996"></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.
</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.
</td></tr><tr><td>Range size</td><td><tt class="literal">a.size() == std::distance(a.begin(),a.end());</tt>.
</td></tr><tr><td>Completeness</td><td>
Iteration through the range
@ -357,10 +357,10 @@ operators, a half open range [5,10) can be specified as follows:
The following describes the
<tt class="literal">index_range</tt> interface.
</p><div class="table"><a name="id802217"></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="id802270"></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
</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
specify 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
report the size of the range an <tt class="literal">index_range</tt>
represents.</td></tr></tbody></table></div><div class="table"><a name="id802332"></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>
represents.</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>
representing the interval <tt class="literal">[idx1,idx2)</tt>
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>
representing the interval <tt class="literal">[idx1,idx2)</tt>
@ -397,9 +397,9 @@ of <tt class="literal">i</tt> up by <tt class="literal">idx</tt>. It is equivale
parameters. Chained calls to <tt class="literal">operator[]</tt> store
range and dimension information used to
instantiate a new view into a MultiArray.
</p><div class="table"><a name="id802987"></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
</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
<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
<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="id803073"></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
<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
specify degenerate dimensions.</td></tr><tr><td><tt class="literal">size_type</tt></td><td>This is an unsigned integral type. It is used to
report the size of the range an <tt class="literal">index_range</tt>
represents.</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
@ -409,7 +409,7 @@ represents.</td></tr><tr><td><tt class="literal">template gen_type::&lt;Dims,Ran
degenerate ranges specified (i.e. calls to
<tt class="literal">operator[](index)</tt>). Note that
<tt class="classname">index_gen</tt> and
<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="id803184"></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>
<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>
object. This object can then be used to generate tuples of
<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
<tt class="classname">index_range</tt> objects in addition to
@ -421,7 +421,7 @@ range, <tt class="literal">index_range(idx,idx).</tt> Note that this is NOT
equivalent to <tt class="literal">x[index_range(idx,idx)].</tt>, which will
return an object of type
<tt class="literal">gen_type&lt;Dims+1,Ranges+1&gt;::type</tt>.
</td></tr></tbody></table></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id803337"></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>
</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>
Boost.MultiArray defines an array class,
<tt class="literal">multi_array</tt>, and two adapter classes,
<tt class="literal">multi_array_ref</tt> and
@ -1117,7 +1117,7 @@ operator[](index idx) const;</tt></span></dt><dd><p>This function returns a new
<tt class="classname">extent_range</tt> objects in addition to
<tt class="literal">extent_range(0,idx).</tt> 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="id828246"></a>Global Objects</h3></div></div><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="id860298"></a>Global Objects</h3></div></div><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.