mirror of
https://github.com/boostorg/multi_array.git
synced 2025-05-11 21:33:52 +00:00
Moved Collection.html into utility library directory.
[SVN r15255]
This commit is contained in:
Ronald Garcia
parent
94aa7038b4
commit
8f43d47777
@ -1,648 +0,0 @@
|
||||
<HTML>
|
||||
<!--
|
||||
-- Copyright (c) Jeremy Siek 2000
|
||||
--
|
||||
-- Permission to use, copy, modify, distribute and sell this software
|
||||
-- and its documentation for any purpose is hereby granted without fee,
|
||||
-- provided that the above copyright notice appears in all copies and
|
||||
-- that both that copyright notice and this permission notice appear
|
||||
-- in supporting documentation. Silicon Graphics makes no
|
||||
-- representations about the suitability of this software for any
|
||||
-- purpose. It is provided "as is" without express or implied warranty.
|
||||
-->
|
||||
<Head>
|
||||
<Title>Collection</Title>
|
||||
</HEAD>
|
||||
|
||||
<BODY BGCOLOR="#ffffff" LINK="#0000ee" TEXT="#000000" VLINK="#551a8b"
|
||||
ALINK="#ff0000">
|
||||
<h1>
|
||||
<img src="../../../c++boost.gif" alt="boost logo"
|
||||
width="277" align="middle" height="86">
|
||||
<br>Collection
|
||||
</h1>
|
||||
|
||||
<h3>Description</h3>
|
||||
|
||||
A Collection is a <i>concept</i> similar to the STL <a
|
||||
href="http://www.sgi.com/Technology/STL/Container.html">Container</a>
|
||||
concept. A Collection provides iterators for accessing a range of
|
||||
elements and provides information about the number of elements in the
|
||||
Collection. However, a Collection has fewer requirements than a
|
||||
Container. The motivation for the Collection concept is that there are
|
||||
many useful Container-like types that do not meet the full
|
||||
requirements of Container, and many algorithms that can be written
|
||||
with this reduced set of requirements. To summarize the reduction
|
||||
in requirements:
|
||||
|
||||
<UL>
|
||||
<LI>It is not required to "own" its elements: the lifetime
|
||||
of an element in a Collection does not have to match the lifetime of
|
||||
the Collection object, though the lifetime of the element should cover
|
||||
the lifetime of the Collection object.
|
||||
<LI>The semantics of copying a Collection object is not defined (it
|
||||
could be a deep or shallow copy or not even support copying).
|
||||
<LI>The associated reference type of a Collection does
|
||||
not have to be a real C++ reference.
|
||||
</UL>
|
||||
|
||||
|
||||
Because of the reduced requirements, some care must be taken when
|
||||
writing code that is meant to be generic for all Collection types.
|
||||
In particular, a Collection object should be passed by-reference
|
||||
since assumptions can not be made about the behaviour of the
|
||||
copy constructor.
|
||||
|
||||
<p>
|
||||
|
||||
<h3>Associated types</h3>
|
||||
|
||||
<Table border>
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
Value type
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>X::value_type</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
The type of the object stored in a Collection.
|
||||
If the Collection is <i>mutable</i> then
|
||||
the value type must be <A
|
||||
href="http://www.sgi.com/Technology/STL/Assignable.html">Assignable</A>.
|
||||
Otherwise the value type must be <a href="./CopyConstructible.html">CopyConstructible</a>.
|
||||
</TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
Iterator type
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>X::iterator</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
The type of iterator used to iterate through a Collection's
|
||||
elements. The iterator's value type is expected to be the
|
||||
Collection's value type. A conversion
|
||||
from the iterator type to the const iterator type must exist.
|
||||
The iterator type must be an <A href="http://www.sgi.com/Technology/STL/InputIterator.html">InputIterator</A>.
|
||||
</TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
Const iterator type
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>X::const_iterator</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
A type of iterator that may be used to examine, but not to modify,
|
||||
a Collection's elements.
|
||||
</TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
Reference type
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>X::reference</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
A type that behaves like a reference to the Collection's value type.
|
||||
<a href="#1">[1]</a>
|
||||
</TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
Const reference type
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>X::const_reference</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
A type that behaves like a const reference to the Collection's value type.
|
||||
</TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
Pointer type
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>X::pointer</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
A type that behaves as a pointer to the Collection's value type.
|
||||
</TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
Distance type
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>X::difference_type</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
A signed integral type used to represent the distance between two
|
||||
of the Collection's iterators. This type must be the same as
|
||||
the iterator's distance type.
|
||||
</TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
Size type
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>X::size_type</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
An unsigned integral type that can represent any nonnegative value
|
||||
of the Collection's distance type.
|
||||
</TD>
|
||||
</tr>
|
||||
</table>
|
||||
<h3>Notation</h3>
|
||||
<Table>
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
<tt>X</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
A type that is a model of Collection.
|
||||
</TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
<tt>a</tt>, <tt>b</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
Object of type <tt>X</tt>.
|
||||
</TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
<tt>T</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
The value type of <tt>X</tt>.
|
||||
</TD>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h3>Valid expressions</h3>
|
||||
|
||||
The following expressions must be valid.
|
||||
<p>
|
||||
|
||||
<Table border>
|
||||
<TR>
|
||||
<TH>
|
||||
Name
|
||||
</TH>
|
||||
<TH>
|
||||
Expression
|
||||
</TH>
|
||||
<TH>
|
||||
Return type
|
||||
</TH>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
Beginning of range
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a.begin()</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>iterator</tt> if <tt>a</tt> is mutable, <tt>const_iterator</tt> otherwise
|
||||
</TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
End of range
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a.end()</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>iterator</tt> if <tt>a</tt> is mutable, <tt>const_iterator</tt> otherwise
|
||||
</TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
Size
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a.size()</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>size_type</tt>
|
||||
</TD>
|
||||
</TR>
|
||||
<!--
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
Maximum size
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a.max_size()</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>size_type</tt>
|
||||
</TD>
|
||||
</TR>
|
||||
<TR>
|
||||
-->
|
||||
<TD VAlign=top>
|
||||
Empty Collection
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a.empty()</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
Convertible to <tt>bool</tt>
|
||||
</TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
Swap
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a.swap(b)</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>void</tt>
|
||||
</TD>
|
||||
</tr>
|
||||
</table>
|
||||
<h3>Expression semantics</h3>
|
||||
|
||||
<Table border>
|
||||
<TR>
|
||||
<TH>
|
||||
Name
|
||||
</TH>
|
||||
<TH>
|
||||
Expression
|
||||
</TH>
|
||||
<TH>
|
||||
Semantics
|
||||
</TH>
|
||||
<TH>
|
||||
Postcondition
|
||||
</TH>
|
||||
</TR>
|
||||
<TD VAlign=top>
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
Beginning of range
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a.begin()</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
Returns an iterator pointing to the first element in the Collection.
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a.begin()</tt> is either dereferenceable or past-the-end. It is
|
||||
past-the-end if and only if <tt>a.size() == 0</tt>.
|
||||
</TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
End of range
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a.end()</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
Returns an iterator pointing one past the last element in the
|
||||
Collection.
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a.end()</tt> is past-the-end.
|
||||
</TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
Size
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a.size()</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
Returns the size of the Collection, that is, its number of elements.
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a.size() >= 0
|
||||
</TD>
|
||||
</TR>
|
||||
<!--
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
Maximum size
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a.max_size()</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
Returns the largest size that this Collection can ever have. <A href="#8">[8]</A>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a.max_size() >= 0 && a.max_size() >= a.size()</tt>
|
||||
</TD>
|
||||
</TR>
|
||||
-->
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
Empty Collection
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a.empty()</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
Equivalent to <tt>a.size() == 0</tt>. (But possibly faster.)
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
|
||||
</TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
Swap
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a.swap(b)</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
Equivalent to <tt>swap(a,b)</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
|
||||
</TD>
|
||||
</tr>
|
||||
</table>
|
||||
<h3>Complexity guarantees</h3>
|
||||
|
||||
<tt>begin()</tt> and <tt>end()</tt> are amortized constant time.
|
||||
<P>
|
||||
<tt>size()</tt> is at most linear in the Collection's
|
||||
size. <tt>empty()</tt> is amortized constant time.
|
||||
<P>
|
||||
<tt>swap()</tt> is at most linear in the size of the two collections.
|
||||
<h3>Invariants</h3>
|
||||
<Table border>
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
Valid range
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
For any Collection <tt>a</tt>, <tt>[a.begin(), a.end())</tt> is a valid
|
||||
range.
|
||||
</TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
Range size
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a.size()</tt> is equal to the distance from <tt>a.begin()</tt> to <tt>a.end()</tt>.
|
||||
</TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
Completeness
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
An algorithm that iterates through the range <tt>[a.begin(), a.end())</tt>
|
||||
will pass through every element of <tt>a</tt>.
|
||||
</TD>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
|
||||
<h3>Models</h3>
|
||||
<UL>
|
||||
<LI> <tt>array</tt>
|
||||
<LI> <tt>array_ptr</tt>
|
||||
<LI> <tt>vector<bool></tt>
|
||||
</UL>
|
||||
|
||||
|
||||
<h3>Collection Refinements</h3>
|
||||
|
||||
There are quite a few concepts that refine the Collection concept,
|
||||
similar to the concepts that refine the Container concept. Here
|
||||
is a brief overview of the refining concepts.
|
||||
|
||||
<h4>ForwardCollection</h4>
|
||||
The elements are arranged in some order that
|
||||
does not change spontaneously from one iteration to the next. As
|
||||
a result, a ForwardCollection is
|
||||
<A
|
||||
href="http://www.sgi.com/Technology/STL/EqualityComparable.html">EqualityComparable</A>
|
||||
and
|
||||
<A
|
||||
href="http://www.sgi.com/Technology/STL/LessThanComparable.html">LessThanComparable</A>.
|
||||
In addition, the iterator type of a ForwardCollection is a
|
||||
MultiPassInputIterator which is just an InputIterator with the added
|
||||
requirements that the iterator can be used to make multiple passes
|
||||
through a range, and that if <tt>it1 == it2</tt> and <tt>it1</tt> is
|
||||
dereferenceable then <tt>++it1 == ++it2</tt>. The ForwardCollection
|
||||
also has a <tt>front()</tt> method.
|
||||
|
||||
<p>
|
||||
<Table border>
|
||||
<TR>
|
||||
<TH>
|
||||
Name
|
||||
</TH>
|
||||
<TH>
|
||||
Expression
|
||||
</TH>
|
||||
<TH>
|
||||
Return type
|
||||
</TH>
|
||||
<TH>
|
||||
Semantics
|
||||
</TH>
|
||||
</TR>
|
||||
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
Font
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a.front()</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>reference</tt> if <tt>a</tt> is mutable, <br> <tt>const_reference</tt>
|
||||
otherwise.
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
Equivalent to <tt>*(a.first())</tt>.
|
||||
</TD>
|
||||
</TR>
|
||||
|
||||
</table>
|
||||
|
||||
|
||||
<h4>ReversibleCollection</h4>
|
||||
|
||||
The container provides access to iterators that traverse in both
|
||||
directions (forward and reverse). The iterator type must meet all of
|
||||
the requirements of
|
||||
<a href="http://www.sgi.com/Technology/STL/BidirectionalIterator.html">BidirectionalIterator</a>
|
||||
except that the reference type does not have to be a real C++
|
||||
reference. The ReversibleCollection adds the following requirements
|
||||
to those of ForwardCollection.
|
||||
<p>
|
||||
|
||||
<Table border>
|
||||
<TR>
|
||||
<TH>
|
||||
Name
|
||||
</TH>
|
||||
<TH>
|
||||
Expression
|
||||
</TH>
|
||||
<TH>
|
||||
Return type
|
||||
</TH>
|
||||
<TH>
|
||||
Semantics
|
||||
</TH>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
Beginning of range
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a.rbegin()</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>reverse_iterator</tt> if <tt>a</tt> is mutable,
|
||||
<tt>const_reverse_iterator</tt> otherwise.
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
Equivalent to <tt>X::reverse_iterator(a.end())</tt>.
|
||||
</TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
End of range
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a.rend()</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>reverse_iterator</tt> if <tt>a</tt> is mutable,
|
||||
<tt>const_reverse_iterator</tt> otherwise.
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
Equivalent to <tt>X::reverse_iterator(a.begin())</tt>.
|
||||
</TD>
|
||||
</tr>
|
||||
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
Back
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a.back()</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>reference</tt> if <tt>a</tt> is mutable, <br> <tt>const_reference</tt>
|
||||
otherwise.
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
Equivalent to <tt>*(--a.end())</tt>.
|
||||
</TD>
|
||||
</TR>
|
||||
|
||||
</table>
|
||||
|
||||
<h4>SequentialCollection</h4>
|
||||
|
||||
The elements are arranged in a strict linear order. No extra methods
|
||||
are required.
|
||||
|
||||
<h4>RandomAccessCollection</h4>
|
||||
|
||||
The iterators of a RandomAccessCollection satisfy all of the
|
||||
requirements of <a
|
||||
href="http://www.sgi.com/Technology/STL/RandomAccessIterator.html">RandomAccessIterator</a>
|
||||
except that the reference type does not have to be a real C++
|
||||
reference. In addition, a RandomAccessCollection provides
|
||||
an element access operator.
|
||||
|
||||
<p>
|
||||
|
||||
<Table border>
|
||||
<TR>
|
||||
<TH>
|
||||
Name
|
||||
</TH>
|
||||
<TH>
|
||||
Expression
|
||||
</TH>
|
||||
<TH>
|
||||
Return type
|
||||
</TH>
|
||||
<TH>
|
||||
Semantics
|
||||
</TH>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
Element Access
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a[n]</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>reference</tt> if <tt>a</tt> is mutable,
|
||||
<tt>const_reference</tt> otherwise.
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
Returns the nth element of the Collection.
|
||||
<tt>n</tt> must be convertible to <tt>size_type</tt>.
|
||||
Precondition: <tt>0 <= n < a.size()</tt>.
|
||||
</TD>
|
||||
</TR>
|
||||
|
||||
</table>
|
||||
|
||||
<h3>Notes</h3>
|
||||
|
||||
<P><A name="1">[1]</A>
|
||||
|
||||
The reference type does not have to be a real C++ reference. The
|
||||
requirements of the reference type depend on the context within which
|
||||
the Collection is being used. Specifically it depends on the
|
||||
requirements the context places on the value type of the Collection.
|
||||
The reference type of the Collection must meet the same requirements
|
||||
as the value type. In addition, the reference objects must be
|
||||
equivalent to the value type objects in the collection (which is
|
||||
trivially true if they are the same object). Also, in a mutable
|
||||
Collection, an assignment to the reference object must result in an
|
||||
assignment to the object in the Collection (again, which is trivially
|
||||
true if they are the same object, but non-trivial if the reference
|
||||
type is a proxy class).
|
||||
|
||||
<h3>See also</h3>
|
||||
<A href="http://www.sgi.com/Technology/STL/Container.html">Container</A>
|
||||
|
||||
|
||||
<br>
|
||||
<HR>
|
||||
<TABLE>
|
||||
<TR valign=top>
|
||||
<TD nowrap>Copyright © 2000</TD><TD>
|
||||
<A HREF=http://www.boost.org/people/jeremy_siek.htm>Jeremy Siek</A>, Univ.of Notre Dame and C++ Library & Compiler Group/SGI (<A HREF="mailto:jsiek@engr.sgi.com">jsiek@engr.sgi.com</A>)
|
||||
</TD></TR></TABLE>
|
||||
|
||||
</BODY>
|
||||
</HTML>
|
||||
@ -1,4 +1,4 @@
|
||||
<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>Boost.MultiArray Reference Manual</title><meta name="generator" content="DocBook XSL Stylesheets V1.49"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article"><div class="titlepage"><div><h1 class="title"><a name="id170680"></a>Boost.MultiArray Reference Manual</h1></div><div><h3 class="author">Ronald Garcia</h3><div class="affiliation"><span class="orgname">Indiana University<br></span><span class="orgdiv">Open Systems Lab<br></span></div></div><div><p class="copyright">Copyright © 2002 Ronald Garcia</p></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="#synopsis">Library Synopsis</a></dt><dt><a href="#MultiArray">MultiArray Concept</a></dt><dd><dl><dt><a href="#id178374">Notation</a></dt><dt><a href="#id174782">Associated Types</a></dt><dt><a href="#id175404">Valid expressions</a></dt><dt><a href="#id248756">Complexity guarantees</a></dt><dt><a href="#id248779">Invariants</a></dt><dt><a href="#view_types">Associated Types for Views</a></dt><dd><dl><dt><a href="#index_range">index_range</a></dt><dt><a href="#index_gen">index_gen</a></dt></dl></dd><dt><a href="#id250489">Models</a></dt></dl></dd><dt><a href="#array_types">Array Components</a></dt><dd><dl><dt><a href="#multi_array">multi_array</a></dt><dt><a href="#multi_array_ref">multi_array_ref</a></dt><dt><a href="#const_multi_array_ref">const_multi_array_ref</a></dt></dl></dd><dt><a href="#auxiliary">Auxiliary Components</a></dt><dd><dl><dt><a href="#multi_array_types">multi_array_types</a></dt><dt><a href="#extent_range">extent_range</a></dt><dt><a href="#extent_gen">extent_gen</a></dt><dt><a href="#id250787">Global Objects</a></dt><dd><dl><dt><a href="#extents">extents</a></dt><dt><a href="#indices">indices</a></dt></dl></dd><dt><a href="#generators">View and SubArray Generators</a></dt><dt><a href="#memory_layout">Memory Layout Specifiers</a></dt><dd><dl><dt><a href="#c_storage_order">c_storage_order</a></dt><dt><a href="#fortran_storage_order">fortran_storage_order</a></dt><dt><a href="#general_storage_order">general_storage_order</a></dt></dl></dd></dl></dd></dl></div><fake><p>Boost.MultiArray is composed of several components.
|
||||
<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>Boost.MultiArray Reference Manual</title><meta name="generator" content="DocBook XSL Stylesheets V1.49"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article"><div class="titlepage"><div><h1 class="title"><a name="id170680"></a>Boost.MultiArray Reference Manual</h1></div><div><h3 class="author">Ronald Garcia</h3><div class="affiliation"><span class="orgname">Indiana University<br></span><span class="orgdiv">Open Systems Lab<br></span></div></div><div><p class="copyright">Copyright © 2002 Ronald Garcia</p></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="#synopsis">Library Synopsis</a></dt><dt><a href="#MultiArray">MultiArray Concept</a></dt><dd><dl><dt><a href="#id178375">Notation</a></dt><dt><a href="#id174783">Associated Types</a></dt><dt><a href="#id175405">Valid expressions</a></dt><dt><a href="#id248758">Complexity guarantees</a></dt><dt><a href="#id248780">Invariants</a></dt><dt><a href="#view_types">Associated Types for Views</a></dt><dd><dl><dt><a href="#index_range">index_range</a></dt><dt><a href="#index_gen">index_gen</a></dt></dl></dd><dt><a href="#id250491">Models</a></dt></dl></dd><dt><a href="#array_types">Array Components</a></dt><dd><dl><dt><a href="#multi_array">multi_array</a></dt><dt><a href="#multi_array_ref">multi_array_ref</a></dt><dt><a href="#const_multi_array_ref">const_multi_array_ref</a></dt></dl></dd><dt><a href="#auxiliary">Auxiliary Components</a></dt><dd><dl><dt><a href="#multi_array_types">multi_array_types</a></dt><dt><a href="#extent_range">extent_range</a></dt><dt><a href="#extent_gen">extent_gen</a></dt><dt><a href="#id250788">Global Objects</a></dt><dd><dl><dt><a href="#extents">extents</a></dt><dt><a href="#indices">indices</a></dt></dl></dd><dt><a href="#generators">View and SubArray Generators</a></dt><dt><a href="#memory_layout">Memory Layout Specifiers</a></dt><dd><dl><dt><a href="#c_storage_order">c_storage_order</a></dt><dt><a href="#fortran_storage_order">fortran_storage_order</a></dt><dt><a href="#general_storage_order">general_storage_order</a></dt></dl></dd></dl></dd></dl></div><fake><p>Boost.MultiArray is composed of several components.
|
||||
The MultiArray concept defines a generic interface to multidimensional
|
||||
containers.
|
||||
<tt>multi_array</tt> is a general purpose container class
|
||||
@ -150,15 +150,15 @@ 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></fake><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="id178374"></a>Notation</h3></div></div><fake><p>What follows are the descriptions of symbols that will be used
|
||||
</p></fake><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="id178375"></a>Notation</h3></div></div><fake><p>What follows are the descriptions of symbols that will be used
|
||||
to describe the MultiArray interface.</p></fake><div class="table"><p><b>Table 1. Notation</b></p><table summary="Notation" border="1"><colgroup><col><col></colgroup><tbody><tr><td><tt>A</tt></td><td>A type that is a model of MultiArray
|
||||
</td></tr><tr><td><tt>a</tt></td><td>An object of type <tt>A</tt></td></tr><tr><td><tt>NumDims</tt></td><td>The numeric dimension parameter associated with
|
||||
<tt>A</tt>.</td></tr><tr><td><tt>Dims</tt></td><td>Some numeric dimension parameter such that
|
||||
<tt>0<Dims<NumDims</tt>.
|
||||
</td></tr><tr><td><tt>indices</tt></td><td>An object created by some number of chained calls
|
||||
to <tt>index_gen::operator[](index_range)</tt>.</td></tr><tr><td><tt>index_list</tt></td><td>An object whose type models
|
||||
<a href="./Collection.html" target="_top">Collection</a></td></tr><tr><td><tt>idx</tt></td><td>A signed integral value.</td></tr><tr><td><tt>tmp</tt></td><td>An object of type
|
||||
<tt>boost::array<index,NumDims></tt></td></tr></tbody></table></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="id174782"></a>Associated Types</h3></div></div><fake><p>
|
||||
<a href="../../utility/Collection.html" target="_top">Collection</a></td></tr><tr><td><tt>idx</tt></td><td>A signed integral value.</td></tr><tr><td><tt>tmp</tt></td><td>An object of type
|
||||
<tt>boost::array<index,NumDims></tt></td></tr></tbody></table></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="id174783"></a>Associated Types</h3></div></div><fake><p>
|
||||
</p></fake><div class="table"><p><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>value_type</tt></td><td>This is the value type of the container.
|
||||
If <tt>NumDims == 1</tt>, then this is
|
||||
<tt>element</tt>. Otherwise, this is the value type of the
|
||||
@ -228,7 +228,7 @@ It models MultiArray.
|
||||
</td></tr><tr><td><tt>template
|
||||
const_array_view<Dims>::type</tt></td><td>
|
||||
This is the const view type with <tt>Dims</tt> dimensions.
|
||||
</td></tr></tbody></table></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="id175404"></a>Valid expressions</h3></div></div><div class="table"><p><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>a.shape()</tt></td><td><tt>const size_type*</tt></td><td>
|
||||
</td></tr></tbody></table></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="id175405"></a>Valid expressions</h3></div></div><div class="table"><p><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>a.shape()</tt></td><td><tt>const size_type*</tt></td><td>
|
||||
This returns a list of <tt>NumDims</tt> elements specifying the
|
||||
extent of each array dimension.
|
||||
</td></tr><tr><td><tt>a.strides()</tt></td><td><tt>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>a >= b</tt></td><td>bool</td><td>This performs a lexicographical comparison of the
|
||||
values of <tt>a</tt> and <tt>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"><div class="titlepage"><div><h3 class="title"><a name="id248756"></a>Complexity guarantees</h3></div></div><tt>begin()</tt> and <tt>end()</tt> execute in amortized
|
||||
expression to be valid.</td></tr></tbody></table></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="id248758"></a>Complexity guarantees</h3></div></div><tt>begin()</tt> and <tt>end()</tt> execute in amortized
|
||||
constant time.
|
||||
<tt>size()</tt> executes in at most linear time in the
|
||||
MultiArray's size.
|
||||
</div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="id248779"></a>Invariants</h3></div></div><div class="table"><p><b>Table 4. Invariants</b></p><table summary="Invariants" border="1"><colgroup><col><col></colgroup><tbody><tr><td>Valid range</td><td><tt>[a.begin(),a.end())</tt> is a valid range.
|
||||
</div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="id248780"></a>Invariants</h3></div></div><div class="table"><p><b>Table 4. Invariants</b></p><table summary="Invariants" border="1"><colgroup><col><col></colgroup><tbody><tr><td>Valid range</td><td><tt>[a.begin(),a.end())</tt> is a valid range.
|
||||
</td></tr><tr><td>Range size</td><td><tt>a.size() == std::distance(a.begin(),a.end());</tt>.
|
||||
</td></tr><tr><td>Completeness</td><td>
|
||||
Iteration through the range
|
||||
@ -329,7 +329,7 @@ Iteration through the range
|
||||
Calling <tt>a[a1][a2]...[aN]</tt> where <tt>N==NumDims</tt>
|
||||
yields the same result as calling
|
||||
<tt>a(index_list)</tt>, where <tt>index_list</tt>
|
||||
is a <a href="./Collection.html" target="_top">Collection</a> containing the values <tt>a1...aN</tt>.
|
||||
is a <a href="../../utility/Collection.html" target="_top">Collection</a> containing the values <tt>a1...aN</tt>.
|
||||
</td></tr></tbody></table></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="view_types"></a>Associated Types for Views</h3></div></div><fake><p>The following MultiArray associated
|
||||
types define the interface for creating views of existing
|
||||
MultiArrays. Their interfaces and roles in the
|
||||
@ -421,7 +421,7 @@ range, <tt>index_range(idx,idx).</tt> Note that this is NOT
|
||||
equivalent to <tt>x[index_range(idx,idx)].</tt>, which will
|
||||
return an object of type
|
||||
<tt>gen_type<Dims+1,Ranges+1>::type</tt>.
|
||||
</td></tr></tbody></table></div></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="id250489"></a>Models</h3></div></div><div class="itemizedlist"><ul type="disc"><li><tt>multi_array</tt></li><li><tt>multi_array_ref</tt></li><li><tt>const_multi_array_ref</tt></li><li><tt>template array_view<Dims>::type</tt></li><li><tt>template const_array_view<Dims>::type</tt></li><li><tt>template subarray<Dims>::type</tt></li><li><tt>template const_subarray<Dims>::type</tt></li></ul></div></div></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="array_types"></a>Array Components</h2></div></div><fake><p>
|
||||
</td></tr></tbody></table></div></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="id250491"></a>Models</h3></div></div><div class="itemizedlist"><ul type="disc"><li><tt>multi_array</tt></li><li><tt>multi_array_ref</tt></li><li><tt>const_multi_array_ref</tt></li><li><tt>template array_view<Dims>::type</tt></li><li><tt>template const_array_view<Dims>::type</tt></li><li><tt>template subarray<Dims>::type</tt></li><li><tt>template const_subarray<Dims>::type</tt></li></ul></div></div></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="array_types"></a>Array Components</h2></div></div><fake><p>
|
||||
Boost.MultiArray defines an array class,
|
||||
<tt>multi_array</tt>, and two adapter classes,
|
||||
<tt>multi_array_ref</tt> and
|
||||
@ -489,7 +489,7 @@ void reshape(const SizeList& sizes)
|
||||
number of elements and the index bases remain the same, but the number
|
||||
of values at each level of the nested container hierarchy may
|
||||
change.</p></fake><p><b><tt>SizeList</tt> Requirements. </b><tt>SizeList</tt> must model
|
||||
<a href="./Collection.html" target="_top">Collection</a>.</p><p><b>Preconditions. </b>
|
||||
<a href="../../utility/Collection.html" target="_top">Collection</a>.</p><p><b>Preconditions. </b>
|
||||
<pre class="programlisting">
|
||||
std::accumulate(sizes.begin(),sizes.end(),size_type(1),std::times<size_type>()) == this->num_elements();
|
||||
sizes.size() == NumDims;
|
||||
@ -504,7 +504,7 @@ void reindex(const BaseList& values);
|
||||
</pre>
|
||||
</span></dt><dd><fake><p>This changes the index bases of the <tt>multi_array</tt> to
|
||||
correspond to the the values in <tt>values</tt>.</p></fake><p><b><tt>BaseList</tt> Requirements. </b><tt>BaseList</tt> must model
|
||||
<a href="./Collection.html" target="_top">Collection</a>.</p><p><b>Preconditions. </b><tt>values.size() == NumDims;</tt></p><p><b>Postconditions. </b><tt>std::equal(values.begin(),values.end(),this->index_bases());
|
||||
<a href="../../utility/Collection.html" target="_top">Collection</a>.</p><p><b>Preconditions. </b><tt>values.size() == NumDims;</tt></p><p><b>Postconditions. </b><tt>std::equal(values.begin(),values.end(),this->index_bases());
|
||||
</tt></p></dd><dt><span class="term">
|
||||
<pre class="programlisting">
|
||||
|
||||
@ -646,7 +646,7 @@ specifies the storage order or layout in memory of the array
|
||||
dimensions. <tt>alloc</tt> is used to
|
||||
allocate the contained elements.
|
||||
</p></fake><p><b><tt>ExtentList</tt> Requirements. </b>
|
||||
<tt>ExtentList</tt> must model <a href="./Collection.html" target="_top">Collection</a>.
|
||||
<tt>ExtentList</tt> must model <a href="../../utility/Collection.html" target="_top">Collection</a>.
|
||||
</p><p><b>Preconditions. </b><tt>sizes.size() == NumDims;</tt></p></dd><dt><span class="term">
|
||||
<pre class="programlisting">explicit multi_array(extent_gen::gen_type<NumDims>::type ranges,
|
||||
const storage_order& store = c_storage_order(),
|
||||
@ -831,7 +831,7 @@ specifies the storage order or layout in memory of the array
|
||||
dimensions. <tt>alloc</tt> is used to
|
||||
allocate the contained elements.
|
||||
</p></fake><p><b><tt>ExtentList</tt> Requirements. </b>
|
||||
<tt>ExtentList</tt> must model <a href="./Collection.html" target="_top">Collection</a>.
|
||||
<tt>ExtentList</tt> must model <a href="../../utility/Collection.html" target="_top">Collection</a>.
|
||||
</p><p><b>Preconditions. </b><tt>sizes.size() == NumDims;</tt></p></dd><dt><span class="term">
|
||||
<pre class="programlisting">explicit multi_array_ref(element* data,
|
||||
extent_gen::gen_type<NumDims>::type ranges,
|
||||
@ -971,7 +971,7 @@ constructed <tt>const_multi_array_ref</tt>. <tt>store</tt>
|
||||
specifies the storage order or layout in memory of the array
|
||||
dimensions.
|
||||
</p></fake><p><b><tt>ExtentList</tt> Requirements. </b>
|
||||
<tt>ExtentList</tt> must model <a href="./Collection.html" target="_top">Collection</a>.
|
||||
<tt>ExtentList</tt> must model <a href="../../utility/Collection.html" target="_top">Collection</a>.
|
||||
</p><p><b>Preconditions. </b><tt>sizes.size() == NumDims;</tt></p></dd><dt><span class="term">
|
||||
<pre class="programlisting">explicit const_multi_array_ref(const element* data,
|
||||
extent_gen::gen_type<NumDims>::type ranges,
|
||||
@ -1078,7 +1078,7 @@ operator[](index idx) const;</tt></span></dt><dd><fake><p>This function returns
|
||||
<tt>extent_range</tt> objects in addition to
|
||||
<tt>extent_range(0,idx).</tt> This function gives the array
|
||||
constructors a similar syntax to traditional C multidimensional array
|
||||
declaration.</p></fake></dd></dl></div></p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="id250787"></a>Global Objects</h3></div></div><fake><p>For syntactic convenience, Boost.MultiArray defines two
|
||||
declaration.</p></fake></dd></dl></div></p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="id250788"></a>Global Objects</h3></div></div><fake><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.
|
||||
|
||||
@ -244,7 +244,7 @@ Though the number of dimensions is always specified as a template
|
||||
parameter, two separate mechanisms have been provided to specify the
|
||||
extent of each.
|
||||
<p>The first method involves passing a
|
||||
<a href="./Collection.html">
|
||||
<a href="../../utility/Collection.html">
|
||||
Collection</a> of extents to a
|
||||
constructor, most commonly a <tt>boost::array</tt>. The constructor
|
||||
will retrieve the beginning iterator from the container and retrieve N
|
||||
@ -290,7 +290,7 @@ C array notation, provided by <tt>operator[]</tt>.
|
||||
</blockquote>
|
||||
|
||||
<p> The second method involves passing a
|
||||
<a href="./Collection.html">
|
||||
<a href="../../utility/Collection.html">
|
||||
Collection</a> of indices to <tt>operator()</tt>. N indices will be retrieved
|
||||
from the Collection for the N dimensions of the container.
|
||||
<h3>Example</h3>
|
||||
@ -607,7 +607,7 @@ cases can be found <a href="./test_cases.html">here</a>.
|
||||
</address>
|
||||
<!-- Created: Fri Jun 29 10:53:07 EST 2001 -->
|
||||
<!-- hhmts start -->
|
||||
Last modified: Fri Jul 26 12:56:22 EST 2002
|
||||
Last modified: Tue Sep 10 11:14:15 EST 2002
|
||||
<!-- hhmts end -->
|
||||
|
||||
</body>
|
||||
|
||||
@ -146,7 +146,7 @@ to <literal>index_gen::operator[](index_range)</literal>.</entry>
|
||||
<row>
|
||||
<entry><literal>index_list</literal></entry>
|
||||
<entry>An object whose type models
|
||||
<ulink url="./Collection.html">Collection</ulink>
|
||||
<ulink url="../../utility/Collection.html">Collection</ulink>
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
@ -633,7 +633,7 @@ Iteration through the range
|
||||
Calling <literal>a[a1][a2]...[aN]</literal> where <literal>N==NumDims</literal>
|
||||
yields the same result as calling
|
||||
<literal>a(index_list)</literal>, where <literal>index_list</literal>
|
||||
is a <ulink url="./Collection.html">Collection</ulink> containing the values <literal>a1...aN</literal>.
|
||||
is a <ulink url="../../utility/Collection.html">Collection</ulink> containing the values <literal>a1...aN</literal>.
|
||||
</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
|
||||
@ -136,7 +136,7 @@ dimensions.
|
||||
|
||||
<formalpara><title><literal>ExtentList</literal> Requirements</title>
|
||||
<para>
|
||||
<literal>ExtentList</literal> must model <ulink url="./Collection.html">Collection</ulink>.
|
||||
<literal>ExtentList</literal> must model <ulink url="../../utility/Collection.html">Collection</ulink>.
|
||||
</para>
|
||||
</formalpara>
|
||||
|
||||
|
||||
@ -152,7 +152,7 @@ allocate the contained elements.
|
||||
|
||||
<formalpara><title><literal>ExtentList</literal> Requirements</title>
|
||||
<para>
|
||||
<literal>ExtentList</literal> must model <ulink url="./Collection.html">Collection</ulink>.
|
||||
<literal>ExtentList</literal> must model <ulink url="../../utility/Collection.html">Collection</ulink>.
|
||||
</para>
|
||||
</formalpara>
|
||||
|
||||
|
||||
@ -152,7 +152,7 @@ allocate the contained elements.
|
||||
|
||||
<formalpara><title><literal>ExtentList</literal> Requirements</title>
|
||||
<para>
|
||||
<literal>ExtentList</literal> must model <ulink url="./Collection.html">Collection</ulink>.
|
||||
<literal>ExtentList</literal> must model <ulink url="../../utility/Collection.html">Collection</ulink>.
|
||||
</para>
|
||||
</formalpara>
|
||||
|
||||
|
||||
@ -245,7 +245,7 @@ change.</para>
|
||||
|
||||
<formalpara><title><literal>SizeList</literal> Requirements</title>
|
||||
<para><literal>SizeList</literal> must model
|
||||
<ulink url="./Collection.html">Collection</ulink>.</para>
|
||||
<ulink url="../../utility/Collection.html">Collection</ulink>.</para>
|
||||
</formalpara>
|
||||
|
||||
<formalpara><title>Preconditions</title>
|
||||
@ -281,7 +281,7 @@ correspond to the the values in <literal>values</literal>.</para>
|
||||
<formalpara>
|
||||
<title><literal>BaseList</literal> Requirements</title>
|
||||
<para><literal>BaseList</literal> must model
|
||||
<ulink url="./Collection.html">Collection</ulink>.</para>
|
||||
<ulink url="../../utility/Collection.html">Collection</ulink>.</para>
|
||||
</formalpara>
|
||||
|
||||
<formalpara>
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user