mirror of
https://github.com/boostorg/utility.git
synced 2025-05-08 18:34:02 +00:00
Initial Revision
[SVN r15254]
This commit is contained in:
Ronald Garcia
parent
d8230c6a73
commit
e20af510f7
648
Collection.html
Normal file
648
Collection.html
Normal file
@ -0,0 +1,648 @@
|
||||
<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>
|
||||
Loading…
x
Reference in New Issue
Block a user