forked from boostorg/range
770 lines
48 KiB
HTML
770 lines
48 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<title>Boost.Range Reference </title>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link rel="stylesheet" href="style.css" type="text/css">
|
|
</head>
|
|
<body>
|
|
<table>
|
|
<tr>
|
|
<td><img src="../../../boost.png" width="100%" border="0"></td>
|
|
<td><h1><br>
|
|
Boost.Range
|
|
</h1>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<h2>Synopsis and Reference
|
|
</h2>
|
|
<ul>
|
|
<li>
|
|
<a href="#overview">Overview</a>
|
|
<li>
|
|
<a href="#Synopsis">Synopsis</a>
|
|
<li>
|
|
<a href="#Semantics">Semantics</a>
|
|
<li>
|
|
<a href="#minimal_interface">Extending the library</a></li>
|
|
</ul>
|
|
<hr size="1">
|
|
<a name="overview"></a>
|
|
<h3>Overview</h3>
|
|
<p>
|
|
Three types of objects are currently supported by the library:
|
|
<ul>
|
|
<li>
|
|
standard-like containers
|
|
<li>
|
|
<code>std::pair<iterator,iterator></code>
|
|
<li>
|
|
built-in arrays
|
|
</li>
|
|
</ul>
|
|
Even though the behavior of the primary templates are exactly such that
|
|
standard containers will be supported by default, the requirements are much
|
|
lower than the standard container requirements. For example, the utility class <a href="utility_class.html#iter_range">
|
|
<code>iterator_range</code></a> implements the <a href="#minimal_interface">minimal
|
|
interface</a> required to make the class a <a href="range.html#forward_range">Forward
|
|
Range</a>
|
|
.
|
|
<P></P>
|
|
<p>
|
|
Please also see <a href="range.html">Range concepts</a> for more details.
|
|
</p>
|
|
<a name="Synopsis"></a>
|
|
<h3>Synopsis</h3>
|
|
<p>
|
|
<pre>
|
|
<span class=keyword>namespace </span><span class=identifier>boost</span>
|
|
<span class=special>{
|
|
</span><span class=comment>//
|
|
// Single Pass Range metafunctions
|
|
//
|
|
|
|
</span><span class=keyword>template</span><span class=special>< </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>>
|
|
</span><span class=keyword>struct </span><a href="#range_iterator"><span
|
|
class=identifier>range_iterator</span></a><span class=special>;
|
|
|
|
</span><span class=keyword>template</span><span class=special>< </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>>
|
|
</span><span class=keyword>struct </span><a href="#range_value"><span
|
|
class=identifier>range_value</span></a><span class=special>;
|
|
|
|
</span><span class=keyword>template</span><span class=special>< </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>>
|
|
</span><span class=keyword>struct </span><a href="#range_reference"><span
|
|
class=identifier>range_reference</span></a><span class=special>;
|
|
|
|
</span><span class=keyword>template</span><span class=special>< </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>>
|
|
</span><span class=keyword>struct </span><a href="#range_pointer"><span
|
|
class=identifier>range_pointer</span></a><span class=special>;
|
|
|
|
</span><span class=keyword>template</span><span class=special>< </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>>
|
|
</span><span class=keyword>struct </span><a href="#range_category"><span
|
|
class=identifier>range_category</span></a><span class=special>;
|
|
|
|
</span><span class=comment>//
|
|
// Forward Range metafunctions
|
|
//
|
|
|
|
</span><span class=keyword>template</span><span class=special>< </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>>
|
|
</span><span class=keyword>struct </span><a href="#range_difference"><span
|
|
class=identifier>range_difference</span></a><span class=special>;
|
|
|
|
</span><span class=comment>//
|
|
// Bidirectional Range metafunctions
|
|
//
|
|
|
|
</span><span class=keyword>template</span><span class=special>< </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>>
|
|
</span><span class=keyword>struct </span><a
|
|
href="#range_reverse_iterator"><span
|
|
class=identifier>range_reverse_iterator</span></a><span class=special>;
|
|
|
|
</span><span class=comment>//
|
|
// Single Pass Range functions
|
|
//
|
|
|
|
</span><span class=keyword>template</span><span class=special>< </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>>
|
|
</span><span class=keyword></span><span class=keyword>typename </span><span class=identifier>range_iterator</span><span class=special><</span><span class=identifier>T</span><span class=special>>::</span><span class=identifier>type
|
|
</span><a href="#begin"><span class=identifier>begin</span></a><span class=special>( </span><span class=identifier>T</span><span class=special>& </span><span class=identifier>r </span><span class=special>);
|
|
|
|
</span><span class=keyword>template</span><span class=special>< </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>>
|
|
</span><span class=keyword></span><span class=keyword>typename </span><span class=identifier>range_iterator</span><span class=special><</span><span class=keyword>const </span><span class=identifier>T</span><span class=special>>::</span><span class=identifier>type
|
|
</span><a href="#begin"><span class=identifier>begin</span></a><span class=special>( </span><span class=keyword>const </span><span class=identifier>T</span><span class=special>& </span><span class=identifier>r </span><span class=special>);
|
|
|
|
</span><span class=keyword>template</span><span class=special>< </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>>
|
|
</span><span class=keyword></span><span class=keyword>typename </span><span class=identifier>range_iterator</span><span class=special><</span><span class=identifier>T</span><span class=special>>::</span><span class=identifier>type
|
|
</span><a href="#end"><span class=identifier>end</span></a><span class=special>( </span><span class=identifier>T</span><span class=special>& </span><span class=identifier>r </span><span class=special>);
|
|
|
|
</span><span class=keyword>template</span><span class=special>< </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>>
|
|
</span><span class=keyword></span><span class=keyword>typename </span><span class=identifier>range_iterator</span><span class=special><</span><span class=keyword>const </span><span class=identifier>T</span><span class=special>>::</span><span class=identifier>type
|
|
</span><a href="#end"><span class=identifier>end</span></a><span class=special>( </span><span class=keyword>const </span><span class=identifier>T</span><span class=special>& </span><span class=identifier>r </span><span class=special>);
|
|
|
|
</span><span class=keyword>template</span><span class=special>< </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>>
|
|
</span><span class=keyword></span><span class=keyword>bool
|
|
</span><a href="#empty"><span class=identifier>empty</span></a><span class=special>( </span><span class=keyword>const </span><span class=identifier>T</span><span class=special>& </span><span class=identifier>r </span><span class=special>);
|
|
|
|
</span><span class=comment>//
|
|
// Forward Range functions
|
|
//
|
|
|
|
</span><span class=keyword>template</span><span class=special>< </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>>
|
|
</span><span class=keyword></span><span class=keyword>typename </span><span class=identifier>range_difference</span><span class=special><</span><span class=identifier>T</span><span class=special>>::</span><span class=identifier>type
|
|
</span><a href="#size"><span class=identifier>distance</span></a><span class=special>( </span><span class=keyword>const </span><span class=identifier>T</span><span class=special>& </span><span class=identifier>r </span><span class=special>);
|
|
|
|
</span><span class=comment>//
|
|
// Bidirectional Range functions
|
|
//
|
|
|
|
</span><span class=keyword>template</span><span class=special>< </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>>
|
|
</span><span class=keyword></span><span class=keyword>typename </span><span class=identifier>range_reverse_iterator</span><span class=special><</span><span class=identifier>T</span><span class=special>>::</span><span class=identifier>type
|
|
</span><a href="#rbegin"><span class=identifier>rbegin</span></a><span class=special>( </span><span class=identifier>T</span><span class=special>& </span><span class=identifier>r </span><span class=special>);
|
|
|
|
</span><span class=keyword>template</span><span class=special>< </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>>
|
|
</span><span class=keyword></span><span class=keyword>typename </span><span class=identifier>range_reverse_iterator</span><span class=special><</span><span class=keyword>const </span><span class=identifier>T</span><span class=special>>::</span><span class=identifier>type
|
|
</span><a href="#rbegin"><span class=identifier>rbegin</span></a><span class=special>( </span><span class=keyword>const </span><span class=identifier>T</span><span class=special>& </span><span class=identifier>r </span><span class=special>);
|
|
|
|
</span><span class=keyword>template</span><span class=special>< </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>>
|
|
</span><span class=keyword></span><span class=keyword>typename </span><span class=identifier>range_reverse_iterator</span><span class=special><</span><span class=identifier>T</span><span class=special>>::</span><span class=identifier>type
|
|
</span><a href="#rend"><span class=identifier>rend</span></a><span class=special>( </span><span class=identifier>T</span><span class=special>& </span><span class=identifier>r </span><span class=special>);
|
|
|
|
</span><span class=keyword>template</span><span class=special>< </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>>
|
|
</span><span class=keyword></span><span class=keyword>typename </span><span class=identifier>range_reverse_iterator</span><span class=special><</span><span class=keyword>const </span><span class=identifier>T</span><span class=special>>::</span><span class=identifier>type
|
|
</span><a href="#rend"><span class=identifier>rend</span></a><span class=special>( </span><span class=keyword>const </span><span
|
|
class=identifier>T</span><span class=special>& </span><span class=identifier>r </span><span class=special>);
|
|
</span>
|
|
<span class=comment>//
|
|
// Random Access Range functions
|
|
//
|
|
|
|
</span><span class=keyword>template</span><span class=special>< </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>>
|
|
</span><span class=keyword></span><span class=keyword>typename </span><span class=identifier>range_difference</span><span class=special><</span><span class=identifier>T</span><span class=special>>::</span><span class=identifier>type
|
|
</span><a href="#size"><span class=identifier>size</span></a><span class=special>( </span><span class=keyword>const </span><span class=identifier>T</span><span class=special>& </span><span class=identifier>r </span><span class=special>);</span>
|
|
|
|
<span class=comment>//
|
|
// Special const Range functions
|
|
//
|
|
</span>
|
|
<span class=keyword>template</span><span class=special>< </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>></span>
|
|
<span class=keyword>typename </span><span class=identifier>range_iterator</span><span class=special><</span><span class=keyword>const </span><span class=identifier>T</span><span class=special>>::</span><span class=identifier>type </span>
|
|
<a href="#const_begin"><span class=identifier>const_begin</span></a><span class=special>(</span><span class=keyword> const </span><span class=identifier>T</span><span class=special>& </span><span class=identifier>r </span><span class=special>);
|
|
</span>
|
|
<span class=keyword>template</span><span class=special>< </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>></span>
|
|
<span class=keyword>typename </span><span class=identifier>range_iterator</span><span class=special><</span><span class=keyword>const </span><span class=identifier>T</span><span class=special>>::</span><span class=identifier>type </span>
|
|
<a href="#const_end"><span class=identifier>const_end</span></a><span class=special>(</span><span class=keyword> const </span><span class=identifier>T</span><span class=special>& </span><span class=identifier>r </span><span class=special>);
|
|
</span>
|
|
<span class=keyword>template</span><span class=special>< </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>></span>
|
|
<span class=keyword>typename </span><span class=identifier>range_reverse_iterator</span><span class=special><</span><span class=keyword>const </span><span class=identifier>T</span><span class=special>>::</span><span class=identifier>type </span>
|
|
<a href="#const_rbegin"><span class=identifier>const_rbegin</span></a><span class=special>(</span><span class=keyword> const </span><span class=identifier>T</span><span class=special>& </span><span class=identifier>r </span><span class=special>);
|
|
</span>
|
|
<span class=keyword>template</span><span class=special>< </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>></span>
|
|
<span class=keyword>typename </span><span class=identifier>range_reverse_iterator</span><span class=special><</span><span class=keyword>const </span><span class=identifier>T</span><span class=special>>::</span><span class=identifier>type </span>
|
|
<a href="#const_rend"><span class=identifier>const_rend</span></a><span class=special>( </span><span class=keyword>const </span><span class=identifier>T</span><span class=special>& </span><span class=identifier>r </span><span class=special>);</span>
|
|
|
|
<span class=comment>//
|
|
// String utilities
|
|
//</span>
|
|
|
|
<span class=keyword>template</span><span class=special><</span> <span class=keyword>class</span> <span class=identifier>T</span> <span class=special>></span>
|
|
<span class=identifier>iterator_range</span><span class=special><...</span><span class=identifier>see</span> <span class=identifier>below</span><span class=special>...></span>
|
|
<span class=identifier><a href="#as_literal">as_literal</a></span><span class=special>(</span> <span class=identifier>T</span><span class=special>&</span> <span class=identifier>r</span> <span class=special>);</span>
|
|
|
|
<span class=keyword>template</span><span class=special><</span> <span class=keyword>class</span> <span class=identifier>T</span> <span class=special>></span>
|
|
<span class=identifier>iterator_range</span><span class=special><...</span><span class=identifier>see</span> <span class=identifier>below</span><span class=special>...></span>
|
|
<span class=identifier><a href="#as_array">as_literal</a></span><span class=special>(</span> <span class=keyword>const</span> <span class=identifier>T</span><span class=special>&</span> <span class=identifier>r</span> <span class=special>);</span>
|
|
|
|
<span class=keyword>template</span><span class=special><</span> <span class=keyword>class</span> <span class=identifier>T</span> <span class=special>></span>
|
|
<span class=identifier>iterator_range</span><span class=special><</span> <span class=keyword>typename</span> <span class=identifier>range_iterator</span><span class=special><</span><span class=identifier>T</span><span class=special>>::</span><span class=identifier>type</span> <span class=special>></span>
|
|
<span class=identifier><a href="#as_array">as_array</a></span><span class=special>(</span> <span class=identifier>T</span><span class=special>&</span> <span class=identifier>r</span> <span class=special>);</span>
|
|
|
|
<span class=keyword>template</span><span class=special><</span> <span class=keyword>class</span> <span class=identifier>T</span> <span class=special>></span>
|
|
<span class=identifier>iterator_range</span><span class=special><</span> <span class=keyword>typename</span> <span class=identifier>range_iterator</span><span class=special><</span><span class=keyword>const</span> <span class=identifier>T</span><span class=special>>::</span><span class=identifier>type</span> <span class=special>></span>
|
|
<span class=identifier><a href="#as_literal">as_array</a></span><span class=special>(</span> <span class=keyword>const</span> <span class=identifier>T</span><span class=special>&</span> <span class=identifier>r</span> <span class=special>);</span>
|
|
|
|
<span class=special>} </span><span class=comment>// namespace 'boost'
|
|
</span>
|
|
</pre>
|
|
<P></P>
|
|
<a name="Semantics"></a>
|
|
<h3>Semantics</h3>
|
|
<h4>notation</h4>
|
|
<p>
|
|
<table cellpadding="5" border="1">
|
|
<tr>
|
|
<th>
|
|
Type
|
|
<th>
|
|
Object
|
|
<th>
|
|
Describes
|
|
</tr>
|
|
<tr>
|
|
<td><code>X</code>
|
|
<td><code>x</code>
|
|
<td>any type</td>
|
|
<tr>
|
|
<td><code>T</code>
|
|
</td>
|
|
<td><code>t</code>
|
|
<td>denotes behavior of the primary templates</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>P</code>
|
|
<td><code>p</code>
|
|
<td>denotes <code>std::pair<iterator,iterator></code></td>
|
|
<tr>
|
|
<td><code>A[sz]</code>
|
|
<td><code>a</code>
|
|
<td>denotes an array of type <code>A</code> of size <code>sz</code>
|
|
</tr>
|
|
<tr>
|
|
<td><code>Char*</code>
|
|
<td><code>s</code>
|
|
<td>denotes either <code>char*</code> or <code>wchar_t*</code></td>
|
|
</tr>
|
|
</table>
|
|
</p>
|
|
<p>
|
|
Please notice in tables below that when four lines appear in a cell, the first
|
|
line will describe the primary template, the second line pairs of iterators,
|
|
the third line arrays and the last line null-terminated strings.
|
|
</p>
|
|
<h4>Metafunctions</h4>
|
|
<p>
|
|
<table border="1" cellpadding="5">
|
|
<tr>
|
|
<th>
|
|
Expression</th>
|
|
<th>
|
|
Return type</th>
|
|
<th>
|
|
Complexity</th>
|
|
</tr>
|
|
|
|
<tr >
|
|
<td><a name="range_iterator"></a><code>range_iterator<X>::type</code></td>
|
|
<td><code>T::iterator</code><br>
|
|
<code>P::first_type</code><br>
|
|
<code>A*</code><br>
|
|
|
|
<td>compile time</td>
|
|
</tr>
|
|
<tr>
|
|
|
|
<td><a name="range_const_iterator"></a><code>range_iterator<const X>::type</code></td>
|
|
<td><code>T::const_iterator</code><br>
|
|
<code>P::first_type</code><br>
|
|
<code>const A*</code><br>
|
|
|
|
<td>compile time</td>
|
|
</tr>
|
|
<tr>
|
|
|
|
<td><a name="range_value"></a><code>range_value<X>::type</code></td>
|
|
<td><code>boost::iterator_value<range_iterator<X>::type>::type</code>
|
|
</td>
|
|
<td>compile time</td>
|
|
</tr>
|
|
<tr>
|
|
|
|
<td><a name="range_reference"></a><code>range_reference<X>::type</code></td>
|
|
<td><code>boost::iterator_reference<range_iterator<X>::type>::type</code>
|
|
</td>
|
|
<td>compile time</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<td><a name="range_pointer"></a><code>range_pointer<X>::type</code></td>
|
|
<td><code>boost::iterator_pointer<range_iterator<X>::type>::type</code>
|
|
</td>
|
|
<td>compile time</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<td><a name="range_category"></a><code>range_category<X>::type</code></td>
|
|
<td><code>boost::iterator_category<range_iterator<X>::type>::type</code>
|
|
</td>
|
|
<td>compile time</td>
|
|
</tr>
|
|
<tr>
|
|
|
|
<td><a name="range_difference"></a><code>range_difference<X>::type</code></td>
|
|
<td>
|
|
<code>boost::iterator_difference<range_iterator<X>::type>::type</code></td>
|
|
|
|
<td>compile time</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<td><a name="range_reverse_iterator"></a><code>range_reverse_iterator<X>::type</code></td>
|
|
<td><code>boost::reverse_iterator<range_iterator<X>::type></code><br>
|
|
<td>compile time</td>
|
|
</tr>
|
|
<tr>
|
|
|
|
<td><a name="range_const_reverse_iterator"></a><code>range_reverse_iterator<const X>::type</code></td>
|
|
<td><code>boost::reverse_iterator<range_iterator<const X>::type></code>
|
|
<br>
|
|
<td>compile time</td>
|
|
</tr>
|
|
</table>
|
|
</p>
|
|
<h4>Functions</h4>
|
|
<p>
|
|
<table border="1" cellpadding="5">
|
|
<tr>
|
|
<th>
|
|
Expression</th>
|
|
<th>
|
|
Return type</th>
|
|
<th>
|
|
Returns</th>
|
|
<th>
|
|
Complexity</th>
|
|
</tr>
|
|
<tr>
|
|
|
|
<td><a name="begin"></a><code>begin(x)</code></td>
|
|
<td><code>range_iterator<X>::type</code></td>
|
|
<td>
|
|
<code>p.first</code> if <code>p</code> is of type <code>std::pair<T><code><br>
|
|
<code>a</code> if <code>a</code> is an array <br>
|
|
<code>range_begin(x)</code> if that expression would invoke a function found by ADL <br>
|
|
<code>t.begin()</code> otherwise
|
|
|
|
<td>constant time</td>
|
|
</tr>
|
|
<tr>
|
|
|
|
<td><a name="end"></a><code>end(x)</code></td>
|
|
<td><code>range_iterator<X>::type</code></td>
|
|
<td>
|
|
<code>p.second</code> if <code>p</code> is of type <code>std::pair<T><code><br>
|
|
<code>a + sz</code> if <code>a</code> is an array of size <code>sz</code>
|
|
|
|
<br>
|
|
<code>range_end(x)</code> if that expression would invoke a function found by ADL <br>
|
|
<code>t.end()</code> otherwise
|
|
|
|
<td>
|
|
constant time </td>
|
|
</tr>
|
|
<tr>
|
|
|
|
<td><a name="empty"></a><code>empty(x)</code></td>
|
|
<td><code>bool</code></td>
|
|
<td><code>boost::begin(x) == boost::end(x)</code><br>
|
|
<td> constant time <br>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
|
|
<td><a name="distance"></a><code>distance(x)</code></td>
|
|
<td><code>range_difference<X>::type</code></td>
|
|
<td>
|
|
<code>
|
|
std::distance(boost::begin(x),boost::end(x))
|
|
</code>
|
|
</td>
|
|
<td>-</td>
|
|
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<td><a name="size"></a><code>size(x)</code></td>
|
|
<td><code>range_difference<X>::type</code></td>
|
|
<td><code> boost::end(x) - boost::begin(x)</code>
|
|
|
|
<td> constant time </td>
|
|
</tr>
|
|
<tr>
|
|
|
|
<td><a name="rbegin"></a><code>rbegin(x)</code></td>
|
|
<td><code>range_reverse_iterator<X>::type</code></td>
|
|
<td><code>range_reverse_iterator<X>::type( boost::end(x) )</code>
|
|
<br>
|
|
<td>constant time
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
|
|
<td> <a name="rend"></a><code>rend(x)</code></td>
|
|
<td><code>range_reverse_iterator<X>::type</code></td>
|
|
<td><code>range_reverse_iterator<X>::type( boost::begin(x) )</code>
|
|
<td>constant time</td>
|
|
</tr>
|
|
<tr>
|
|
|
|
<td><a name="const_begin"></a><code>const_begin(x)</code></td>
|
|
<td><code>range_iterator<const X>::type</code></td>
|
|
<td><code>range_iterator<const X>::type( boost::begin(x) )</code>
|
|
<br>
|
|
<td>constant time
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
|
|
<td><a name="const_end"></a><code>const_end(x)</code></td>
|
|
<td><code>range_iterator<const X>::type</code></td>
|
|
<td><code>range_iterator<const X>::type( boost::end(x) )</code>
|
|
<td>constant time</td>
|
|
</tr>
|
|
<tr>
|
|
|
|
<td><a name="const_rbegin"></a><code>const_rbegin(x)</code></td>
|
|
<td><code>range_reverse_iterator<const X>::type</code></td>
|
|
<td><code>range_reverse_iterator<const X>::type( boost::rbegin(x) )</code>
|
|
<br>
|
|
<td>constant time
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
|
|
<td><a name="const_rend"></a><code>const_rend(x)</code></td>
|
|
<td><code>range_reverse_iterator<const X>::type</code></td>
|
|
<td><code>range_reverse_iterator<const X>::type( boost::rend(x) )</code>
|
|
|
|
<td>constant time</td>
|
|
</tr>
|
|
<tr>
|
|
|
|
<td><a name="as_literal"></a><code>as_literal(x)</code></td>
|
|
<td><code>iterator_range<U></code> where <code>U</code> is
|
|
<code>Char*</code> if <code>x</code> is a pointer to a
|
|
string and <code>U</code> is
|
|
<code>range_iterator<X>::type</code> otherwise
|
|
</td>
|
|
<td>
|
|
|
|
<!-- <code>[a,a+sz-1)</code> if <code>a</code> is an array
|
|
of size <code>sz</code><br>-->
|
|
<code>[s,s + std::char_traits<X>::length(s))</code> if <code>s</code> is a <code>Char*</code> or an array of <code>Char</code>
|
|
<br>
|
|
<code>[boost::begin(x),boost::end(x))</code> otherwise
|
|
|
|
|
|
|
|
</td>
|
|
<td>linear time for pointers to a string or arrays of
|
|
<code>Char</code>, constant time otherwise</td>
|
|
</tr>
|
|
<tr>
|
|
|
|
<td><a name="as_array"></a><code>as_array(x)</code></td>
|
|
<td><code>iterator_range<X></code> </td>
|
|
<td>
|
|
<code>[boost::begin(x),boost::end(x))</code>
|
|
|
|
|
|
|
|
|
|
</td>
|
|
<td>constant time otherwise</td>
|
|
</tr>
|
|
|
|
</table>
|
|
</p>
|
|
<p>
|
|
The special <code>const_</code>-named functions are useful when you
|
|
want to document clearly that your code is read-only.
|
|
</p>
|
|
<p>
|
|
<code>as_literal()</code> can be used <i>internally</i> in string
|
|
algorithm librararies such that arrays of characters are
|
|
handled correctly.
|
|
</p>
|
|
<p>
|
|
<code>as_array()</code> can be used with string algorithm libraries to make it clear that arrays of characters are handled like an array and not like a string.
|
|
</p>
|
|
<p>Notice that the above functions should always be called with
|
|
qualification (<code>boost::</code>) to prevent <i>unintended</i>
|
|
Argument Dependent Lookup (ADL).
|
|
</p>
|
|
<hr>
|
|
<a name="minimal_interface"></a>
|
|
<h3>Extending the library</h3>
|
|
<ul>
|
|
<li><a href="#method1">Method 1: provide member functions and nested types</a></li>
|
|
|
|
<li><a href="#method2">Method 2: provide free-standing functions and specialize metafunctions</a></li>
|
|
</ul>
|
|
|
|
<!--<b>Warning:</b><i> If possible, then prefer method 1 if you want to be absolutely sure your code is forward compatible.
|
|
</i>-->
|
|
|
|
<a name="method1"></a>
|
|
<h4>Method 1: provide member functions and nested types</h4>
|
|
|
|
<p>
|
|
This procedure assumes that you have control over the types that should be made
|
|
conformant to a Range concept. If not, see <a href="#method2">method 2</a>.
|
|
</p>
|
|
|
|
<p>
|
|
The primary templates in this library are implemented such that standard
|
|
containers will work automatically and so will <code>boost::<a href="../../array/index.html">array</a></code>.
|
|
Below is given an overview of which member functions and member types a class
|
|
must specify to be useable as a certain Range concept.
|
|
</p>
|
|
<p>
|
|
<table cellpadding="5" border="1">
|
|
<tr>
|
|
<th>
|
|
Member function</th>
|
|
<th>
|
|
Related concept</th>
|
|
<tr>
|
|
<td><code>begin()</code></td>
|
|
<td><a href="range.html#single_pass_range">Single Pass Range</a></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>end()</code>
|
|
</td>
|
|
<td><a href="range.html#single_pass_range">Single Pass Range</a></td>
|
|
</tr>
|
|
</table>
|
|
</p>
|
|
<p>
|
|
Notice that <code>rbegin()</code> and <code>rend()</code> member functions are
|
|
not needed even though the container can support bidirectional iteration.
|
|
</p>
|
|
<p>
|
|
The required member types are:
|
|
</p>
|
|
<p>
|
|
<table cellpadding="5" border="1">
|
|
<tr>
|
|
<th>
|
|
Member type</th>
|
|
<th>
|
|
Related concept</th>
|
|
</tr>
|
|
<tr>
|
|
<td><code>iterator</code></td>
|
|
<td><a href="range.html#single_pass_range">Single Pass Range</a></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>const_iterator</code></td>
|
|
<td><a href="range.html#single_pass_range">Single Pass Range</a></td>
|
|
</tr>
|
|
</table>
|
|
</p>
|
|
<p>
|
|
Again one should notice that member types <code>reverse_iterator</code> and <code>const_reverse_iterator</code>
|
|
are not needed.
|
|
</p>
|
|
<a name="method2"></a>
|
|
<h4>Method 2: provide free-standing functions and specialize metafunctions</h4>
|
|
|
|
<p>
|
|
This procedure assumes that you cannot (or do not wish to) change the types that should be made
|
|
conformant to a Range concept. If this is not true, see <a href="#method1">method 1</a>.
|
|
</p>
|
|
|
|
<p>
|
|
The primary templates in this library are implemented such that
|
|
certain functions are found via argument-dependent-lookup (ADL).
|
|
Below is given an overview of which free-standing functions a class
|
|
must specify to be useable as a certain Range concept.
|
|
Let <code>x</code> be a variable (<code>const</code> or mutable)
|
|
of the class in question.
|
|
</p>
|
|
<p>
|
|
<table cellpadding="5" border="1" ID="Table1">
|
|
<tr>
|
|
<th>
|
|
Function</th>
|
|
<th>
|
|
Related concept</th>
|
|
<tr>
|
|
<td><code>range_begin(x)</code></td>
|
|
<td><a href="range.html#single_pass_range">Single Pass Range</a></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>range_end(x)</code>
|
|
</td>
|
|
<td><a href="range.html#single_pass_range">Single Pass Range</a></td>
|
|
</tr>
|
|
|
|
</table>
|
|
</p>
|
|
<p><code>range_begin()</code> and <code>range_end()</code> must be
|
|
overloaded for both <code>const</code> and mutable reference arguments.
|
|
</p>
|
|
|
|
<p>
|
|
You must also specialize two metafunctions for your type <code>X</code>:
|
|
</p>
|
|
<p>
|
|
<table cellpadding="5" border="1" ID="Table2">
|
|
<tr>
|
|
<th>
|
|
Metafunction</th>
|
|
<th>
|
|
Related concept</th>
|
|
<tr>
|
|
<td><code>boost::range_mutable_iterator</code></td>
|
|
<td><a href="range.html#single_pass_range">Single Pass Range</a></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>boost::range_const_iterator</code></td>
|
|
<td><a href="range.html#single_pass_range">Single Pass Range</a></td>
|
|
</tr>
|
|
|
|
</table>
|
|
</p>
|
|
<p>
|
|
A complete example is given here:
|
|
</p>
|
|
<blockquote>
|
|
<pre>
|
|
<span class=preprocessor>#include</span> <span class=special><</span><span class=identifier>boost</span><span class=special>/</span><span class=identifier>range</span><span class=special>.</span><span class=identifier>hpp</span><span class=special>></span>
|
|
<span class=preprocessor>#include</span> <span class=special><</span><span class=identifier>iterator</span><span class=special>></span> <span class=comment>// for std::iterator_traits, std::distance()</span>
|
|
|
|
<span class=keyword>namespace</span> <span class=identifier>Foo</span>
|
|
<span class=special>{</span>
|
|
<span class=comment>//
|
|
// Our sample UDT. A 'Pair'
|
|
// will work as a range when the stored
|
|
// elements are iterators.
|
|
//</span>
|
|
<span class=keyword>template</span><span class=special><</span> <span class=keyword>class</span> <span class=identifier>T</span> <span class=special>></span>
|
|
<span class=keyword>struct</span> <span class=identifier>Pair</span>
|
|
<span class=special>{</span>
|
|
<span class=identifier>T</span> <span class=identifier>first</span><span class=special>,</span> <span class=identifier>last</span><span class=special>;</span>
|
|
<span class=special>};</span>
|
|
|
|
<span class=special>}</span> <span class=comment>// namespace 'Foo'</span>
|
|
|
|
<span class=keyword>namespace</span> <span class=identifier>boost</span>
|
|
<span class=special>{</span>
|
|
<span class=comment>//
|
|
// Specialize metafunctions. We must include the range.hpp header.
|
|
// We must open the 'boost' namespace.
|
|
//</span>
|
|
|
|
<span class=keyword>template</span><span class=special><</span> <span class=keyword>class</span> <span class=identifier>T</span> <span class=special>></span>
|
|
<span class=keyword>struct</span> <span class=identifier>range_mutable_iterator</span><span class=special><</span> <span class=identifier>Foo</span><span class=special>::</span><span class=identifier>Pair</span><span class=special><</span><span class=identifier>T</span><span class=special>></span> <span class=special>></span>
|
|
<span class=special>{</span>
|
|
<span class=keyword>typedef</span> <span class=identifier>T</span> <span class=identifier>type</span><span class=special>;</span>
|
|
<span class=special>};</span>
|
|
|
|
<span class=keyword>template</span><span class=special><</span> <span class=keyword>class</span> <span class=identifier>T</span> <span class=special>></span>
|
|
<span class=keyword>struct</span> <span class=identifier>range_const_iterator</span><span class=special><</span> <span class=identifier>Foo</span><span class=special>::</span><span class=identifier>Pair</span><span class=special><</span><span class=identifier>T</span><span class=special>></span> <span class=special>></span>
|
|
<span class=special>{</span>
|
|
<span class=comment>//
|
|
// Remark: this is defined similar to 'range_mutable_iterator'
|
|
// because the 'Pair' type does not distinguish
|
|
// between an iterator and a const_iterator.
|
|
//</span>
|
|
<span class=keyword>typedef</span> <span class=identifier>T</span> <span class=identifier>type</span><span class=special>;</span>
|
|
<span class=special>};</span>
|
|
|
|
<span class=special>}</span> <span class=comment>// namespace 'boost'</span>
|
|
|
|
<span class=keyword>namespace</span> <span class=identifier>Foo</span>
|
|
<span class=special>{</span>
|
|
<span class=comment>//
|
|
// The required functions. These should be defined in
|
|
// the same namespace as 'Pair', in this case
|
|
// in namespace 'Foo'.
|
|
//</span>
|
|
|
|
<span class=keyword>template</span><span class=special><</span> <span class=keyword>class</span> <span class=identifier>T</span> <span class=special>></span>
|
|
<span class=keyword>inline</span> <span class=identifier>T</span> <span class=identifier>range_begin</span><span class=special>(</span> <span class=identifier>Pair</span><span class=special><</span><span class=identifier>T</span><span class=special>>&</span> <span class=identifier>x</span> <span class=special>)</span>
|
|
<span class=special>{</span>
|
|
<span class=keyword>return</span> <span class=identifier>x</span><span class=special>.</span><span class=identifier>first</span><span class=special>;</span>
|
|
<span class=special>}</span>
|
|
|
|
<span class=keyword>template</span><span class=special><</span> <span class=keyword>class</span> <span class=identifier>T</span> <span class=special>></span>
|
|
<span class=keyword>inline</span> <span class=identifier>T</span> <span class=identifier>range_begin</span><span class=special>(</span> <span class=keyword>const</span> <span class=identifier>Pair</span><span class=special><</span><span class=identifier>T</span><span class=special>>&</span> <span class=identifier>x</span> <span class=special>)</span>
|
|
<span class=special>{</span>
|
|
<span class=keyword>return</span> <span class=identifier>x</span><span class=special>.</span><span class=identifier>first</span><span class=special>;</span>
|
|
<span class=special>}</span>
|
|
|
|
<span class=keyword>template</span><span class=special><</span> <span class=keyword>class</span> <span class=identifier>T</span> <span class=special>></span>
|
|
<span class=keyword>inline</span> <span class=identifier>T</span> <span class=identifier>range_end</span><span class=special>(</span> <span class=identifier>Pair</span><span class=special><</span><span class=identifier>T</span><span class=special>>&</span> <span class=identifier>x</span> <span class=special>)</span>
|
|
<span class=special>{</span>
|
|
<span class=keyword>return</span> <span class=identifier>x</span><span class=special>.</span><span class=identifier>last</span><span class=special>;</span>
|
|
<span class=special>}</span>
|
|
|
|
<span class=keyword>template</span><span class=special><</span> <span class=keyword>class</span> <span class=identifier>T</span> <span class=special>></span>
|
|
<span class=keyword>inline</span> <span class=identifier>T</span> <span class=identifier>range_end</span><span class=special>(</span> <span class=keyword>const</span> <span class=identifier>Pair</span><span class=special><</span><span class=identifier>T</span><span class=special>>&</span> <span class=identifier>x</span> <span class=special>)</span>
|
|
<span class=special>{</span>
|
|
<span class=keyword>return</span> <span class=identifier>x</span><span class=special>.</span><span class=identifier>last</span><span class=special>;</span>
|
|
<span class=special>}</span>
|
|
|
|
<span class=special>}</span> <span class=comment>// namespace 'Foo'</span>
|
|
|
|
<span class=preprocessor>#include</span> <span class=special><</span><span class=identifier>vector</span><span class=special>></span>
|
|
|
|
<span class=keyword>int</span> <span class=identifier>main</span><span class=special>()</span>
|
|
<span class=special>{</span>
|
|
<span class=keyword>typedef</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>vector</span><span class=special><</span><span class=keyword>int</span><span class=special>>::</span><span class=identifier>iterator</span> <span class=identifier>iter</span><span class=special>;</span>
|
|
<span class=identifier>std</span><span class=special>::</span><span class=identifier>vector</span><span class=special><</span><span class=keyword>int</span><span class=special>></span> <span class=identifier>vec</span><span class=special>;</span>
|
|
<span class=identifier>Foo</span><span class=special>::</span><span class=identifier>Pair</span><span class=special><</span><span class=identifier>iter</span><span class=special>></span> <span class=identifier>pair</span> <span class=special>=</span> <span class=special>{</span> <span class=identifier>vec</span><span class=special>.</span><span class=identifier>begin</span><span class=special>(),</span> <span class=identifier>vec</span><span class=special>.</span><span class=identifier>end</span><span class=special>()</span> <span class=special>};</span>
|
|
<span class=keyword>const</span> <span class=identifier>Foo</span><span class=special>::</span><span class=identifier>Pair</span><span class=special><</span><span class=identifier>iter</span><span class=special>>&</span> <span class=identifier>cpair</span> <span class=special>=</span> <span class=identifier>pair</span><span class=special>;</span>
|
|
<span class=comment>//
|
|
// Notice that we call 'begin' etc with qualification.
|
|
//</span>
|
|
<span class=identifier>iter</span> <span class=identifier>i</span> <span class=special>=</span> <span class=identifier>boost</span><span class=special>::</span><span class=identifier>begin</span><span class=special>(</span> <span class=identifier>pair</span> <span class=special>);</span>
|
|
<span class=identifier>iter</span> <span class=identifier>e</span> <span class=special>=</span> <span class=identifier>boost</span><span class=special>::</span><span class=identifier>end</span><span class=special>(</span> <span class=identifier>pair</span> <span class=special>);</span>
|
|
<span class=identifier>i</span> <span class=special>=</span> <span class=identifier>boost</span><span class=special>::</span><span class=identifier>begin</span><span class=special>(</span> <span class=identifier>cpair</span> <span class=special>);</span>
|
|
<span class=identifier>e</span> <span class=special>=</span> <span class=identifier>boost</span><span class=special>::</span><span class=identifier>end</span><span class=special>(</span> <span class=identifier>cpair</span> <span class=special>);</span>
|
|
<span class=identifier>boost</span><span class=special>::</span><span class=identifier>range_difference</span><span class=special><</span> <span class=identifier>Foo</span><span class=special>::</span><span class=identifier>Pair</span><span class=special><</span><span class=identifier>iter</span><span class=special>></span> <span class=special>>::</span><span class=identifier>type</span> <span class=identifier>s</span> <span class=special>=</span> <span class=identifier>boost</span><span class=special>::</span><span class=identifier>size</span><span class=special>(</span> <span class=identifier>pair</span> <span class=special>);</span>
|
|
<span class=identifier>s</span> <span class=special>=</span> <span class=identifier>boost</span><span class=special>::</span><span class=identifier>size</span><span class=special>(</span> <span class=identifier>cpair</span> <span class=special>);</span>
|
|
<span class=identifier>boost</span><span class=special>::</span><span class=identifier>range_reverse_iterator</span><span class=special><</span> <span class=identifier>const Foo</span><span class=special>::</span><span class=identifier>Pair</span><span class=special><</span><span class=identifier>iter</span><span class=special>></span> <span class=special>>::</span><span class=identifier>type</span>
|
|
<span class=identifier>ri</span> <span class=special>=</span> <span class=identifier>boost</span><span class=special>::</span><span class=identifier>rbegin</span><span class=special>(</span> <span class=identifier>cpair</span> <span class=special>),</span>
|
|
<span class=identifier>re</span> <span class=special>=</span> <span class=identifier>boost</span><span class=special>::</span><span class=identifier>rend</span><span class=special>(</span> <span class=identifier>cpair</span> <span class=special>);</span>
|
|
<span class=special>}</span>
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<hr>
|
|
<p>
|
|
© <a name="Copyright" id="Copyright">Copyright</a> Thorsten Ottosen 2008.
|
|
</p>
|
|
|
|
<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>
|
|
<br>
|
|
<br>
|
|
<br>
|
|
<br>
|
|
<br>
|
|
<br>
|
|
<br>
|
|
<br>
|
|
<br>
|
|
<br>
|
|
<br>
|
|
<br>
|
|
</body>
|
|
</html>
|