2008-06-24 15:39:28 +00:00
|
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
|
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-10 09:56:55 +00:00
|
|
|
<table border="0" >
|
|
|
|
<tr>
|
2004-10-05 15:45:52 +00:00
|
|
|
<td ><img src="../../../boost.png" border="0" ></td>
|
2004-08-10 09:56:55 +00:00
|
|
|
<td ><h1 align="center">Boost.Range </h1></td>
|
|
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
|
|
|
|
<h2>Range concepts </h2>
|
|
|
|
|
|
|
|
<ul>
|
|
|
|
<li>
|
|
|
|
<a href="#overview">Overview</a>
|
|
|
|
<li>
|
|
|
|
<a href="#single_pass_range">Single Pass Range</a>
|
|
|
|
<li>
|
|
|
|
<a href="#forward_range">Forward Range</a>
|
|
|
|
<li>
|
|
|
|
<a href="#bidirectional_range">Bidirectional Range</a>
|
|
|
|
<li>
|
|
|
|
<a href="#random_access_range">Random Access Range</a>
|
2006-03-08 21:40:14 +00:00
|
|
|
<li>
|
|
|
|
<a href="#concept_checking">Concept Checking</a>
|
2004-08-10 09:56:55 +00:00
|
|
|
</ul>
|
|
|
|
|
|
|
|
<a name="overview"></a>
|
|
|
|
<hr>
|
|
|
|
<h3>Overview</h3>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
A Range is a <i>concept</i> similar to the STL <a
|
2005-08-12 13:02:37 +00:00
|
|
|
href="http://www.sgi.com/Technology/STL/Container.html">Container</a> concept. A
|
2005-07-18 19:50:41 +00:00
|
|
|
Range provides iterators for accessing a half-open range
|
2004-08-10 09:56:55 +00:00
|
|
|
<code>[first,one_past_last)</code> of elements and provides
|
2005-08-12 13:02:37 +00:00
|
|
|
information about the number of elements in the Range. However, a Range has
|
2007-11-09 10:27:42 +00:00
|
|
|
<i>much</i> fewer requirements than a Container.
|
2005-08-12 13:02:37 +00:00
|
|
|
</p>
|
2004-08-10 09:56:55 +00:00
|
|
|
<p>
|
2005-08-12 13:02:37 +00:00
|
|
|
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
|
2004-08-10 09:56:55 +00:00
|
|
|
reduced set of requirements. In particular, a Range does not necessarily
|
|
|
|
|
|
|
|
<ul>
|
|
|
|
<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.
|
|
|
|
-->
|
|
|
|
</ul>
|
|
|
|
|
2005-08-12 13:02:37 +00:00
|
|
|
|
|
|
|
Because of the second requirement, a Range object must be passed by
|
2004-08-24 15:58:01 +00:00
|
|
|
(const or non-const) reference in generic code.
|
2004-08-10 09:56:55 +00:00
|
|
|
|
|
|
|
</p>
|
|
|
|
<p>
|
2005-08-12 13:02:37 +00:00
|
|
|
The operations that can be performed on a Range is dependent on the
|
|
|
|
<a href="../../iterator/doc/new-iter-concepts.html#iterator-traversal-concepts-lib-iterator-traversal">traversal
|
2004-08-10 09:56:55 +00:00
|
|
|
category</a> of the underlying iterator type. Therefore
|
2007-11-09 10:27:42 +00:00
|
|
|
the range concepts are named to reflect which traversal category their
|
|
|
|
iterators support. See also <a href="style.html">terminology and style
|
|
|
|
guidelines.</a> for more information about naming of ranges.</p>
|
2005-08-12 13:02:37 +00:00
|
|
|
|
2004-08-12 10:58:13 +00:00
|
|
|
<p> The concepts described below specifies associated types as
|
2005-08-12 13:02:37 +00:00
|
|
|
<a href="../../mpl/doc/refmanual/metafunction.html">metafunctions</a> and all
|
2004-08-12 10:58:13 +00:00
|
|
|
functions as free-standing functions to allow for a layer of indirection. </p>
|
2004-08-10 09:56:55 +00:00
|
|
|
|
2005-08-12 13:02:37 +00:00
|
|
|
<!--<p><i>Notice that these metafunctions must be defined in namespace </i>
|
|
|
|
<code>boost</code></p>-->
|
2005-05-03 22:39:49 +00:00
|
|
|
|
2004-08-10 09:56:55 +00:00
|
|
|
<hr>
|
2008-06-24 15:39:28 +00:00
|
|
|
<a name="single_pass_range"></a>
|
2004-08-10 09:56:55 +00:00
|
|
|
<H2>Single Pass Range</H2>
|
|
|
|
|
|
|
|
<h3>Notation</h3>
|
|
|
|
<Table>
|
2004-08-05 19:37:40 +00:00
|
|
|
<TR>
|
2004-08-10 09:56:55 +00:00
|
|
|
<TD VAlign="top"><code>X</code></TD>
|
|
|
|
<TD VAlign="top">A type that is a model of Single Pass Range.</TD>
|
|
|
|
</TR>
|
|
|
|
<TR>
|
|
|
|
<TD VAlign="top"><code>a</code></TD>
|
|
|
|
<TD VAlign="top">Object of type <code>X</code>.</TD>
|
|
|
|
</TR>
|
|
|
|
</table>
|
|
|
|
|
2005-08-12 13:02:37 +00:00
|
|
|
|
2004-08-10 09:56:55 +00:00
|
|
|
<h3>Description</h3>
|
|
|
|
<p>
|
2005-08-12 13:02:37 +00:00
|
|
|
A range X where <code>boost::range_iterator<X>::type</code> is a model of <a
|
2004-08-10 09:56:55 +00:00
|
|
|
href="../../iterator/doc/new-iter-concepts.html#single-pass-iterators-lib-single-pass-iterators">
|
|
|
|
Single Pass Iterator</a>
|
|
|
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
<h3>Associated types</h3>
|
|
|
|
|
|
|
|
<table border="1" cellpadding="5">
|
2007-11-09 10:27:42 +00:00
|
|
|
|
2004-08-10 09:56:55 +00:00
|
|
|
<TR>
|
|
|
|
<TD VAlign="top">Iterator type</TD>
|
2005-08-12 13:02:37 +00:00
|
|
|
<TD VAlign="top"><code>boost::range_iterator<X>::type</code></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
|
2004-08-10 09:56:55 +00:00
|
|
|
conversion from the iterator type to the const iterator type must exist.
|
|
|
|
</TR>
|
|
|
|
<TR>
|
|
|
|
<TD VAlign="top">Const iterator type</TD>
|
2007-11-09 10:27:42 +00:00
|
|
|
<TD VAlign="top"><code>boost::range_iterator<const X>::type</code></TD>
|
2005-08-12 13:02:37 +00:00
|
|
|
<TD VAlign="top">A type of iterator that may be used to examine, but not to
|
2004-08-10 09:56:55 +00:00
|
|
|
modify, a Range's elements.</TD>
|
|
|
|
</TR>
|
|
|
|
<!--
|
|
|
|
<TR>
|
|
|
|
<TD VAlign="top">Reference type</TD>
|
|
|
|
<TD VAlign="top"><code>reference_of<X>::type</code></TD>
|
|
|
|
<TD VAlign="top">A type that behaves like a reference to the Range's value type. <a href="#1">[1]</a></TD>
|
|
|
|
</TR>
|
|
|
|
-->
|
|
|
|
</table>
|
|
|
|
|
|
|
|
|
|
|
|
<h3>Valid expressions</h3>
|
|
|
|
|
|
|
|
The following expressions must be valid.
|
|
|
|
<p>
|
|
|
|
|
|
|
|
<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>
|
2005-08-12 13:02:37 +00:00
|
|
|
<TD VAlign="top"><code>boost::begin(a)</code></TD>
|
|
|
|
<TD VAlign="top"><code>boost::range_iterator<X>::type</code> if
|
2007-11-09 10:27:42 +00:00
|
|
|
<code>a</code> is mutable, <code>boost::range_iterator<const X>::type</code>
|
2004-08-10 09:56:55 +00:00
|
|
|
otherwise</TD> </TR>
|
|
|
|
<TR>
|
|
|
|
<TD VAlign="top">End of range</TD>
|
2005-08-12 13:02:37 +00:00
|
|
|
<TD VAlign="top"><code>boost::end(a)</code></TD>
|
|
|
|
<TD VAlign="top"><code>boost::range_iterator<X>::type</code> if
|
2007-11-09 10:27:42 +00:00
|
|
|
<code>a</code> is mutable, <code>boost::range_iterator<const X>::type</code>
|
2004-08-10 09:56:55 +00:00
|
|
|
otherwise</TD>
|
|
|
|
</TR>
|
2007-11-09 10:27:42 +00:00
|
|
|
|
2004-08-10 09:56:55 +00:00
|
|
|
</table>
|
|
|
|
<h3>Expression semantics</h3>
|
|
|
|
|
|
|
|
<Table border>
|
|
|
|
<TR>
|
|
|
|
<TH>Expression</TH>
|
|
|
|
<TH>Semantics</TH>
|
|
|
|
<TH>Postcondition</TH>
|
|
|
|
</TR>
|
|
|
|
<TR>
|
2005-08-12 13:02:37 +00:00
|
|
|
<TD VAlign="top"><code>boost::begin(a)</code></TD>
|
2004-08-05 19:37:40 +00:00
|
|
|
<TD VAlign="top">Returns an iterator pointing to the first element in the Range.</TD>
|
2005-08-12 13:02:37 +00:00
|
|
|
<TD VAlign="top"><code>boost::begin(a)</code> is either dereferenceable or past-the-end.
|
2007-11-09 10:27:42 +00:00
|
|
|
It is past-the-end if and only if <code>boost::distance(a) == 0</code>.</TD>
|
2004-08-05 19:37:40 +00:00
|
|
|
</TR>
|
|
|
|
<TR>
|
2005-08-12 13:02:37 +00:00
|
|
|
<TD VAlign="top"><code>boost::end(a)</code></TD>
|
2004-08-05 19:37:40 +00:00
|
|
|
<TD VAlign="top">Returns an iterator pointing one past the last element in the
|
|
|
|
Range.</TD>
|
2005-08-12 13:02:37 +00:00
|
|
|
<TD VAlign="top"><code>boost::end(a)</code> is past-the-end.</TD>
|
2004-08-10 09:56:55 +00:00
|
|
|
</TR>
|
2007-11-09 10:27:42 +00:00
|
|
|
|
2004-08-10 09:56:55 +00:00
|
|
|
</table>
|
|
|
|
|
|
|
|
<h3>Complexity guarantees</h3>
|
|
|
|
|
2007-11-09 10:27:42 +00:00
|
|
|
<code>boost::end(a)</code> is at most amortized linear time, <code>boost::begin(a)</code> is
|
|
|
|
amortized constant time. For most practical
|
|
|
|
purposes, one can expect both to be amortized constant time.
|
2004-08-10 09:56:55 +00:00
|
|
|
|
|
|
|
<h3>Invariants</h3>
|
|
|
|
<Table border>
|
|
|
|
<TR>
|
|
|
|
<TD VAlign="top">Valid range</TD>
|
2005-08-12 13:02:37 +00:00
|
|
|
<TD VAlign="top">For any Range <code>a</code>, <code>[boost::begin(a),boost::end(a))</code> is
|
|
|
|
a valid range, that is, <code>boost::end(a)</code> is reachable from <code>boost::begin(a)</code>
|
2004-08-10 09:56:55 +00:00
|
|
|
in a finite number of increments.</TD>
|
|
|
|
</TR>
|
|
|
|
<TR>
|
|
|
|
<TD VAlign="top">Completeness</TD>
|
2005-08-12 13:02:37 +00:00
|
|
|
<TD VAlign="top">An algorithm that iterates through the range <code>[boost::begin(a),boost::end(a))</code>
|
2004-08-10 09:56:55 +00:00
|
|
|
will pass through every element of <code>a</code>.</TD>
|
|
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
|
|
|
|
|
|
|
|
<h3>See also</h3>
|
2007-11-09 10:27:42 +00:00
|
|
|
<p><a
|
|
|
|
href="boost_range.html#minimal_interface">Extending the library for UDTs </a></p>
|
|
|
|
<p> <a href="boost_range.html#boost::rang_difference">Implementation of
|
2005-05-03 22:39:49 +00:00
|
|
|
metafunctions </a></p>
|
|
|
|
|
2007-11-09 10:27:42 +00:00
|
|
|
<p> <a href="boost_range.html#begin">Implementation of
|
2005-05-03 22:39:49 +00:00
|
|
|
functions </a></p>
|
2007-11-09 10:27:42 +00:00
|
|
|
<p>
|
|
|
|
<A href="http://www.sgi.com/Technology/STL/Container.html">Container</A>
|
|
|
|
</p>
|
|
|
|
|
2004-08-10 09:56:55 +00:00
|
|
|
|
|
|
|
<hr>
|
2008-06-24 15:39:28 +00:00
|
|
|
<a name=forward_range></a><h2>Forward Range</h2>
|
2004-08-10 09:56:55 +00:00
|
|
|
|
|
|
|
<h3>Notation</h3>
|
|
|
|
<Table>
|
|
|
|
<TR>
|
|
|
|
<TD VAlign="top"><code>X</code></TD>
|
|
|
|
<TD VAlign="top">A type that is a model of Forward Range.</TD>
|
2004-08-05 19:37:40 +00:00
|
|
|
</TR>
|
|
|
|
<TR>
|
2004-08-10 09:56:55 +00:00
|
|
|
<TD VAlign="top"><code>a</code></TD>
|
|
|
|
<TD VAlign="top">Object of type <code>X</code>.</TD>
|
|
|
|
</TR>
|
|
|
|
</table>
|
|
|
|
|
|
|
|
<h3>Description</h3>
|
|
|
|
<p>
|
2005-08-12 13:02:37 +00:00
|
|
|
A range <code>X</code> where <code>boost::range_iterator<X>::type</code> is a model
|
2004-08-10 09:56:55 +00:00
|
|
|
of <a
|
|
|
|
href="../../iterator/doc/new-iter-concepts.html#forward-traversal-iterators-lib-forward-traversal-iterators">Forward Traversal Iterator</a>
|
|
|
|
</p>
|
|
|
|
|
|
|
|
<h3>Refinement of</h3> <a href="#single_pass_range">Single Pass
|
|
|
|
Range</a>
|
|
|
|
|
2007-11-09 10:27:42 +00:00
|
|
|
</p>
|
|
|
|
|
2004-08-10 09:56:55 +00:00
|
|
|
<hr>
|
|
|
|
|
2008-06-24 15:39:28 +00:00
|
|
|
<a name="bidirectional_range"></a><h2>Bidirectional Range</h2>
|
2004-08-10 09:56:55 +00:00
|
|
|
|
|
|
|
<h3>Notation</h3>
|
|
|
|
<Table>
|
|
|
|
<TR>
|
|
|
|
<TD VAlign="top"><code>X</code></TD>
|
|
|
|
<TD VAlign="top">A type that is a model of Bidirectional Range.</TD>
|
|
|
|
</TR>
|
|
|
|
<TR>
|
|
|
|
<TD VAlign="top"><code>a</code></TD>
|
|
|
|
<TD VAlign="top">Object of type <code>X</code>.</TD>
|
|
|
|
</TR>
|
|
|
|
</table>
|
|
|
|
|
|
|
|
<h3>Description</h3> This concept provides access to iterators that traverse in
|
|
|
|
both directions (forward and reverse). The
|
2005-08-12 13:02:37 +00:00
|
|
|
<code>boost::range_iterator<X>::type</code> iterator must meet all of the requirements
|
2004-08-10 09:56:55 +00:00
|
|
|
of <a
|
|
|
|
href="../../iterator/doc/new-iter-concepts.html#bidirectional-traversal-iterator
|
|
|
|
s-lib-bidirectional-traversal-iterators">Bidirectional Traversal Iterator.</a>
|
|
|
|
|
|
|
|
<h3>Refinement of</h3> <a href="#forward_range">Forward Range</a>
|
|
|
|
|
2007-11-09 10:27:42 +00:00
|
|
|
|
|
|
|
</p>
|
2005-05-03 22:39:49 +00:00
|
|
|
|
2004-08-10 09:56:55 +00:00
|
|
|
<hr>
|
|
|
|
|
2008-06-24 15:39:28 +00:00
|
|
|
<a name=random_access_range></a><h2>Random Access Range</h2>
|
|
|
|
<h3>Description</h3>
|
2004-08-10 09:56:55 +00:00
|
|
|
<p>
|
2005-08-12 13:02:37 +00:00
|
|
|
A range <code>X</code> where <code>boost::range_iterator<X>::type</code> is a model
|
2004-08-10 09:56:55 +00:00
|
|
|
of <a
|
2004-10-06 18:19:13 +00:00
|
|
|
|
|
|
|
href="../../iterator/doc/new-iter-concepts.html#random-access-traversal-iterators
|
2004-08-10 09:56:55 +00:00
|
|
|
-lib-random-access-traversal-iterators">Random Access Traversal Iterator</a>
|
|
|
|
</p>
|
|
|
|
|
|
|
|
<h3>Refinement of</h3>
|
|
|
|
<p>
|
|
|
|
<a href="#bidirectional_range">Bidirectional Range</a>
|
|
|
|
</p>
|
|
|
|
|
|
|
|
<hr>
|
|
|
|
|
2008-06-24 15:39:28 +00:00
|
|
|
<a name=concept_checking></a><h2>Concept Checking</h2>
|
2006-03-08 21:40:14 +00:00
|
|
|
|
|
|
|
Each of the range concepts has a corresponding concept checking
|
2008-06-24 15:39:28 +00:00
|
|
|
class in the file <code><boost/range/concepts.hpp></code>. These classes may be
|
2006-03-08 21:40:14 +00:00
|
|
|
used in conjunction with the <a
|
|
|
|
href="../../concept_check/concept_check.htm">Boost Concept
|
|
|
|
Check</a> library to insure that the type of a template parameter
|
|
|
|
is compatible with a range concept. If not, a meaningful compile
|
|
|
|
time error is generated. Checks are provided for the range
|
|
|
|
concepts related to iterator traversal categories. For example,
|
|
|
|
the following line checks that the type <code>T</code> models the
|
|
|
|
<a href="#forward_range">ForwardRange</a> concept.
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
function_requires<ForwardRangeConcept<T> >();
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
An additional concept check is required for the value access
|
|
|
|
property of the range based on the range's iterator type. For
|
|
|
|
example to check for a ForwardReadableRange, the following code is
|
|
|
|
required.
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
function_requires<ForwardRangeConcept<T> >();
|
|
|
|
function_requires<
|
|
|
|
ReadableIteratorConcept<
|
|
|
|
typename range_iterator<T>::type
|
|
|
|
>
|
|
|
|
>();
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
The following range concept checking classes are provided.
|
|
|
|
<ul>
|
|
|
|
<li>
|
|
|
|
Class <code>SinglePassRangeConcept</code> checks for <a
|
|
|
|
href="#single_pass_range">Single Pass Range</a>
|
|
|
|
<li>
|
|
|
|
Class <code>ForwardRangeConcept</code> checks for <a
|
|
|
|
href="#forward_range">Forward Range</a>
|
|
|
|
<li>
|
|
|
|
Class <code>BidirectionalRangeConcept</code> checks for <a
|
|
|
|
href="#bidirectional_range">Bidirectional Range</a>
|
|
|
|
<li>
|
|
|
|
Class <code>RandomAccessRangeConcept</code> checks for <a
|
|
|
|
href="#random_access_range">Random Access Range</a>
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
<h3>See also</h3>
|
|
|
|
<p> <a href="style.html">Range Terminology and style guidelines</a></p>
|
|
|
|
<p> <a href="../../iterator/doc/iterator_concepts.html">Iterator Concepts</a></p>
|
|
|
|
<p> <a href="../../concept_check/concept_check.htm">Boost Concept Check library</a></p>
|
|
|
|
|
|
|
|
<hr>
|
2008-02-06 23:12:21 +00:00
|
|
|
<p>
|
|
|
|
© <a name="Copyright" id="Copyright">Copyright</a> Thorsten Ottosen 2008.
|
|
|
|
</p>
|
2004-08-10 09:56:55 +00:00
|
|
|
|
2008-02-06 23:12:21 +00:00
|
|
|
<p>
|
|
|
|
Distributed under the Boost Software License, Version 1.0. (See
|
|
|
|
accompanying file LICENSE_1_0.txt or copy
|
|
|
|
at <a href=
|
|
|
|
"http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a>)
|
|
|
|
</p>
|
2004-08-10 09:56:55 +00:00
|
|
|
<br>
|
|
|
|
<br>
|
|
|
|
<br>
|
|
|
|
<br>
|
|
|
|
<br>
|
|
|
|
<br>
|
|
|
|
<br>
|
|
|
|
<br>
|
|
|
|
<br>
|
|
|
|
<br>
|
|
|
|
|
|
|
|
</BODY>
|
2004-08-05 19:37:40 +00:00
|
|
|
</HTML>
|