2004-08-05 19:37:40 +00:00
|
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
|
|
|
<html>
|
|
|
|
|
<head>
|
|
|
|
|
<title>Boost.Range Range Implementation </title>
|
|
|
|
|
<meta http-equiv="Content-Type"content="text/html; charset=iso-8859-1">
|
|
|
|
|
</head>
|
|
|
|
|
|
|
|
|
|
<body>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<table >
|
|
|
|
|
<tr >
|
|
|
|
|
<td ><img src="cboost.gif" width="100%" border="0"></td>
|
|
|
|
|
<td ><h1 ><br>
|
|
|
|
|
Boost.Range </h1></td>
|
|
|
|
|
</tr>
|
|
|
|
|
</table>
|
|
|
|
|
|
|
|
|
|
<h2>Range and ReversibleRange Implementation</h2>
|
|
|
|
|
|
|
|
|
|
<ul >
|
|
|
|
|
<li>
|
|
|
|
|
<a href="#overview">Overview</a>
|
|
|
|
|
<li >
|
|
|
|
|
<a href="#Synopsis" >Synopsis</a>
|
|
|
|
|
</li>
|
|
|
|
|
<li >
|
|
|
|
|
<a href="#Semantics" >Semantics</a>
|
|
|
|
|
</li>
|
|
|
|
|
<li >
|
|
|
|
|
<a href="#Examples" >Examples</a>
|
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<hr size="1" >
|
|
|
|
|
|
|
|
|
|
<h3>Overview</h3>
|
|
|
|
|
<p>
|
|
|
|
|
Five types of objects are currently supported by the library:
|
|
|
|
|
<ul >
|
|
|
|
|
<li >
|
|
|
|
|
standard containers
|
|
|
|
|
</li>
|
|
|
|
|
<li >
|
|
|
|
|
built-in arrays
|
|
|
|
|
</li>
|
|
|
|
|
<li >
|
|
|
|
|
null terminated strings (this includes <code >char[]</code>,<code >wchar_t[]</code>,
|
|
|
|
|
<code >char*</code>, and <code >wchar_t*</code>)
|
|
|
|
|
</li>
|
|
|
|
|
<li >
|
|
|
|
|
<code >std::pair<iterator,iterator></code>
|
|
|
|
|
</li>
|
|
|
|
|
<li >
|
|
|
|
|
iterators which when default constructed denotes the end of the range
|
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
|
|
|
|
It is worth noticing that some functionality requires partial template
|
|
|
|
|
specialization, in particular, full array support does (remark: this is a very
|
|
|
|
|
small problem since one would use <code>boost::array<></code> anyway). Also note
|
|
|
|
|
that arrays and pointers of <code >char</code> or <code >whar_t</code> are
|
|
|
|
|
treated special because of their use in string algorithms.
|
|
|
|
|
</p>
|
|
|
|
|
<h3 >ExternalCollectionConcept</h3><a name="ExternalCollectionConcept" ></a>
|
|
|
|
|
<p >
|
|
|
|
|
The concept is defined by the type-generators and the functions below. Even
|
|
|
|
|
though these functions are defined in namespace <code>boost</code>, there is no
|
|
|
|
|
such general requirement, that is, if one wants to extend the list of supported
|
|
|
|
|
types, it can be done in any namespace.
|
|
|
|
|
</p>
|
|
|
|
|
<h3 >Synopsis</h3><a name="Synopsis" ></a>
|
|
|
|
|
<p >
|
|
|
|
|
<pre>
|
|
|
|
|
namespace boost
|
2004-06-29 02:58:13 +00:00
|
|
|
{
|
2004-08-05 19:37:40 +00:00
|
|
|
//
|
2004-06-29 02:58:13 +00:00
|
|
|
// type generators
|
2004-08-05 19:37:40 +00:00
|
|
|
//
|
2004-06-29 02:58:13 +00:00
|
|
|
|
2004-08-05 19:37:40 +00:00
|
|
|
template< typename EC >
|
2004-06-29 02:58:13 +00:00
|
|
|
struct <a href="#value_type_of" >value_type_of</a>
|
|
|
|
|
{
|
2004-08-05 19:37:40 +00:00
|
|
|
typedef ... type; // type of stored objects
|
2004-06-29 02:58:13 +00:00
|
|
|
};
|
|
|
|
|
|
2004-08-05 19:37:40 +00:00
|
|
|
template< typename EC >
|
|
|
|
|
struct <a href="#iterator_of" >iterator_of</a>
|
2004-06-29 02:58:13 +00:00
|
|
|
{
|
|
|
|
|
typedef ... type; // iterator over stored objects
|
|
|
|
|
};
|
|
|
|
|
|
2004-08-05 19:37:40 +00:00
|
|
|
template< typename EC >
|
|
|
|
|
struct <a href="#const_iterator_of" >const_iterator_of</a>
|
2004-06-29 02:58:13 +00:00
|
|
|
{
|
2004-08-05 19:37:40 +00:00
|
|
|
typedef ... type; // iterator over immutable stored objects
|
2004-06-29 02:58:13 +00:00
|
|
|
};
|
|
|
|
|
|
2004-08-05 19:37:40 +00:00
|
|
|
template< typename EC >
|
2004-06-29 02:58:13 +00:00
|
|
|
struct <a href="#difference_type_of" >difference_type_of</a>
|
|
|
|
|
{
|
2004-08-05 19:37:40 +00:00
|
|
|
typedef ... type;
|
2004-06-29 02:58:13 +00:00
|
|
|
BOOST_STATIC_ASSERT( boost::is_signed< type >::value );
|
|
|
|
|
//
|
2004-08-05 19:37:40 +00:00
|
|
|
// remark: if std::iterator_traits<> works for the type, this assertion must
|
|
|
|
|
hold
|
2004-06-29 02:58:13 +00:00
|
|
|
//
|
2004-08-05 19:37:40 +00:00
|
|
|
BOOST_STATIC_ASSERT( boost::is_same< type, std::iterator_traits< typename
|
|
|
|
|
<a href="#iterator_of" >iterator_of</a>< EC >::type >::difference_type>::value );
|
2004-06-29 02:58:13 +00:00
|
|
|
};
|
|
|
|
|
|
2004-08-05 19:37:40 +00:00
|
|
|
template< typename EC >
|
2004-06-29 02:58:13 +00:00
|
|
|
struct <a href="#size_type_of" >size_type_of</a>
|
|
|
|
|
{
|
|
|
|
|
typedef ... type;
|
|
|
|
|
BOOST_STATIC_ASSERT( boost::is_unsigned< type >::value );
|
2004-08-05 19:37:40 +00:00
|
|
|
BOOST_STATIC_ASSERT( sizeof( type ) >= sizeof( <a href="#difference_type_of" >
|
|
|
|
|
difference_type_of</a>< EC >::type ) );
|
2004-06-29 02:58:13 +00:00
|
|
|
};
|
|
|
|
|
|
2004-08-05 19:37:40 +00:00
|
|
|
template< typename EC >
|
|
|
|
|
struct <a href="#result_iterator_of" >result_iterator_of</a>
|
2004-06-29 02:58:13 +00:00
|
|
|
{
|
2004-08-05 19:37:40 +00:00
|
|
|
typedef ... type;
|
|
|
|
|
// <a href="#iterator_of" >iterator_of</a>< EC >::type if EC is non-const, <a href="#const_iterator_of" >
|
|
|
|
|
const_iterator_of</a>< EC >::type otherwise
|
2004-06-29 02:58:13 +00:00
|
|
|
};
|
|
|
|
|
|
|
|
|
|
//
|
|
|
|
|
// funtions
|
|
|
|
|
//
|
|
|
|
|
|
|
|
|
|
template< typename EC >
|
|
|
|
|
inline typename iterator_of<EC>::type
|
2004-08-05 19:37:40 +00:00
|
|
|
<a href="#begin" >begin</a>( EC& c );
|
2004-06-29 02:58:13 +00:00
|
|
|
|
|
|
|
|
template< typename EC >
|
|
|
|
|
inline typename const_iterator_of< EC >::type
|
2004-08-05 19:37:40 +00:00
|
|
|
<a href="#begin" >begin</a>( const EC& c );
|
2004-06-29 02:58:13 +00:00
|
|
|
|
|
|
|
|
template< typename EC >
|
|
|
|
|
inline typename iterator_of< EC >::type
|
2004-08-05 19:37:40 +00:00
|
|
|
<a href="#end" >end</a>( EC& c );
|
2004-06-29 02:58:13 +00:00
|
|
|
|
|
|
|
|
template< typename EC >
|
|
|
|
|
inline typename const_iterator_of< EC >::type
|
|
|
|
|
<a href="#end" >end</a>( const EC& c );
|
|
|
|
|
|
|
|
|
|
template< typename EC >
|
|
|
|
|
inline bool
|
2004-08-05 19:37:40 +00:00
|
|
|
<a href="#empty" >empty</a>( const EC& c );
|
2004-06-29 02:58:13 +00:00
|
|
|
|
|
|
|
|
template< typename EC >
|
|
|
|
|
inline typename size_type_of< EC >::type
|
|
|
|
|
<a href="#size" >size</a>( const EC& c );
|
|
|
|
|
|
2004-08-05 19:37:40 +00:00
|
|
|
} // namespace 'boost' </pre>
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<h3 >Semantics</h3><a name="Semantics" ></a>
|
|
|
|
|
<p >
|
|
|
|
|
In the table <code >C</code> is a type that conforms to the
|
|
|
|
|
ExternalCollectionConcept and <code >c</code> is an object of that type.<code >
|
|
|
|
|
SC</code>
|
|
|
|
|
will denote a standard container, <code >T[sz]</code> will denote an array of
|
|
|
|
|
type <code >T</code> of size <code >sz</code>, <code >P</code> will denote <code >
|
|
|
|
|
std::pair<></code>,
|
|
|
|
|
<code >I</code> means an iterator which default construction denotes the end of
|
|
|
|
|
the range and <code >sc,t,p,i</code> are objects of these types, respectively.
|
|
|
|
|
Special cases for <code >char*</code> and <code >wchar_t*</code> are described
|
|
|
|
|
explicitly.
|
|
|
|
|
</p>
|
|
|
|
|
<table border="1" cellpadding="5" >
|
|
|
|
|
<tr >
|
|
|
|
|
<th >Expression</th>
|
|
|
|
|
<th >Return type</th>
|
|
|
|
|
<th >Complexity</th>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr >
|
|
|
|
|
<a name="value_type_of" ></a>
|
|
|
|
|
<td ><code >value_type_of<C>::type</code></td>
|
|
|
|
|
<td ><code >SC::value_type</code><br>
|
|
|
|
|
<code >T</code><br>
|
|
|
|
|
<code >std::iterator_traits<P::first_type>::value_type</code><br>
|
|
|
|
|
<td >compile time</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr >
|
|
|
|
|
<a name="iterator_of" ></a>
|
|
|
|
|
<td ><code >iterator_of<C>::type</code></td>
|
|
|
|
|
<td ><code >SC::iterator</code><br>
|
|
|
|
|
<code >T*</code><br>
|
|
|
|
|
<code >P::first_type</code><br>
|
|
|
|
|
<td >compile time</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr >
|
|
|
|
|
<a name="const_iterator_of" ></a>
|
|
|
|
|
<td ><code >const_iterator_of<C>::type</code></td>
|
|
|
|
|
<td ><code >SC::const_iterator</code><br>
|
|
|
|
|
<code >const T*</code><br>
|
|
|
|
|
<code >P::first_type</code><br>
|
|
|
|
|
<td >compile time</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr >
|
|
|
|
|
<a name="difference_type_of" ></a>
|
|
|
|
|
<td ><code >difference_type_of<C>::type</code></td>
|
|
|
|
|
<td ><code >SC::difference_type</code><br>
|
|
|
|
|
<code >std::ptrdiff_t</code><br>
|
|
|
|
|
<code >std::iterator_traits<P::first_type>:: difference_type</code><br>
|
|
|
|
|
<td >compile time</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr >
|
|
|
|
|
<a name="size_type_of" ></a>
|
|
|
|
|
<td ><code >size_type_of<C>::type</code></td>
|
|
|
|
|
<td ><code >SC::size_type</code><br>
|
|
|
|
|
<code >std::size_t</code><br>
|
|
|
|
|
<code >std::size_t</code><br>
|
|
|
|
|
<td >compile time</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr >
|
|
|
|
|
<a name="result_iterator_of" ></a>
|
|
|
|
|
<td ><code >result_iterator_of<C>::type</code></td>
|
|
|
|
|
<td ><code >const_iterator_of< C>::type</code> if <code >C</code> is <code >
|
|
|
|
|
const</code>
|
|
|
|
|
<br>
|
|
|
|
|
<code >iterator_of<C>::type</code> otherwise </td>
|
|
|
|
|
<td >compile time</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr >
|
|
|
|
|
<a name="reverse_iterator_of" ></a>
|
|
|
|
|
<td ><code >reverse_iterator_of<C>::type</code></td>
|
|
|
|
|
<td ><code >boost::reverse_iterator< typename iterator_of<T>::type
|
|
|
|
|
></code><br> <td >compile time</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr >
|
|
|
|
|
<a name="const_reverse_iterator_of" ></a>
|
|
|
|
|
<td ><code >const_reverse_iterator_of<C>::type</code></td>
|
|
|
|
|
<td ><code >boost::reverse_iterator< typename const_iterator_of<T>::type ></code><br>
|
|
|
|
|
<td >compile time</td>
|
|
|
|
|
</tr> <tr >
|
|
|
|
|
<a name="reverse_result_iterator_of" ></a>
|
|
|
|
|
<td ><code >reverse_result_iterator_of<C>::type</code></td>
|
|
|
|
|
<td ><code >boost::reverse_iterator< typename result_iterator_of<T>::
|
|
|
|
|
type ></code>
|
|
|
|
|
<td >compile time</td>
|
|
|
|
|
</tr>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</table>
|
|
|
|
|
<br>
|
|
|
|
|
<table border="1" cellpadding="5" >
|
|
|
|
|
<tr >
|
|
|
|
|
<th >Expression</th>
|
|
|
|
|
<th >Return type</th>
|
|
|
|
|
<th >Returns</th>
|
|
|
|
|
<th >Complexity</th>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr >
|
|
|
|
|
<a name="begin" ></a>
|
|
|
|
|
<td ><code >begin( c )</code></td>
|
|
|
|
|
<td ><code >result_iterator_of<C>::type</code></td>
|
|
|
|
|
<td ><code >sc.begin()</code><br>
|
|
|
|
|
<code >t</code><br>
|
|
|
|
|
<code >p.first</code><br>
|
|
|
|
|
<td >constant time</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr >
|
|
|
|
|
<a name="end" ></a>
|
|
|
|
|
<td ><code >end( c )</code></td>
|
|
|
|
|
<td ><code >result_iterator_of<C>::type</code></td>
|
|
|
|
|
<td ><code >sc.end()</code><br>
|
|
|
|
|
<code >t + std::char_traits<C>::length( t )</code> if <code >C</code> is <code >
|
|
|
|
|
char*</code>
|
|
|
|
|
or <code >wchar_t*</code><br>
|
|
|
|
|
<code >t + sz - 1</code> if <code >C</code> is <code >char[sz]</code> or <code >
|
|
|
|
|
wchar_t[sz]</code>
|
|
|
|
|
<br>
|
|
|
|
|
<code >t + sz</code> otherwise <br>
|
|
|
|
|
<code >p.second</code><br>
|
|
|
|
|
<td >linear if <code >C</code> is <code >char*</code> or <code >wchar_t*</code>
|
|
|
|
|
<br>
|
|
|
|
|
constant time otherwise</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr >
|
|
|
|
|
<a name="empty" ></a>
|
|
|
|
|
<td ><code >empty( c )</code></td>
|
|
|
|
|
<td >Convertible to <code >bool</code></td>
|
|
|
|
|
<td ><code >sc.empty()</code><br>
|
|
|
|
|
<code >size( t ) == 0</code><br>
|
|
|
|
|
<code >p.first == p.second</code><br>
|
|
|
|
|
<td >linear if <code >C</code> is <code >char*</code> or <code >wchar_t*</code>
|
|
|
|
|
<br>
|
|
|
|
|
constant time otherwise<br>
|
|
|
|
|
</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr >
|
|
|
|
|
<a name="size" ></a>
|
|
|
|
|
<td ><code >size( c )</code></td>
|
|
|
|
|
<td ><code >size_type_of<C>::type</code></td>
|
|
|
|
|
<td ><code >sc.size()</code><br>
|
|
|
|
|
<code >end( t ) - begin( t )</code><br>
|
|
|
|
|
<code >distance( p. first, p.second )</code><br>
|
|
|
|
|
<td >linear if <code >C</code> is <code >char*</code> or <code >wchar_t*</code>
|
|
|
|
|
<br>
|
|
|
|
|
or if <code >std::distance()</code> is linear <br>
|
|
|
|
|
constant time otherwise</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr >
|
|
|
|
|
<a name="rbegin" ></a>
|
|
|
|
|
<td ><code >rbegin( c )</code></td>
|
|
|
|
|
<td ><code >reverse_result_iterator_of<C>::type</code></td>
|
|
|
|
|
<td ><code >reverse_result_iterator_of<C>::type( end( c ) )</code>
|
|
|
|
|
<br>
|
|
|
|
|
<td >same as <code>end()</code> </td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr >
|
|
|
|
|
<a name="rend" ></a>
|
|
|
|
|
<td ><code >rend( c )</code></td>
|
|
|
|
|
<td ><code >reverse_result_iterator_of<C>::type</code></td>
|
|
|
|
|
<td ><code >reverse_result_iterator_of<C>::type( begin( c ) )</code>
|
|
|
|
|
<td > same as <code>begin()</code></td>
|
|
|
|
|
</tr>
|
|
|
|
|
|
|
|
|
|
</table>
|
|
|
|
|
|
|
|
|
|
<p >
|
|
|
|
|
Please note that <code >char*</code>,<code >whar_t*</code>,<code >char[]</code>,
|
|
|
|
|
and <code >wchar_t[]</code> behaves differently from normal arrays only for <code >
|
|
|
|
|
size()</code>
|
|
|
|
|
and <code >end()</code>. Note that the null pointer is allowed as an argument
|
|
|
|
|
in these cases.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<hr size="1" ><h2 >Examples</h2><a name="Examples" ></a>
|
|
|
|
|
<p >
|
|
|
|
|
Some examples are given in the accompanying test files:
|
|
|
|
|
</p>
|
|
|
|
|
<ul >
|
|
|
|
|
<li >
|
|
|
|
|
<a href="../test/iterator.cpp" target="_self" ><code >iterator.cpp</code></a>
|
|
|
|
|
</li>
|
|
|
|
|
shows how to implement a container version of <code >std::copy()</code> that
|
|
|
|
|
works with <code >std::ifstream_iterator<>.</code>
|
|
|
|
|
<li >
|
|
|
|
|
<a href="../test/string.cpp" target="_self" ><code >string.cpp</code></a>
|
|
|
|
|
</li>
|
|
|
|
|
shows how to implement a container version of <code >std::find()</code> that
|
|
|
|
|
works with <code >char[],wchar_t[],char*,wchar_t*.</code>
|
|
|
|
|
<li >
|
|
|
|
|
<a href="../test/algorithm_example.cpp" target="_self" ><code >algorithm_example.cpp</code></a>
|
|
|
|
|
|
|
|
|
|
</li>
|
|
|
|
|
shows the replace example from the introduction.
|
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
<hr>
|
|
|
|
|
<p>
|
|
|
|
|
(C) Copyright Thorsten Ottosen 2003-2004
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<br>
|
|
|
|
|
<br>
|
|
|
|
|
<br>
|
|
|
|
|
<br>
|
|
|
|
|
<br>
|
|
|
|
|
<br>
|
|
|
|
|
<br>
|
|
|
|
|
<br>
|
|
|
|
|
<br>
|
|
|
|
|
<br>
|
|
|
|
|
<br>
|
|
|
|
|
<br>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</body>
|
|
|
|
|
</html>
|
