forked from boostorg/range
*** empty log message ***
[SVN r24174]
This commit is contained in:
445
doc/range.htm
445
doc/range.htm
@@ -11,7 +11,7 @@
|
|||||||
-- purpose. It is provided "as is" without express or implied warranty.
|
-- purpose. It is provided "as is" without express or implied warranty.
|
||||||
-->
|
-->
|
||||||
<Head>
|
<Head>
|
||||||
<Title>Collection</Title>
|
<Title>Range Concepts</Title>
|
||||||
</HEAD>
|
</HEAD>
|
||||||
<BODY BGCOLOR="#ffffff" LINK="#0000ee" TEXT="#000000" VLINK="#551a8b"
|
<BODY BGCOLOR="#ffffff" LINK="#0000ee" TEXT="#000000" VLINK="#551a8b"
|
||||||
ALINK="#ff0000">
|
ALINK="#ff0000">
|
||||||
@@ -20,147 +20,32 @@
|
|||||||
<IMG SRC="/Images/stat.gif" ALT="" BORDER=0 WIDTH = "6" HEIGHT = "6" >
|
<IMG SRC="/Images/stat.gif" ALT="" BORDER=0 WIDTH = "6" HEIGHT = "6" >
|
||||||
|
|
||||||
<BR Clear>
|
<BR Clear>
|
||||||
<H1>Collection</H1>
|
<H1>Range</H1>
|
||||||
|
|
||||||
|
|
||||||
<h3>Description</h3>
|
<h3>Description</h3>
|
||||||
|
|
||||||
A Collection is a <i>concept</i> similar to the STL <a
|
A Range is a <i>concept</i> similar to the STL <a
|
||||||
href="http://www.sgi.com/Technology/STL/Container.html">Container</a>
|
href="http://www.sgi.com/Technology/STL/Container.html">Container</a>
|
||||||
concept. A Collection provides iterators for accessing a range of
|
concept. A Range provides iterators for accessing a range of
|
||||||
elements and provides information about the number of elements in the
|
elements and provides information about the number of elements in the
|
||||||
Collection. However, a Collection has fewer requirements than a
|
Range. However, a Range has fewer requirements than a
|
||||||
Container. The motivation for the Collection concept is that there are
|
Container. The motivation for the Range concept is that there are
|
||||||
many useful Container-like types that do not meet the full
|
many useful Container-like types that do not meet the full
|
||||||
requirements of Container, and many algorithms that can be written
|
requirements of Container, and many algorithms that can be written
|
||||||
with this reduced set of requirements. To summarize the reduction
|
with this reduced set of requirements. In particular, a Range does
|
||||||
in requirements:
|
not necessarily
|
||||||
|
|
||||||
<UL>
|
<ul>
|
||||||
<LI>It is not required to "own" its elements: the lifetime
|
<li> own the elements that can be accessed through it,
|
||||||
of an element in a Collection does not have to match the lifetime of
|
<li> have copy semantics,
|
||||||
the Collection object, though the lifetime of the element should cover
|
<li> require that the associated reference type is a real C++ reference.
|
||||||
the lifetime of the Collection object.
|
</ul>
|
||||||
<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 second requirement, a Range object must
|
||||||
Because of the reduced requirements, some care must be taken when
|
be passed by reference in generic code.
|
||||||
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>
|
<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>
|
<h3>Notation</h3>
|
||||||
<Table>
|
<Table>
|
||||||
<TR>
|
<TR>
|
||||||
@@ -168,7 +53,7 @@ An unsigned integral type that can represent any nonnegative value
|
|||||||
<tt>X</tt>
|
<tt>X</tt>
|
||||||
</TD>
|
</TD>
|
||||||
<TD VAlign=top>
|
<TD VAlign=top>
|
||||||
A type that is a model of Collection.
|
A type that is a model of Range.
|
||||||
</TD>
|
</TD>
|
||||||
</TR>
|
</TR>
|
||||||
<TR>
|
<TR>
|
||||||
@@ -189,6 +74,120 @@ The value type of <tt>X</tt>.
|
|||||||
</tr>
|
</tr>
|
||||||
</table>
|
</table>
|
||||||
|
|
||||||
|
<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 Range.
|
||||||
|
<!--
|
||||||
|
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 Range's
|
||||||
|
elements. The iterator's value type is expected to be the
|
||||||
|
Range's value type. A conversion
|
||||||
|
from the iterator type to the const iterator type must exist.
|
||||||
|
The iterator type must at least 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 Range'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 Range'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 Range'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 Range's distance type.
|
||||||
|
</TD>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
|
||||||
|
|
||||||
<h3>Valid expressions</h3>
|
<h3>Valid expressions</h3>
|
||||||
|
|
||||||
The following expressions must be valid.
|
The following expressions must be valid.
|
||||||
@@ -254,7 +253,7 @@ Maximum size
|
|||||||
<TR>
|
<TR>
|
||||||
-->
|
-->
|
||||||
<TD VAlign=top>
|
<TD VAlign=top>
|
||||||
Empty Collection
|
Empty range
|
||||||
</TD>
|
</TD>
|
||||||
<TD VAlign=top>
|
<TD VAlign=top>
|
||||||
<tt>a.empty()</tt>
|
<tt>a.empty()</tt>
|
||||||
@@ -302,7 +301,7 @@ Beginning of range
|
|||||||
<tt>a.begin()</tt>
|
<tt>a.begin()</tt>
|
||||||
</TD>
|
</TD>
|
||||||
<TD VAlign=top>
|
<TD VAlign=top>
|
||||||
Returns an iterator pointing to the first element in the Collection.
|
Returns an iterator pointing to the first element in the Range.
|
||||||
</TD>
|
</TD>
|
||||||
<TD VAlign=top>
|
<TD VAlign=top>
|
||||||
<tt>a.begin()</tt> is either dereferenceable or past-the-end. It is
|
<tt>a.begin()</tt> is either dereferenceable or past-the-end. It is
|
||||||
@@ -318,7 +317,7 @@ End of range
|
|||||||
</TD>
|
</TD>
|
||||||
<TD VAlign=top>
|
<TD VAlign=top>
|
||||||
Returns an iterator pointing one past the last element in the
|
Returns an iterator pointing one past the last element in the
|
||||||
Collection.
|
Range.
|
||||||
</TD>
|
</TD>
|
||||||
<TD VAlign=top>
|
<TD VAlign=top>
|
||||||
<tt>a.end()</tt> is past-the-end.
|
<tt>a.end()</tt> is past-the-end.
|
||||||
@@ -391,12 +390,11 @@ Equivalent to <tt>swap(a,b)</tt>
|
|||||||
</table>
|
</table>
|
||||||
<h3>Complexity guarantees</h3>
|
<h3>Complexity guarantees</h3>
|
||||||
|
|
||||||
<tt>begin()</tt> and <tt>end()</tt> are amortized constant time.
|
All four functions are at most amortized linear time. For
|
||||||
<P>
|
most practical purposes, one can expect
|
||||||
<tt>size()</tt> is at most linear in the Collection's
|
<tt>begin()</tt>, <tt>end()</tt> and <tt>empty()</tt> to be amortized constant
|
||||||
size. <tt>empty()</tt> is amortized constant time.
|
time.
|
||||||
<!-- <P>
|
|
||||||
<tt>swap()</tt> is at most linear in the size of the two collections. -->
|
|
||||||
<h3>Invariants</h3>
|
<h3>Invariants</h3>
|
||||||
<Table border>
|
<Table border>
|
||||||
<TR>
|
<TR>
|
||||||
@@ -404,7 +402,7 @@ size. <tt>empty()</tt> is amortized constant time.
|
|||||||
Valid range
|
Valid range
|
||||||
</TD>
|
</TD>
|
||||||
<TD VAlign=top>
|
<TD VAlign=top>
|
||||||
For any Collection <tt>a</tt>, <tt>[a.begin(), a.end())</tt> is a valid
|
For any Range <tt>a</tt>, <tt>[a.begin(), a.end())</tt> is a valid
|
||||||
range.
|
range.
|
||||||
</TD>
|
</TD>
|
||||||
</TR>
|
</TR>
|
||||||
@@ -430,80 +428,65 @@ An algorithm that iterates through the range <tt>[a.begin(), a.end())</tt>
|
|||||||
|
|
||||||
<h3>Models</h3>
|
<h3>Models</h3>
|
||||||
<UL>
|
<UL>
|
||||||
<!-- <LI> <tt>array</tt> -->
|
<LI> <tt>boost::array<T,sz></tt>
|
||||||
<!--<LI> <tt>array_ptr</tt> -->
|
<LI> <tt>std::vector<bool></tt>
|
||||||
<LI> <tt>vector<bool></tt>
|
|
||||||
</UL>
|
</UL>
|
||||||
|
|
||||||
<!--
|
<h3>See also</h3>
|
||||||
<h3>Collection Refinements</h3>
|
<A href="http://www.sgi.com/Technology/STL/Container.html">Container</A>
|
||||||
|
|
||||||
There are quite a few concepts that refine the Collection concept,
|
<br><br>
|
||||||
similar to the concepts that refine the Container concept. Here
|
<hr>
|
||||||
is a brief overview of the refining concepts.
|
<br>
|
||||||
|
|
||||||
<h4>ForwardCollection</h4>
|
<h1>ReversibleRange</h1>
|
||||||
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>
|
<h3>Description</h3>
|
||||||
<Table border>
|
This concept provides access to iterators that traverse in both
|
||||||
<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
|
directions (forward and reverse). The iterator type must meet all of
|
||||||
the requirements of <a
|
the requirements of <a
|
||||||
href="http://www.sgi.com/Technology/STL/BidirectionalIterator.html">BidirectionalIterator</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++
|
except that the reference type does not have to be a real C++
|
||||||
reference. The ReversibleCollection adds the following requirements
|
reference.
|
||||||
to those of ForwardCollection.
|
|
||||||
<p>
|
<h3>Refinement of</h3>
|
||||||
|
Range
|
||||||
|
|
||||||
|
<h3>Associated types</h3>
|
||||||
|
|
||||||
|
<Table border>
|
||||||
|
<TR>
|
||||||
|
<TD VAlign=top>
|
||||||
|
Reverse Iterator type
|
||||||
|
</TD>
|
||||||
|
<TD VAlign=top>
|
||||||
|
<tt>X::reverse_iterator</tt>
|
||||||
|
</TD>
|
||||||
|
<TD VAlign=top>
|
||||||
|
The type of iterator used to iterate through a Range's
|
||||||
|
elements in reverse order. The iterator's value type is expected to be the
|
||||||
|
Range's value type. A conversion
|
||||||
|
from the reverse iterator type to the const reverse iterator type must exist.
|
||||||
|
The iterator type must at least be a <a
|
||||||
|
href="http://www.sgi.com/Technology/STL/BidirectionalIterator.html">BidirectionalIterator</a>.
|
||||||
|
</TD>
|
||||||
|
</TR>
|
||||||
|
<TR>
|
||||||
|
<TD VAlign=top>
|
||||||
|
Const reverse iterator type
|
||||||
|
</TD>
|
||||||
|
<TD VAlign=top>
|
||||||
|
<tt>X::const_reverse_iterator</tt>
|
||||||
|
</TD>
|
||||||
|
<TD VAlign=top>
|
||||||
|
A type of reverse iterator that may be used to examine, but not to modify,
|
||||||
|
a Range's elements.
|
||||||
|
</TD>
|
||||||
|
</TR>
|
||||||
|
</table>
|
||||||
|
|
||||||
|
|
||||||
|
<h3>Valid expressions</h3>
|
||||||
|
|
||||||
<Table border>
|
<Table border>
|
||||||
<TR>
|
<TR>
|
||||||
@@ -551,53 +534,43 @@ Equivalent to <tt>X::reverse_iterator(a.begin())</tt>.
|
|||||||
</TD>
|
</TD>
|
||||||
</tr>
|
</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>
|
</table>
|
||||||
|
|
||||||
<h4>SequentialCollection</h4>
|
<h3>Complexity guarantees</h3>
|
||||||
|
|
||||||
The elements are arranged in a strict linear order. No extra methods
|
<tt>rbegin()</tt> has the same complexity as <tt>end()</tt> and
|
||||||
are required.
|
<tt>rend()</tt> has the same complexity as <tt>begin()</tt> from Range.
|
||||||
-->
|
|
||||||
|
|
||||||
|
<h3>Models</h3>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li> std::vector<T>
|
||||||
|
<li> std::list<T>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<hr>
|
||||||
<h3>Notes</h3>
|
<h3>Notes</h3>
|
||||||
|
|
||||||
<P><A name="1">[1]</A>
|
<P><A name="1">[1]</A>
|
||||||
|
|
||||||
The reference type does not have to be a real C++ reference. The
|
The reference type does not have to be a real C++ reference. The
|
||||||
requirements of the reference type depend on the context within which
|
requirements of the reference type depend on the context within which
|
||||||
the Collection is being used. Specifically it depends on the
|
the Range is being used. Specifically it depends on the
|
||||||
requirements the context places on the value type of the Collection.
|
requirements the context places on the value type of the Range.
|
||||||
The reference type of the Collection must meet the same requirements
|
The reference type of the Range must meet the same requirements
|
||||||
as the value type. In addition, the reference objects must be
|
as the value type. In addition, the reference objects must be
|
||||||
equivalent to the value type objects in the collection (which is
|
equivalent to the value type objects in the Range (which is
|
||||||
trivially true if they are the same). Also, in a mutable Collection,
|
trivially true if they are the same). Also, in a mutable Range,
|
||||||
an assignment to the reference object must result in an assignment to
|
an assignment to the reference object must result in an assignment to
|
||||||
the object in the Collection (again, which is trivially true if they
|
the object in the Range (again, which is trivially true if they
|
||||||
are the same object, but non-trivial if the reference type is a proxy
|
are the same object, but non-trivial if the reference type is a proxy
|
||||||
class).
|
class).
|
||||||
|
|
||||||
<h3>See also</h3>
|
|
||||||
<A href="http://www.sgi.com/Technology/STL/Container.html">Container</A>
|
|
||||||
|
|
||||||
|
<br><br>
|
||||||
<br>
|
|
||||||
<HR>
|
<HR>
|
||||||
|
<br>
|
||||||
|
|
||||||
<TABLE>
|
<TABLE>
|
||||||
<TR valign=top>
|
<TR valign=top>
|
||||||
<TD nowrap>Copyright © 2000</TD><TD>
|
<TD nowrap>Copyright © 2000</TD><TD>
|
||||||
|
23
doc/style.css
Executable file
23
doc/style.css
Executable file
@@ -0,0 +1,23 @@
|
|||||||
|
pre{
|
||||||
|
BORDER-RIGHT: gray 1pt solid;
|
||||||
|
PADDING-RIGHT: 2pt;
|
||||||
|
BORDER-TOP: gray 1pt solid;
|
||||||
|
DISPLAY: block;
|
||||||
|
PADDING-LEFT: 2pt;
|
||||||
|
PADDING-BOTTOM: 2pt;
|
||||||
|
BORDER-LEFT: gray 1pt solid;
|
||||||
|
MARGIN-RIGHT: 32pt;
|
||||||
|
PADDING-TOP: 2pt;
|
||||||
|
BORDER-BOTTOM: gray 1pt solid;
|
||||||
|
FONT-FAMILY: "Courier New", Courier, mono;
|
||||||
|
background-color: #EEEEEE;
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
.keyword{color: #0000FF;}
|
||||||
|
.identifier{}
|
||||||
|
.comment{font-style: italic; color: #008000;}
|
||||||
|
.special{color: #800040;}
|
||||||
|
.preprocessor{color: #3F007F;}
|
||||||
|
.string{font-style: italic; color: #666666;}
|
||||||
|
.literal{font-style: italic; color: #666666;}
|
201
doc/utility_class.html
Normal file
201
doc/utility_class.html
Normal file
@@ -0,0 +1,201 @@
|
|||||||
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
|
||||||
|
|
||||||
|
<html>
|
||||||
|
<head>
|
||||||
|
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
||||||
|
<title>Boost.Range Utility Classes </title>
|
||||||
|
<link rel="stylesheet" href="style.css" type="text/css">
|
||||||
|
</head>
|
||||||
|
|
||||||
|
<body>
|
||||||
|
<table border="0" >
|
||||||
|
<tr>
|
||||||
|
<td ><img src="cboost.gif" border="0" ></td>
|
||||||
|
<td >
|
||||||
|
<h1 align="center">Boost.Range utility classes</h1>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
|
||||||
|
<h1></h1>
|
||||||
|
|
||||||
|
<p> Having an abstraction that encapsulates a pair of iterators is very
|
||||||
|
useful. The standard library uses <code>std::pair</code> in some
|
||||||
|
cercumstances, but that class is cumbersome to use because we need to
|
||||||
|
specify two template arguments, and for all range algorithm purposes,
|
||||||
|
we must enforce the two template arguments to be the same. Moreover,
|
||||||
|
<code>std::pair<iterator,iterator></code> is hardly self-documenting
|
||||||
|
whereas more domain specific class names are. Therefore these two
|
||||||
|
classes are provided:
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li> <a href=#iter_range><code>iterator_range</code></a>
|
||||||
|
<li> <a href=#sub_range><code>sub_range</code></a> </ul>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
The <code>iterator_range</code> class is templated on an iterator and should be
|
||||||
|
used whenever super general code is needed. The <code>sub_range</code> class
|
||||||
|
is templated on an <a href=range.html#external_range>ExternalRange</a>
|
||||||
|
and it is less general, but a bit easier to use since its template argument
|
||||||
|
is easier to specify.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<hr> <a name=iter_range></a> <h1><code>iterator_range</code></h1>
|
||||||
|
|
||||||
|
The intention of the
|
||||||
|
<code>iterator_range</code> class is to encapsulate
|
||||||
|
two iterators so they fulfill the <a href=range.html#range>Range</a> concept.
|
||||||
|
A few other functions are also provided for convinience.
|
||||||
|
|
||||||
|
<h3>Synopsis</h3>
|
||||||
|
|
||||||
|
<pre>
|
||||||
|
namespace boost
|
||||||
|
{
|
||||||
|
template< class Iterator >
|
||||||
|
class iterator_range
|
||||||
|
{
|
||||||
|
iterator_range(); // not implemented
|
||||||
|
|
||||||
|
public: // Range types
|
||||||
|
typedef ... value_type;
|
||||||
|
typedef ... difference_type;
|
||||||
|
typedef ... size_type;
|
||||||
|
typedef Iterator iterator;
|
||||||
|
typedef Iterator const_iterator;
|
||||||
|
|
||||||
|
public: // construction, assignment
|
||||||
|
template< class Iterator >
|
||||||
|
iterator_range( Iterator Begin, Iterator End );
|
||||||
|
|
||||||
|
template< class XRange >
|
||||||
|
iterator_range( XRange& r );
|
||||||
|
|
||||||
|
template< class XRange >
|
||||||
|
iterator_range( const XRange& r );
|
||||||
|
|
||||||
|
template< class XRange >
|
||||||
|
iterator_range& operator=( XRange& r );
|
||||||
|
|
||||||
|
template< class XRange >
|
||||||
|
iterator_range& operator=( const XRange& r );
|
||||||
|
|
||||||
|
public: // Range functions
|
||||||
|
iterator begin() const;
|
||||||
|
iterator end() const;
|
||||||
|
size_type size() const;
|
||||||
|
bool empty() const;
|
||||||
|
|
||||||
|
public: // convenience
|
||||||
|
operator unspecified_bool_type() const;
|
||||||
|
void swap( iterator_range& r );
|
||||||
|
};
|
||||||
|
|
||||||
|
// stream output
|
||||||
|
template< class Iterator, class T, class Traits >
|
||||||
|
std::basic_ostream<T,Traits>& operator<<( std::basic_ostream<T,Traits>& Os,
|
||||||
|
const iterator_range<Iterator>& r );
|
||||||
|
|
||||||
|
// comparison
|
||||||
|
template< class Iterator >
|
||||||
|
bool operator==( const iterator_range<Iterator>& l, const iterator_range<Iterator>& r );
|
||||||
|
|
||||||
|
template< class Iterator >
|
||||||
|
bool operator!=( const iterator_range<Iterator>& l, const iterator_range<Iterator>& r );
|
||||||
|
|
||||||
|
// external construction
|
||||||
|
template< class Iterator >
|
||||||
|
iterator_range< Iterator >
|
||||||
|
make_iterator_range( Iterator Begin, Iterator End );
|
||||||
|
|
||||||
|
template< class XRange >
|
||||||
|
iterator_range< typename iterator_of<XRange>::type >
|
||||||
|
make_iterator_range( XRange& r );
|
||||||
|
|
||||||
|
template< class XRange >
|
||||||
|
iterator_range< typename const_iterator_of<XRange>::type >
|
||||||
|
make_iterator_range( const XRange& r );
|
||||||
|
|
||||||
|
// convenience
|
||||||
|
template< class Sequence, class XRange >
|
||||||
|
Sequence copy_range( const XRange& r )
|
||||||
|
|
||||||
|
template< class Sequence, class XRange, class Func >
|
||||||
|
Sequence transform_range( const XRange& r, Func func );
|
||||||
|
|
||||||
|
} // namespace 'boost'
|
||||||
|
</pre>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
It is worth noticing that the templated constructors and assignment operators
|
||||||
|
allow conversion from <code>iterator_range<iterator></code> to
|
||||||
|
<code>iterator_range<const_iterator></code>. If an instance of
|
||||||
|
<code>iterator_range</code> is constructed by a client with two iterators, the
|
||||||
|
client must ensure that the two iterators delimit a valid closed-open range
|
||||||
|
<code>[begin,end)</code>.
|
||||||
|
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<hr> <a name=sub_range></a>
|
||||||
|
<h1><code>sub_range</code></h1>
|
||||||
|
|
||||||
|
The <code>sub_range</code> class inherits all its functionality
|
||||||
|
from the <a href="#iter_range"><code>iterator_range</code></a> class.
|
||||||
|
The <code>sub_range</code> class is often easier to use because
|
||||||
|
one must specify the <a href="range.html#external_range">ExternalRange</a>
|
||||||
|
template argument instead of an iterator.
|
||||||
|
|
||||||
|
<h3>Synopsis</h3>
|
||||||
|
|
||||||
|
<pre>
|
||||||
|
namespace boost
|
||||||
|
{
|
||||||
|
|
||||||
|
template< class XRange >
|
||||||
|
class sub_range : public iterator_range< typename result_iterator_of<XRange>::type >
|
||||||
|
{
|
||||||
|
public: // construction, assignment
|
||||||
|
template< class Iterator >
|
||||||
|
sub_range( Iterator Begin, Iterator End );
|
||||||
|
|
||||||
|
template< class XRange2 >
|
||||||
|
sub_range( XRange2& r );
|
||||||
|
|
||||||
|
template< class XRange2 >
|
||||||
|
sub_range( const Range2& r );
|
||||||
|
|
||||||
|
template< class XRange2 >
|
||||||
|
sub_range& operator=( XRange2& r );
|
||||||
|
|
||||||
|
template< class XRange2 >
|
||||||
|
sub_range& operator=( const XRange2& r );
|
||||||
|
|
||||||
|
public:
|
||||||
|
// rest of interface inherited from iterator_range
|
||||||
|
};
|
||||||
|
|
||||||
|
} // namespace 'boost'
|
||||||
|
|
||||||
|
</pre>
|
||||||
|
|
||||||
|
<hr>
|
||||||
|
<p>
|
||||||
|
(C) Copyright Thorsten Ottosen 2003-2004
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<br>
|
||||||
|
<br>
|
||||||
|
<br>
|
||||||
|
<br>
|
||||||
|
<br>
|
||||||
|
<br>
|
||||||
|
<br>
|
||||||
|
<br>
|
||||||
|
<br>
|
||||||
|
<br>
|
||||||
|
<br>
|
||||||
|
<br>
|
||||||
|
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
|
|
97
index.html
97
index.html
@@ -1,8 +1,95 @@
|
|||||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><head><title> Collection Traits </title><meta http-equiv="Content-Type"content="text/html; charset=iso-8859-1"></head>
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
|
||||||
<FRAMESET cols="100%">
|
|
||||||
<frame src="doc/collection_traits.html" >
|
<html>
|
||||||
</FRAMESET>
|
<head>
|
||||||
</HTML>
|
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
||||||
|
<title>Boost.Range Documentation </title>
|
||||||
|
<link rel="stylesheet" href="style.css" type="text/css">
|
||||||
|
</head>
|
||||||
|
|
||||||
|
<body>
|
||||||
|
<table border="0" >
|
||||||
|
<tr>
|
||||||
|
<td ><img src="doc/cboost.gif" border="0" ></td>
|
||||||
|
<td >
|
||||||
|
<h1 align="center">Range Library</h1>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
Copyright <20> 2003-2004 Thorsten Ottosen
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
Use, modification and distribution is subject to the Boost Software License, Version 1.0
|
||||||
|
(see <a href=http://www.boost.org/LICENSE_1_0.txt>
|
||||||
|
http://www.boost.org/LICENSE_1_0.txt</a>).
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<h1>Overview</h1>
|
||||||
|
<p>
|
||||||
|
Boost.Range is a collection of concepts and utilities that are particularly
|
||||||
|
useful for specifying and implementing generic algorithms. The documentation
|
||||||
|
consists of the following sections:
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li> Introduction
|
||||||
|
|
||||||
|
<li> Concepts:
|
||||||
|
<ul>
|
||||||
|
<li> Range
|
||||||
|
<li> ReversibleRange
|
||||||
|
<li> ExternalRange
|
||||||
|
<li> ExternalReversibleRange
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<li> Implementation of ExternalReversibleRange for
|
||||||
|
<ul>
|
||||||
|
<li> arrays
|
||||||
|
<li> Ranges
|
||||||
|
<li> strings
|
||||||
|
<li> pairs of iterators
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<li> <a href=doc/utility_class.html> Utility classses:</a>
|
||||||
|
<ul>
|
||||||
|
<li> <a href=doc/utility_class.html#iter_range><code>iterator_range</code></a>
|
||||||
|
<li> <a href=doc/utility_class.html#sub_range><code>sub_range</code></a> </ul>
|
||||||
|
|
||||||
|
<li>
|
||||||
|
Utility functions:
|
||||||
|
<ul>
|
||||||
|
<li> make_iterator_range()
|
||||||
|
<li> copy_range()
|
||||||
|
<li> transform_range()
|
||||||
|
</ul>
|
||||||
|
<li> Style and terminology guidelines
|
||||||
|
<li><a href="#headers">Headers</a> </li>
|
||||||
|
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<hr>
|
||||||
|
<p>
|
||||||
|
(C) Copyright Thorsten Ottosen 2003-2004
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<br>
|
||||||
|
<br>
|
||||||
|
<br>
|
||||||
|
<br>
|
||||||
|
<br>
|
||||||
|
<br>
|
||||||
|
<br>
|
||||||
|
<br>
|
||||||
|
<br>
|
||||||
|
<br>
|
||||||
|
<br>
|
||||||
|
<br>
|
||||||
|
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Reference in New Issue
Block a user