2004-06-29 02:58:13 +00:00
|
|
|
<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>
|
2004-08-05 19:37:40 +00:00
|
|
|
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
|
|
|
|
<Title>Range Concepts</Title>
|
|
|
|
|
<link rel="stylesheet" href="style.css" type="text/css">
|
2004-06-29 02:58:13 +00:00
|
|
|
</HEAD>
|
|
|
|
|
|
2004-08-05 19:37:40 +00:00
|
|
|
<table border="0" >
|
|
|
|
|
<tr>
|
|
|
|
|
<td ><img src="cboost.gif" border="0" ></td>
|
|
|
|
|
<td ><h1 align="center">Boost.Range </h1></td>
|
|
|
|
|
</tr>
|
|
|
|
|
</table>
|
|
|
|
|
|
|
|
|
|
<h2>Range concepts </h2>
|
|
|
|
|
|
|
|
|
|
<ul>
|
|
|
|
|
<li>
|
|
|
|
|
<a href="#range">Range</a>
|
|
|
|
|
<li>
|
|
|
|
|
<a href="#reversible_range">ReversibleRange</a>
|
|
|
|
|
</ul>
|
|
|
|
|
<hr>
|
|
|
|
|
|
|
|
|
|
<a name="range"><H1>Range</H1>
|
2004-06-29 02:58:13 +00:00
|
|
|
|
|
|
|
|
<h3>Description</h3>
|
|
|
|
|
|
2004-07-30 01:30:27 +00:00
|
|
|
A Range is a <i>concept</i> similar to the STL <a
|
2004-08-05 19:37:40 +00:00
|
|
|
href="http://www.sgi.com/Technology/STL/Container.html">Container</a> concept. A
|
|
|
|
|
Range provides iterators for accessing a range of elements and provides
|
|
|
|
|
information about the number of elements in the Range. However, a Range has
|
|
|
|
|
fewer requirements than a Container. The motivation for the Range 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. In particular, a Range does not necessarily
|
2004-06-29 02:58:13 +00:00
|
|
|
|
2004-07-30 01:30:27 +00:00
|
|
|
<ul>
|
2004-08-05 19:37:40 +00:00
|
|
|
<li>
|
|
|
|
|
own the elements that can be accessed through it,
|
|
|
|
|
<li>
|
|
|
|
|
have copy semantics,
|
|
|
|
|
<li>
|
|
|
|
|
require that the associated reference type is a real C++ reference.
|
2004-07-30 01:30:27 +00:00
|
|
|
</ul>
|
2004-06-29 02:58:13 +00:00
|
|
|
|
2004-08-05 19:37:40 +00:00
|
|
|
Because of the second requirement, a Range object must be passed by reference in
|
|
|
|
|
generic code.
|
2004-06-29 02:58:13 +00:00
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
|
2004-07-30 01:30:27 +00:00
|
|
|
<h3>Notation</h3>
|
|
|
|
|
<Table>
|
2004-08-05 19:37:40 +00:00
|
|
|
<TR>
|
|
|
|
|
<TD VAlign="top"><tt>X</tt></TD>
|
|
|
|
|
<TD VAlign="top">A type that is a model of Range.</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>
|
2004-07-30 01:30:27 +00:00
|
|
|
</table>
|
|
|
|
|
|
2004-06-29 02:58:13 +00:00
|
|
|
<h3>Associated types</h3>
|
|
|
|
|
|
2004-08-05 19:37:40 +00:00
|
|
|
<table border=1 cellpadding=5>
|
|
|
|
|
<TR>
|
|
|
|
|
<TD VAlign="top">Value type</TD>
|
|
|
|
|
<TD VAlign="top"><tt>value_type_of<X>::type</tt></TD>
|
|
|
|
|
<TD VAlign="top">The type of the object stored in a Range.
|
|
|
|
|
</TR>
|
|
|
|
|
<TR>
|
|
|
|
|
<TD VAlign="top">Iterator type</TD>
|
|
|
|
|
<TD VAlign="top"><tt>iterator_of<X>::type</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>const_iterator_of<X>::type</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>reference_of<X>::type</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">Distance type</TD>
|
|
|
|
|
<TD VAlign="top"><tt>difference_type_of<>::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>size_type_of<X>::type</tt></TD>
|
|
|
|
|
<TD VAlign="top">An unsigned integral type that can represent any nonnegative
|
|
|
|
|
value of the Range's distance type.</TD>
|
|
|
|
|
</tr>
|
2004-06-29 02:58:13 +00:00
|
|
|
</table>
|
|
|
|
|
|
2004-07-30 01:30:27 +00:00
|
|
|
|
2004-06-29 02:58:13 +00:00
|
|
|
<h3>Valid expressions</h3>
|
|
|
|
|
|
|
|
|
|
The following expressions must be valid.
|
|
|
|
|
<p>
|
|
|
|
|
|
2004-08-05 19:37:40 +00:00
|
|
|
<Table border=1 cellpadding=5>
|
|
|
|
|
<TR>
|
|
|
|
|
<TH>Name</TH>
|
|
|
|
|
<TH>Expression</TH>
|
|
|
|
|
<TH>Return type</TH>
|
|
|
|
|
</TR>
|
|
|
|
|
<TR>
|
|
|
|
|
<TD VAlign="top">Beginning of range</TD>
|
|
|
|
|
<TD VAlign="top"><tt>begin(a)</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>end(a)</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 of range</TD>
|
|
|
|
|
<TD VAlign="top"><tt>size(a)</tt></TD>
|
|
|
|
|
<TD VAlign="top"><tt>size_type</tt></TD>
|
|
|
|
|
</TR>
|
|
|
|
|
<TD VAlign="top">Is range empty?</TD>
|
|
|
|
|
<TD VAlign="top"><tt>empty(a)</tt></TD>
|
|
|
|
|
<TD VAlign="top">Convertible to <tt>bool</tt></TD>
|
|
|
|
|
</TR>
|
|
|
|
|
<TR>
|
|
|
|
|
</tr>
|
2004-06-29 02:58:13 +00:00
|
|
|
</table>
|
|
|
|
|
<h3>Expression semantics</h3>
|
|
|
|
|
|
|
|
|
|
<Table border>
|
2004-08-05 19:37:40 +00:00
|
|
|
<TR>
|
|
|
|
|
<TH>Expression</TH>
|
|
|
|
|
<TH>Semantics</TH>
|
|
|
|
|
<TH>Postcondition</TH>
|
|
|
|
|
</TR>
|
|
|
|
|
<TD VAlign="top">
|
|
|
|
|
<TR>
|
|
|
|
|
<TD VAlign="top"><tt>begin(a)</tt></TD>
|
|
|
|
|
<TD VAlign="top">Returns an iterator pointing to the first element in the Range.</TD>
|
|
|
|
|
<TD VAlign="top"><tt>begin(a)</tt> is either dereferenceable or
|
|
|
|
|
past-the-end. It is past-the-end if and only if <tt>size(a) == 0</tt>.</TD>
|
|
|
|
|
</TR>
|
|
|
|
|
<TR>
|
|
|
|
|
<TD VAlign="top"><tt>end(a)</tt></TD>
|
|
|
|
|
<TD VAlign="top">Returns an iterator pointing one past the last element in the
|
|
|
|
|
Range.</TD>
|
|
|
|
|
<TD VAlign="top"><tt>end(a)</tt> is past-the-end.</TD>
|
|
|
|
|
</TR>
|
|
|
|
|
<TR>
|
|
|
|
|
<TD VAlign="top"><tt>size(a)</tt></TD>
|
|
|
|
|
<TD VAlign="top">Returns the size of the Collection, that is, its number of
|
|
|
|
|
elements.</TD>
|
|
|
|
|
<TD VAlign="top"><tt>size(a) >= 0</TD>
|
|
|
|
|
</TR>
|
|
|
|
|
<TR>
|
|
|
|
|
<TD VAlign="top"><tt>empty(a)</tt></TD>
|
|
|
|
|
<TD VAlign="top">Equivalent to <tt>size(a) == 0</tt>. (But
|
|
|
|
|
possibly faster.)</TD> <TD VAlign="top"> - </TD>
|
|
|
|
|
</TR>
|
2004-06-29 02:58:13 +00:00
|
|
|
</table>
|
2004-08-05 19:37:40 +00:00
|
|
|
|
2004-06-29 02:58:13 +00:00
|
|
|
<h3>Complexity guarantees</h3>
|
|
|
|
|
|
2004-08-05 19:37:40 +00:00
|
|
|
All four functions are at most amortized linear time. For most practical
|
|
|
|
|
purposes, one can expect <tt>begin(a)</tt>, <tt>end(a)</tt> and
|
|
|
|
|
<tt>empty(a)</tt> to be amortized constant time.
|
2004-07-30 01:30:27 +00:00
|
|
|
|
2004-06-29 02:58:13 +00:00
|
|
|
<h3>Invariants</h3>
|
|
|
|
|
<Table border>
|
2004-08-05 19:37:40 +00:00
|
|
|
<TR>
|
|
|
|
|
<TD VAlign="top">Valid range</TD>
|
|
|
|
|
<TD VAlign="top">For any Range <tt>a</tt>, <tt>[begin(a),end(a))</tt> is a
|
|
|
|
|
valid range, that is, <code>end(a)</code> is reachable from <code>begin(a)</code>
|
|
|
|
|
in a finite number of increments.</TD>
|
|
|
|
|
</TR>
|
|
|
|
|
<TR>
|
|
|
|
|
<TD VAlign="top">Range size</TD>
|
|
|
|
|
<TD VAlign="top"><tt>size(a)</tt> is equal to the distance from
|
|
|
|
|
<tt>begin(a)</tt> to <tt>end(a)</tt>.</TD>
|
|
|
|
|
</TR>
|
|
|
|
|
<TR>
|
|
|
|
|
<TD VAlign="top">Completeness</TD>
|
|
|
|
|
<TD VAlign="top">An algorithm that iterates through the range
|
|
|
|
|
<tt>[begin(a),end(a))</tt> will pass through every element of <tt>a</tt>.</TD>
|
|
|
|
|
</tr>
|
2004-06-29 02:58:13 +00:00
|
|
|
</table>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<h3>Models</h3>
|
|
|
|
|
<UL>
|
2004-08-05 19:37:40 +00:00
|
|
|
<li>
|
|
|
|
|
<code>All models of <A href="http://www.sgi.com/Technology/STL/Container.html">Container</A></code>
|
|
|
|
|
<LI>
|
|
|
|
|
<tt>boost::array<T,sz></tt>
|
|
|
|
|
<LI>
|
|
|
|
|
<tt>std::vector<bool></tt>
|
2004-06-29 02:58:13 +00:00
|
|
|
</UL>
|
|
|
|
|
|
2004-08-05 19:37:40 +00:00
|
|
|
<h3>See also</h3> <A href="http://www.sgi.com/Technology/STL/Container.html">Container</A>
|
2004-06-29 02:58:13 +00:00
|
|
|
|
2004-08-05 19:37:40 +00:00
|
|
|
<br>
|
|
|
|
|
<br>
|
2004-07-30 01:30:27 +00:00
|
|
|
<hr>
|
|
|
|
|
<br>
|
2004-06-29 02:58:13 +00:00
|
|
|
|
2004-08-05 19:37:40 +00:00
|
|
|
<a name=reversible_range><h1>ReversibleRange</h1>
|
2004-07-30 01:30:27 +00:00
|
|
|
|
2004-07-30 02:56:01 +00:00
|
|
|
|
2004-08-05 19:37:40 +00:00
|
|
|
<h3>Description</h3> This concept 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.
|
2004-07-30 01:30:27 +00:00
|
|
|
|
2004-08-05 19:37:40 +00:00
|
|
|
<h3>Refinement of</h3> Range
|
2004-07-30 01:30:27 +00:00
|
|
|
|
|
|
|
|
<h3>Associated types</h3>
|
|
|
|
|
|
|
|
|
|
<Table border>
|
2004-08-05 19:37:40 +00:00
|
|
|
<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>
|
2004-06-29 02:58:13 +00:00
|
|
|
</table>
|
|
|
|
|
|
|
|
|
|
|
2004-07-30 01:30:27 +00:00
|
|
|
<h3>Valid expressions</h3>
|
2004-08-05 19:37:40 +00:00
|
|
|
|
2004-06-29 02:58:13 +00:00
|
|
|
<Table border>
|
2004-08-05 19:37:40 +00:00
|
|
|
<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>rbegin(a)</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(end(a))</tt>.</TD> </TR>
|
|
|
|
|
<TR>
|
|
|
|
|
<TD VAlign="top">End of range</TD>
|
|
|
|
|
<TD VAlign="top"><tt>rend(a)</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(begin(a))</tt>.</TD> </tr>
|
2004-06-29 02:58:13 +00:00
|
|
|
|
|
|
|
|
</table>
|
|
|
|
|
|
2004-07-30 01:30:27 +00:00
|
|
|
<h3>Complexity guarantees</h3>
|
|
|
|
|
|
2004-08-05 19:37:40 +00:00
|
|
|
<tt>rbegin(a)</tt> has the same complexity as <tt>end(a)</tt> and
|
|
|
|
|
<tt>rend(a)</tt> has the same complexity as <tt>begin(a)</tt> from Range.
|
2004-06-29 02:58:13 +00:00
|
|
|
|
2004-07-30 01:30:27 +00:00
|
|
|
<h3>Models</h3>
|
|
|
|
|
|
|
|
|
|
<ul>
|
2004-08-05 19:37:40 +00:00
|
|
|
<li>
|
|
|
|
|
std::vector<T>
|
|
|
|
|
<li>
|
|
|
|
|
std::list<T>
|
2004-07-30 01:30:27 +00:00
|
|
|
</ul>
|
2004-06-29 02:58:13 +00:00
|
|
|
|
2004-07-30 01:30:27 +00:00
|
|
|
<hr>
|
2004-06-29 02:58:13 +00:00
|
|
|
<h3>Notes</h3>
|
|
|
|
|
|
2004-08-05 19:37:40 +00:00
|
|
|
<P>
|
|
|
|
|
<A name="1">[1]</A>
|
2004-06-29 02:58:13 +00:00
|
|
|
|
2004-08-05 19:37:40 +00:00
|
|
|
The reference type does not have to be a real C++ reference. The requirements of
|
|
|
|
|
the reference type is that it <i>behaves</i> like a real reference. Hence the
|
|
|
|
|
reference type must be convertible to the value_type and assignment through
|
2004-06-29 02:58:13 +00:00
|
|
|
|
2004-08-05 19:37:40 +00:00
|
|
|
<br>
|
|
|
|
|
<br>
|
2004-06-29 02:58:13 +00:00
|
|
|
<HR>
|
2004-07-30 01:30:27 +00:00
|
|
|
<br>
|
|
|
|
|
|
2004-06-29 02:58:13 +00:00
|
|
|
<TABLE>
|
2004-08-05 19:37:40 +00:00
|
|
|
<TR valign="top">
|
|
|
|
|
<TD nowrap>Copyright © 2000</TD>
|
|
|
|
|
<TD><A HREF=http://www.boost.org/people/jeremy_siek.htm>Jeremy Siek</A>
|
|
|
|
|
</TR>
|
|
|
|
|
<tr >
|
|
|
|
|
<TD nowrap>Copyright © 2004</TD>
|
|
|
|
|
<TD>Thorsten Ottosen.
|
2004-06-29 02:58:13 +00:00
|
|
|
</TABLE>
|
|
|
|
|
|
|
|
|
|
</BODY>
|
2004-08-05 19:37:40 +00:00
|
|
|
</HTML>
|
