mirror of
https://github.com/boostorg/utility.git
synced 2025-05-09 02:44:10 +00:00
649 lines
13 KiB
HTML
649 lines
13 KiB
HTML
<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/tech/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/tech/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/tech/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/tech/stl/EqualityComparable.html">EqualityComparable</A>
|
|
and
|
|
<A
|
|
href="http://www.sgi.com/tech/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/tech/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/tech/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/tech/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>
|