forked from boostorg/range
*** empty log message ***
[SVN r24315]
This commit is contained in:
Thorsten Jørgen Ottosen
@ -1,112 +1,128 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><head><title> Boost.Range External 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 External Range Implementation </h1></td></tr></table><ul ><li ><a href="#Introduction" >Introduction</a></li><li ><a href="#Reference" >Reference</a></li><ul ><li ><a href="#Synopsis" >Synopsis</a></li><li ><a href="#Library headers" >Library headers</a></li><li ><a href="#Semantics" >Semantics</a></li></ul><li ><a href="#Examples" >Examples</a></li><li ><a href="#Portability" >Portability</a></li><li ><a href="#FAQ" >FAQ</a></li><li ><a href="#History" >History</a></li></ul><hr size="1" ><h2 >Introduction</h2><a name="Introduction" ></a><p >This library makes it possible to treat different types as if they have
|
||||
implemented a subset of the container requirements
|
||||
(see §23.1of the C++ standard). Formally, that subset is defined by
|
||||
the <a href="Collection.htm" target="_self" >CollectionConcept.</a>
|
||||
The subset deals mostly with
|
||||
iterator returning functions and nested <code >typedef</code>s.
|
||||
The main goal is to treat built-in arrays, standard containers,
|
||||
pairs of iterators and some iterators uniformly. Formally, this library is an implementation
|
||||
of the <a href="#ExternalCollectionConcept" >ExternalCollectionConcept</a> (see also this explanation of <a href="external_concepts.html" target="_self" >External Concepts</a> ).</p><p >The main advantages are <ul ><li >safe use of built-in arrays</li><li >simpler implementation of generic container algorithms</li><li >more flexible client code</li><li >correct handling of null-terminated strings</li></ul></p><p >Below are given a small example (the complete example can be found <a href="../test/algorithm_example.cpp" target="_self" >here</a> ):<pre >
|
||||
//
|
||||
// Example: extracting bounds in generic algorithms
|
||||
//
|
||||
|
||||
template< typename ExternalCollection, typename T >
|
||||
inline typename boost::iterator_of<ExternalCollection>::type
|
||||
find( ExternalCollection& c, const T& value )
|
||||
{
|
||||
return std::find( boost::begin( c ), boost::end( c ), value );
|
||||
}
|
||||
<!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>
|
||||
|
||||
template< typename ExternalCollection, typename T >
|
||||
inline typename boost::const_iterator_of<ExternalCollection>::type
|
||||
find( const ExternalCollection& c, const T& value )
|
||||
{
|
||||
return std::find( boost::begin( c ), boost::end( c ), value );
|
||||
}
|
||||
|
||||
//
|
||||
// replace first value and return its index
|
||||
//
|
||||
template< typename EC, typename T >
|
||||
inline typename boost::size_type_of< EC >::type
|
||||
my_generic_replace( EC& c, const T& value, const T& replacement )
|
||||
{
|
||||
typename boost::const_iterator_of<EC>::type found = find( c, value );
|
||||
*found = replacement;
|
||||
return std::distance( boost::begin( c ), found );
|
||||
}
|
||||
|
||||
//
|
||||
// usage
|
||||
//
|
||||
std::vector<int> my_vector;
|
||||
typedef vector<int>::iterator iterator;
|
||||
std::pair<iterator,iterator> my_view( my_vector.begin(), my_vector.begin() + N );
|
||||
char str[] = "a string";
|
||||
// ...
|
||||
std::cout << my_generic_replace( my_vector, 4, 2 )
|
||||
<< my_generic_replace( my_view, 4, 2 )
|
||||
<< my_generic_replace( str, 'a', 'b' );
|
||||
</pre>By using the free-standing functions and type-generators, the code automatically
|
||||
works for all the types supported by this library. Notice that we have to provide
|
||||
two version of <code >find()</code> since we cannot
|
||||
forward a non-const rvalue with reference arguments (see this article about <a href="http://std.dkuug.dk/jtc1/sc22/wg21/docs/papers/2002/n1385.htm" target="_self" >The Forwarding Problem</a> ).</p><hr size="1" ><h2 >Reference</h2><a name="Reference" ></a><p ><pre >#include <boost/collection_traits.hpp></pre></p><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
|
||||
<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
|
||||
{
|
||||
//
|
||||
//
|
||||
// type generators
|
||||
//
|
||||
//
|
||||
|
||||
template< typename EC >
|
||||
template< typename EC >
|
||||
struct <a href="#value_type_of" >value_type_of</a>
|
||||
{
|
||||
typedef ... type; // type of stored objects
|
||||
typedef ... type; // type of stored objects
|
||||
};
|
||||
|
||||
template< typename EC >
|
||||
struct <a href="#iterator_of" >iterator_of</a>
|
||||
template< typename EC >
|
||||
struct <a href="#iterator_of" >iterator_of</a>
|
||||
{
|
||||
typedef ... type; // iterator over stored objects
|
||||
};
|
||||
|
||||
template< typename EC >
|
||||
struct <a href="#const_iterator_of" >const_iterator_of</a>
|
||||
template< typename EC >
|
||||
struct <a href="#const_iterator_of" >const_iterator_of</a>
|
||||
{
|
||||
typedef ... type; // iterator over immutable stored objects
|
||||
typedef ... type; // iterator over immutable stored objects
|
||||
};
|
||||
|
||||
template< typename EC >
|
||||
template< typename EC >
|
||||
struct <a href="#difference_type_of" >difference_type_of</a>
|
||||
{
|
||||
typedef ... type;
|
||||
typedef ... type;
|
||||
BOOST_STATIC_ASSERT( boost::is_signed< type >::value );
|
||||
//
|
||||
// remark: if std::iterator_traits<> works for the type, this assertion must hold
|
||||
// remark: if std::iterator_traits<> works for the type, this assertion must
|
||||
hold
|
||||
//
|
||||
BOOST_STATIC_ASSERT( boost::is_same< type, std::iterator_traits< typename
|
||||
<a href="#iterator_of" >iterator_of</a>< EC >::type >::difference_type>::value );
|
||||
BOOST_STATIC_ASSERT( boost::is_same< type, std::iterator_traits< typename
|
||||
<a href="#iterator_of" >iterator_of</a>< EC >::type >::difference_type>::value );
|
||||
};
|
||||
|
||||
template< typename EC >
|
||||
template< typename EC >
|
||||
struct <a href="#size_type_of" >size_type_of</a>
|
||||
{
|
||||
typedef ... type;
|
||||
BOOST_STATIC_ASSERT( boost::is_unsigned< type >::value );
|
||||
BOOST_STATIC_ASSERT( sizeof( type ) >= sizeof( <a href="#difference_type_of" >difference_type_of</a>< EC >::type ) );
|
||||
BOOST_STATIC_ASSERT( sizeof( type ) >= sizeof( <a href="#difference_type_of" >
|
||||
difference_type_of</a>< EC >::type ) );
|
||||
};
|
||||
|
||||
template< typename EC >
|
||||
struct <a href="#result_iterator_of" >result_iterator_of</a>
|
||||
template< typename EC >
|
||||
struct <a href="#result_iterator_of" >result_iterator_of</a>
|
||||
{
|
||||
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
|
||||
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
|
||||
};
|
||||
|
||||
//
|
||||
@ -115,15 +131,15 @@
|
||||
|
||||
template< typename EC >
|
||||
inline typename iterator_of<EC>::type
|
||||
<a href="#begin" >begin</a>( EC& c );
|
||||
<a href="#begin" >begin</a>( EC& c );
|
||||
|
||||
template< typename EC >
|
||||
inline typename const_iterator_of< EC >::type
|
||||
<a href="#begin" >begin</a>( const EC& c );
|
||||
<a href="#begin" >begin</a>( const EC& c );
|
||||
|
||||
template< typename EC >
|
||||
inline typename iterator_of< EC >::type
|
||||
<a href="#end" >end</a>( EC& c );
|
||||
<a href="#end" >end</a>( EC& c );
|
||||
|
||||
template< typename EC >
|
||||
inline typename const_iterator_of< EC >::type
|
||||
@ -131,38 +147,230 @@
|
||||
|
||||
template< typename EC >
|
||||
inline bool
|
||||
<a href="#empty" >empty</a>( const EC& c );
|
||||
<a href="#empty" >empty</a>( const EC& c );
|
||||
|
||||
template< typename EC >
|
||||
inline typename size_type_of< EC >::type
|
||||
<a href="#size" >size</a>( const EC& c );
|
||||
|
||||
} // namespace 'boost' </pre></p><h3 >Library headers</h3><a name="Library headers" ></a><table cellpadding=5 border=1 > <tr ><th >Header</th><th >Includes</th></tr><tr ><td ><code ><boost/collection_traits.hpp></code></td><td >everything</td></tr><tr ><td ><code ><boost/collection_traits/types.hpp></code></td><td >every type-generator</td></tr><tr ><td ><code ><boost/collection_traits/functions.hpp></code></td><td >every function</td></tr><tr ><td ><code ><boost/collection_traits/value_type.hpp></code></td><td ><a href="#value_type_of" >value_type_of</a></td></tr><tr ><td ><code ><boost/collection_traits/iterator.hpp></code></td><td ><a href="#iterator_of" >iterator_of</a></td></tr><tr ><td ><code ><boost/collection_traits/const_iterator.hpp></code></td><td ><a href="#const_iterator_of" >const_iterator_of</a></td></tr><tr ><td ><code ><boost/collection_traits/difference_type.hpp></code></td><td ><a href="#difference_type_of" >difference_type_of</a></td></tr><tr ><td ><code ><boost/collection_traits/size_type.hpp></code></td><td ><a href="#size_type_of" >size_type_of</a></td></tr><tr ><td ><code ><boost/collection_traits/result_iterator.hpp></code></td><td ><a href="#result_iterator_of" >result_iterator_of</a></td></tr><tr ><td ><code ><boost/collection_traits/begin.hpp></code></td><td ><a href="#begin" >begin</a></td></tr><tr ><td ><code ><boost/collection_traits/end.hpp></code></td><td ><a href="#end" >end</a></td></tr><tr ><td ><code ><boost/collection_traits/empty.hpp></code></td><td ><a href="#empty" >empty</a></td></tr><tr ><td ><code ><boost/collection_traits/size.hpp></code></td><td ><a href="#size" >size</a></td></tr> </table><br><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><code >std::iterator_traits<I>::value_type</code></td><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><code >I</code></td><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><code >I</code></td><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><code >std::iterator_traits<I>::difference_type</code></td><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><code >std::size_t</code></td><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> </table> <br> <table border=1 cellpadding=5 > <tr ><th >Expression</th><th >Return type</th><th >Effects</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><code >i</code></td><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><code >I()</code></td><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><code >begin( i ) == end( i )</code></td><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><code >not available for iterators</code></td><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> </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><br><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 size="1" ><h2 >Portability</h2><a name="Portability" ></a><p >Full support for built-in arrays require that the
|
||||
compiler supports class template partial specialization.</p><p >Notice that some compilers cannot do function template ordering
|
||||
properly. In that case one cannot rely of <code >result_iterator_of<></code> and a single function definition; instead one needs to supply
|
||||
a function overloaded for const and non-const arguments if it is required.</p><p >Full support for iterators like <code >std::istream_iterator<></code> depends very
|
||||
much on a conforming standard library.</p><p >Most of the tests have been run successfully on these compilers<ul ><li >vc7.1</li><li >gcc3.2</li><li >como4.3.0.1</li><li >bcc6</li></ul></p><hr size="1" ><h2 >FAQ</h2><a name="FAQ" ></a><ol ><li >Why is there no difference between <code >iterator_of<C>::type</code> and <code >const_iterator_of<C>::type</code> for <code >std::pair<iterator,iterator></code> or iterators which default construction denotes the end of the range?</li><p >In general it is not possible nor desirable to find a corresponding <code >const_iterator</code>. When it is possible to come up with
|
||||
one, the client might choose to
|
||||
construct a <code >std::pair<const_iterator,const_iterator></code> object. </p><li >Why does the traits not supply more types or more functions?<p >The traits class have been kept small because its current interface
|
||||
will serve most purposes. If and when a genuine need arises for
|
||||
more functionality, it can be implemented.</p></li><li >How should I implement generic algorithms for external collections?<p >One should always start with a generic algorithm that takes two iterators as input. Then use the
|
||||
collection traits to build handier versions on top of the base algorithm.</p></li></ol><hr size="1" ><h2 >History</h2><a name="History" ></a><p >The library have been under way for a long time. Dietmar K<>hl originally
|
||||
intended to submit an <code >array_traits<></code> class template which had most
|
||||
of the functionality present now, but only for arrays and standard containers.
|
||||
Meanwhile work on container algorithms
|
||||
in various context showed the need for handling pairs of iterators, and
|
||||
string libraries needed special treatment of character arrays.
|
||||
Thorsten Ottosen wrote everything from the ground up including the first
|
||||
work-around for missing partial template specialization. Pavol Droba helped to
|
||||
improve the work-around for handicapped compilers and the special character support.
|
||||
The naming scheme of type-generators was suggested by Peter Dimov. </p><hr size="1" ><p >© Thorsten Ottosen 2003-2004 (nesotto_AT_cs.auc.dk).
|
||||
Permission to copy, use, modify, sell and distribute this software is granted provided this copyright notice appears
|
||||
in all copies. This software is provided "as is" without express or implied warranty, and with no
|
||||
claim as to its suitability for any purpose.</p><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br></body></html>
|
||||
<!-- Copyright Dezide Aps 2003-2004 -->
|
||||
} // 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>
|
||||
|
||||
75
doc/faq.html
Executable file
75
doc/faq.html
Executable file
@ -0,0 +1,75 @@
|
||||
<!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 FAQ </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</h1></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<p>
|
||||
<h2 >FAQ</h2>
|
||||
<a name="FAQ" ></a>
|
||||
<ol >
|
||||
<li >
|
||||
Why is there no difference between <code >iterator_of<C>::type</code> and <code >const_iterator_of<C>::type</code>
|
||||
for <code >std::pair<iterator, iterator></code>.
|
||||
</li>
|
||||
<p >
|
||||
In general it is not possible nor desirable to find a corresponding <code >const_iterator</code>.
|
||||
When it is possible to come up with one, the client might choose to construct a <code >std::pair<const_iterator,const_iterator></code>
|
||||
object.
|
||||
</p>
|
||||
<li >
|
||||
Why is there not supplied more types or more functions?
|
||||
<p >
|
||||
The library have been kept small because its current interface will serve
|
||||
most purposes. If and when a genuine need arises for more functionality, it can
|
||||
be implemented.
|
||||
</p>
|
||||
</li>
|
||||
<li >
|
||||
How should I implement generic algorithms for ranges?
|
||||
<p >
|
||||
One should always start with a generic algorithm that takes two
|
||||
iterators (or more) as
|
||||
input. Then use Boost.Range to build handier versions on top of the
|
||||
iterator based algorithm. Please notice that once the range version
|
||||
of the algorithm is done, it makes sense <i>not</i> to expose the
|
||||
iterator version in the public interface.
|
||||
</p>
|
||||
</li>
|
||||
</ol>
|
||||
|
||||
|
||||
<hr>
|
||||
<p>
|
||||
(C) Copyright Thorsten Ottosen 2003-2004
|
||||
</p>
|
||||
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
|
||||
|
||||
</body>
|
||||
</html>
|
||||
|
||||
134
doc/headers.html
Executable file
134
doc/headers.html
Executable file
@ -0,0 +1,134 @@
|
||||
<!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 Headers </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</h1></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<p>
|
||||
<h2 >Library headers</h2><a name="Library headers" ></a>
|
||||
<table cellpadding="5" border="1" >
|
||||
<tr >
|
||||
<th >Header</th>
|
||||
<th >Includes</th>
|
||||
</tr>
|
||||
<tr >
|
||||
<td ><code ><boost/range.hpp></code></td>
|
||||
<td >everything</td>
|
||||
</tr>
|
||||
<tr >
|
||||
<td ><code ><boost/range/types.hpp></code></td>
|
||||
<td >every meta-function</td>
|
||||
</tr>
|
||||
<tr >
|
||||
<td ><code ><boost/range/functions.hpp></code></td>
|
||||
<td >every function</td>
|
||||
</tr>
|
||||
<tr >
|
||||
<td ><code ><boost/range/value_type.hpp></code></td>
|
||||
<td ><a href="boost_range.html#value_type_of" >value_type_of</a></td>
|
||||
</tr>
|
||||
<tr >
|
||||
<td ><code ><boost/range/iterator.hpp></code></td>
|
||||
<td ><a href="boost_range.html#iterator_of" >iterator_of</a></td>
|
||||
</tr>
|
||||
<tr >
|
||||
<td ><code ><boost/range/const_iterator.hpp></code></td>
|
||||
<td ><a href="boost_range.html#const_iterator_of" >const_iterator_of</a></td>
|
||||
</tr>
|
||||
<tr >
|
||||
<td ><code ><boost/range/difference_type.hpp></code></td>
|
||||
<td ><a href="boost_range.html#difference_type_of" >difference_type_of</a></td>
|
||||
</tr>
|
||||
<tr >
|
||||
<td ><code ><boost/range/size_type.hpp></code></td>
|
||||
<td ><a href="boost_range.html#size_type_of" >size_type_of</a></td>
|
||||
</tr>
|
||||
<tr >
|
||||
<td ><code ><boost/range/result_iterator.hpp></code></td>
|
||||
<td ><a href="boost_range.html#result_iterator_of" >result_iterator_of</a></td>
|
||||
</tr>
|
||||
<tr >
|
||||
<td ><code ><boost/range/reverse_iterator.hpp></code></td>
|
||||
<td ><a href="boost_range.html#reverse_iterator_of" >reverse_iterator_of</a></td>
|
||||
</tr>
|
||||
<tr >
|
||||
<td ><code ><boost/range/const_reverse_iterator.hpp></code></td>
|
||||
<td ><a href="boost_range.html#const_reverse_iterator_of" >const_reverse_iterator_of</a></td>
|
||||
</tr>
|
||||
<tr >
|
||||
<td ><code ><boost/range/reverse_result_iterator.hpp></code></td>
|
||||
<td ><a href="boost_range.html#reverse_result_iterator_of">reverse_result_iterator_of</a></td>
|
||||
</tr>
|
||||
<tr >
|
||||
<td ><code ><boost/range/begin.hpp></code></td>
|
||||
<td ><a href="boost_range.html#begin" >begin</a></td>
|
||||
</tr>
|
||||
<tr >
|
||||
<td ><code ><boost/range/end.hpp></code></td>
|
||||
<td ><a href="boost_range.html#end" >end</a></td>
|
||||
</tr>
|
||||
<tr >
|
||||
<td ><code ><boost/range/empty.hpp></code></td>
|
||||
<td ><a href="boost_range.html#empty" >empty</a></td>
|
||||
</tr>
|
||||
<tr >
|
||||
<td ><code ><boost/range/size.hpp></code></td>
|
||||
<td ><a href="boost_range.html#size" >size</a></td>
|
||||
</tr>
|
||||
<tr >
|
||||
<td ><code ><boost/range/rbegin.hpp></code></td>
|
||||
<td ><a href="boost_range.html#rbegin" >rbegin</a></td>
|
||||
</tr>
|
||||
<tr >
|
||||
<td ><code ><boost/range/rend.hpp></code></td>
|
||||
<td ><a href="boost_range.html#rend" >rend</a></td>
|
||||
</tr>
|
||||
<tr >
|
||||
<td ><code ><boost/range/iterator_range.hpp></code></td>
|
||||
<td ><a href="utility_class.html#iter_range"
|
||||
>iterator_range</a></td>
|
||||
</tr>
|
||||
<tr >
|
||||
<td ><code ><boost/range/sub_range.hpp></code></td>
|
||||
<td ><a href="utility_class.html#sub_range" >sub_range</a></td>
|
||||
</tr>
|
||||
|
||||
</table>
|
||||
<br
|
||||
</p>
|
||||
|
||||
|
||||
<hr>
|
||||
<p>
|
||||
(C) Copyright Thorsten Ottosen 2003-2004
|
||||
</p>
|
||||
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
|
||||
|
||||
</body>
|
||||
</html>
|
||||
|
||||
62
doc/history_ack.html
Executable file
62
doc/history_ack.html
Executable file
@ -0,0 +1,62 @@
|
||||
<!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 History and Acknowledgement </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 </h1></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h2 >History and Acknowledgement</h2><a name="History" ></a>
|
||||
<p >
|
||||
The library have been under way for a long time. Dietmar K<>hl originally
|
||||
intended to submit an <code >array_traits<></code> class template which
|
||||
had most of the functionality present now, but only for arrays and standard
|
||||
containers.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Meanwhile work on container algorithms in various context showed the
|
||||
need for handling pairs of iterators, and string libraries needed special
|
||||
treatment of character arrays.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Special thanks goes to
|
||||
<ul>
|
||||
<li> Pavol Droba
|
||||
<li> Pavel Vozenilek
|
||||
<li> Jonathan Turkanis
|
||||
</ul>
|
||||
</p>
|
||||
<hr>
|
||||
<p>
|
||||
(C) Copyright Thorsten Ottosen 2003-2004
|
||||
</p>
|
||||
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
|
||||
|
||||
</body>
|
||||
</html>
|
||||
|
||||
125
doc/intro.html
Executable file
125
doc/intro.html
Executable file
@ -0,0 +1,125 @@
|
||||
<!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 Introduction </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</h1></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h2>Introduction</h2>
|
||||
<p>
|
||||
This library makes it possible to treat different types as if they have
|
||||
implemented a subset of the container requirements (see §23.1of the C++
|
||||
standard). Formally, that subset is defined by the <a href="Range.htm"
|
||||
target="_self" >Range</a> concept. The subset deals mostly with iterator
|
||||
returning functions and nested <code >typedef</code>s. The main goal is to treat
|
||||
built-in arrays, standard containers, pairs of iterators and some iterators
|
||||
uniformly.
|
||||
</p>
|
||||
<p >
|
||||
The main advantages are
|
||||
<ul >
|
||||
<li >
|
||||
safe use of built-in arrays
|
||||
</li>
|
||||
<li >
|
||||
simpler implementation of generic container algorithms
|
||||
</li>
|
||||
<li >
|
||||
more flexible client code
|
||||
</li>
|
||||
<li >
|
||||
correct handling of null-terminated strings
|
||||
</li>
|
||||
</ul>
|
||||
</p>
|
||||
<p >
|
||||
Below are given a small example (the complete example can be found <a href="../test/algorithm_example.cpp" target="_self" >here</a>
|
||||
):
|
||||
<pre >
|
||||
|
||||
//
|
||||
// Example: extracting bounds in generic algorithms
|
||||
//
|
||||
|
||||
template< typename XRange, typename T >
|
||||
inline typename boost::iterator_of<XRange>::type
|
||||
find( XRange& c, const T& value )
|
||||
{
|
||||
return std::find( boost::begin( c ), boost::end( c ), value );
|
||||
}
|
||||
|
||||
template< typename XRange, typename T >
|
||||
inline typename boost::const_iterator_of<XRange>::type
|
||||
find( const XRange& c, const T& value )
|
||||
{
|
||||
return std::find( boost::begin( c ), boost::end( c ), value );
|
||||
}
|
||||
|
||||
//
|
||||
// replace first value and return its index
|
||||
//
|
||||
template< typename EC, typename T >
|
||||
inline typename boost::size_type_of< EC >::type
|
||||
my_generic_replace( EC& c, const T& value, const T& replacement )
|
||||
{
|
||||
typename boost::const_iterator_of<EC>::type found = find( c, value );
|
||||
*found = replacement;
|
||||
return std::distance( boost::begin( c ), found );
|
||||
}
|
||||
|
||||
//
|
||||
// usage
|
||||
//
|
||||
std::vector<int> my_vector;
|
||||
typedef vector<int>::iterator iterator;
|
||||
std::pair<iterator,iterator> my_view( my_vector.begin(), my_vector.begin(
|
||||
) + N );
|
||||
char str[] = "a string";
|
||||
// ...
|
||||
std::cout << my_generic_replace( my_vector, 4, 2 )
|
||||
<< my_generic_replace( my_view, 4, 2 )
|
||||
<< my_generic_replace( str, 'a', 'b' );
|
||||
</pre>
|
||||
|
||||
By using the free-standing functions and type-generators, the code automatically
|
||||
works for all the types supported by this library. Notice that we have to
|
||||
provide two version of <code >find()</code> since we cannot forward a non-const
|
||||
rvalue with reference arguments (see this article about <a href="http://std.dkuug.dk/jtc1/sc22/wg21/docs/papers/2002/n1385.htm" target="_self" >The
|
||||
Forwarding Problem</a> ).
|
||||
|
||||
</p>
|
||||
|
||||
|
||||
<hr>
|
||||
<p>
|
||||
(C) Copyright Thorsten Ottosen 2003-2004
|
||||
</p>
|
||||
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
|
||||
|
||||
</body>
|
||||
</html>
|
||||
|
||||
63
doc/portability.html
Executable file
63
doc/portability.html
Executable file
@ -0,0 +1,63 @@
|
||||
<!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 Portability </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</h1></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h2>Portability</h2><a name="Portability" ></a>
|
||||
<p >
|
||||
Full support for built-in arrays require that the compiler supports class
|
||||
template partial specialization. For non-conforming compilers there might
|
||||
be a change that it works anyway thanks to workarounds in the type traits
|
||||
library. </p>
|
||||
<p >
|
||||
Notice that some compilers cannot do function template ordering properly. In
|
||||
that case one must rely of <code >result_iterator_of<></code> and a
|
||||
single function definition instead of
|
||||
overloaded versions for const and non-const arguments.
|
||||
|
||||
|
||||
So if one cares about old compilers, one should not pass rvalues
|
||||
to the functions.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
A huge effort has been made to port the library to as many compilers as
|
||||
possible. The results of the test-suites can be found
|
||||
<a href="http://boost.sourceforge.net/regression-logs/developer/range.html">here</a>.
|
||||
</p>
|
||||
|
||||
<hr>
|
||||
<p>
|
||||
(C) Copyright Thorsten Ottosen 2003-2004
|
||||
</p>
|
||||
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
|
||||
|
||||
</body>
|
||||
</html>
|
||||
|
||||
729
doc/range.htm
729
doc/range.htm
@ -11,181 +11,112 @@
|
||||
-- purpose. It is provided "as is" without express or implied warranty.
|
||||
-->
|
||||
<Head>
|
||||
<Title>Range Concepts</Title>
|
||||
<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">
|
||||
</HEAD>
|
||||
<BODY BGCOLOR="#ffffff" LINK="#0000ee" TEXT="#000000" VLINK="#551a8b"
|
||||
ALINK="#ff0000">
|
||||
<IMG SRC="cboost.gif"
|
||||
ALT="C++ Boost">
|
||||
<IMG SRC="/Images/stat.gif" ALT="" BORDER=0 WIDTH = "6" HEIGHT = "6" >
|
||||
|
||||
<BR Clear>
|
||||
<a name=range>
|
||||
<H1>Range</H1>
|
||||
<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>
|
||||
|
||||
<h3>Description</h3>
|
||||
|
||||
A Range is a <i>concept</i> similar to the STL <a
|
||||
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
|
||||
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
|
||||
|
||||
<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.
|
||||
<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>
|
||||
|
||||
Because of the second requirement, a Range object must
|
||||
be passed by reference in generic code.
|
||||
Because of the second requirement, a Range object must be passed by reference in
|
||||
generic code.
|
||||
|
||||
<p>
|
||||
|
||||
<h3>Notation</h3>
|
||||
<Table>
|
||||
<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>
|
||||
<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>
|
||||
</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 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>
|
||||
</table>
|
||||
|
||||
|
||||
@ -194,395 +125,209 @@ An unsigned integral type that can represent any nonnegative value
|
||||
The following expressions must be valid.
|
||||
<p>
|
||||
|
||||
<Table border>
|
||||
<TR>
|
||||
<TH>
|
||||
Name
|
||||
</TH>
|
||||
<TH>
|
||||
Expression
|
||||
</TH>
|
||||
<TH>
|
||||
Return type
|
||||
</TH>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
Beginning of range
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a.begin()</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>a.end()</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
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a.size()</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>size_type</tt>
|
||||
</TD>
|
||||
</TR>
|
||||
<!--
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
Maximum size
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a.max_size()</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>size_type</tt>
|
||||
</TD>
|
||||
</TR>
|
||||
<TR>
|
||||
-->
|
||||
<TD VAlign=top>
|
||||
Empty range
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a.empty()</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
Convertible to <tt>bool</tt>
|
||||
</TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<!--
|
||||
<TD VAlign=top>
|
||||
Swap
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a.swap(b)</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>void</tt>
|
||||
</TD> -->
|
||||
</tr>
|
||||
<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>
|
||||
</table>
|
||||
<h3>Expression semantics</h3>
|
||||
|
||||
<Table border>
|
||||
<TR>
|
||||
<TH>
|
||||
Name
|
||||
</TH>
|
||||
<TH>
|
||||
Expression
|
||||
</TH>
|
||||
<TH>
|
||||
Semantics
|
||||
</TH>
|
||||
<TH>
|
||||
Postcondition
|
||||
</TH>
|
||||
</TR>
|
||||
<TD VAlign=top>
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
Beginning of range
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a.begin()</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
Returns an iterator pointing to the first element in the Range.
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a.begin()</tt> is either dereferenceable or past-the-end. It is
|
||||
past-the-end if and only if <tt>a.size() == 0</tt>.
|
||||
</TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
End of range
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a.end()</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
Returns an iterator pointing one past the last element in the
|
||||
Range.
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a.end()</tt> is past-the-end.
|
||||
</TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
Size
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a.size()</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
Returns the size of the Collection, that is, its number of elements.
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a.size() >= 0
|
||||
</TD>
|
||||
</TR>
|
||||
<!--
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
Maximum size
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a.max_size()</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
Returns the largest size that this Collection can ever have. <A href="#8">[8]</A>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a.max_size() >= 0 && a.max_size() >= a.size()</tt>
|
||||
</TD>
|
||||
</TR>
|
||||
-->
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
Empty Collection
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a.empty()</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
Equivalent to <tt>a.size() == 0</tt>. (But possibly faster.)
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
|
||||
</TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<!--
|
||||
<TD VAlign=top>
|
||||
Swap
|
||||
</TD>
|
||||
|
||||
<TD VAlign=top>
|
||||
<tt>a.swap(b)</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
Equivalent to <tt>swap(a,b)</tt>
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
|
||||
</TD>
|
||||
-->
|
||||
</tr>
|
||||
<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>
|
||||
</table>
|
||||
|
||||
<h3>Complexity guarantees</h3>
|
||||
|
||||
All four functions are at most amortized linear time. For
|
||||
most practical purposes, one can expect
|
||||
<tt>begin()</tt>, <tt>end()</tt> and <tt>empty()</tt> to be amortized constant
|
||||
time.
|
||||
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.
|
||||
|
||||
<h3>Invariants</h3>
|
||||
<Table border>
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
Valid range
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
For any Range <tt>a</tt>, <tt>[a.begin(), a.end())</tt> is a valid
|
||||
range.
|
||||
</TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
Range size
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a.size()</tt> is equal to the distance from <tt>a.begin()</tt> to <tt>a.end()</tt>.
|
||||
</TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
Completeness
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
An algorithm that iterates through the range <tt>[a.begin(), a.end())</tt>
|
||||
will pass through every element of <tt>a</tt>.
|
||||
</TD>
|
||||
</tr>
|
||||
<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>
|
||||
</table>
|
||||
|
||||
|
||||
<h3>Models</h3>
|
||||
<UL>
|
||||
<LI> <tt>boost::array<T,sz></tt>
|
||||
<LI> <tt>std::vector<bool></tt>
|
||||
<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>
|
||||
</UL>
|
||||
|
||||
<h3>See also</h3>
|
||||
<A href="http://www.sgi.com/Technology/STL/Container.html">Container</A>
|
||||
<h3>See also</h3> <A href="http://www.sgi.com/Technology/STL/Container.html">Container</A>
|
||||
|
||||
<br><br>
|
||||
<br>
|
||||
<br>
|
||||
<hr>
|
||||
<br>
|
||||
|
||||
<a name=reversible_range>
|
||||
<h1>ReversibleRange</h1>
|
||||
<a name=reversible_range><h1>ReversibleRange</h1>
|
||||
|
||||
|
||||
<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.
|
||||
<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.
|
||||
|
||||
<h3>Refinement of</h3>
|
||||
Range
|
||||
<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>
|
||||
<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>
|
||||
<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>a.rbegin()</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(a.end())</tt>.
|
||||
</TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD VAlign=top>
|
||||
End of range
|
||||
</TD>
|
||||
<TD VAlign=top>
|
||||
<tt>a.rend()</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(a.begin())</tt>.
|
||||
</TD>
|
||||
</tr>
|
||||
<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>
|
||||
|
||||
</table>
|
||||
|
||||
<h3>Complexity guarantees</h3>
|
||||
|
||||
<tt>rbegin()</tt> has the same complexity as <tt>end()</tt> and
|
||||
<tt>rend()</tt> has the same complexity as <tt>begin()</tt> from Range.
|
||||
<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.
|
||||
|
||||
<h3>Models</h3>
|
||||
|
||||
<ul>
|
||||
<li> std::vector<T>
|
||||
<li> std::list<T>
|
||||
<li>
|
||||
std::vector<T>
|
||||
<li>
|
||||
std::list<T>
|
||||
</ul>
|
||||
|
||||
<hr>
|
||||
<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
|
||||
requirements of the reference type depend on the context within which
|
||||
the Range is being used. Specifically it depends on the
|
||||
requirements the context places on the value type of the Range.
|
||||
The reference type of the Range must meet the same requirements
|
||||
as the value type. In addition, the reference objects must be
|
||||
equivalent to the value type objects in the Range (which is
|
||||
trivially true if they are the same). Also, in a mutable Range,
|
||||
an assignment to the reference object must result in an assignment to
|
||||
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
|
||||
class).
|
||||
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
|
||||
|
||||
|
||||
<br><br>
|
||||
<br>
|
||||
<br>
|
||||
<HR>
|
||||
<br>
|
||||
|
||||
<TABLE>
|
||||
<TR valign=top>
|
||||
<TD nowrap>Copyright © 2000</TD><TD>
|
||||
<A HREF=http://www.boost.org/people/jeremy_siek.htm>Jeremy Siek</A>, Univ.of Notre Dame and C++ Library & Compiler Group/SGI (<A HREF="mailto:jsiek@engr.sgi.com">jsiek@engr.sgi.com</A>)
|
||||
</TD></TR>
|
||||
<tr >
|
||||
<TD nowrap>Copyright © 2004</TD><TD>
|
||||
Thorsten Ottosen.
|
||||
<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.
|
||||
</TABLE>
|
||||
|
||||
</BODY>
|
||||
</HTML>
|
||||
</HTML>
|
||||
|
||||
@ -21,3 +21,11 @@ pre{
|
||||
.preprocessor{color: #3F007F;}
|
||||
.string{font-style: italic; color: #666666;}
|
||||
.literal{font-style: italic; color: #666666;}
|
||||
|
||||
table
|
||||
{
|
||||
cellpadding: 5px;
|
||||
border: 2px;
|
||||
}
|
||||
|
||||
|
||||
|
||||
229
doc/style.html
229
doc/style.html
@ -2,145 +2,122 @@
|
||||
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
||||
<title>Boost.Range Terminology and Style Guidelines </title>
|
||||
<link rel="stylesheet" href="style.css" type="text/css">
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
||||
<title>Boost.Range Terminology and Style Guidelines </title>
|
||||
<link rel="stylesheet" href="style.css" type="text/css">
|
||||
</head>
|
||||
|
||||
<body>
|
||||
<body>
|
||||
|
||||
<table border="0" >
|
||||
<tr>
|
||||
<td ><img src="cboost.gif" border="0" ></td>
|
||||
<td >
|
||||
<h1 align="center">Boost.Range terminology and style guidelines</h1>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<p>
|
||||
The use of a consistent terminologi is as important for
|
||||
iterator <a href="range.html#range">Range</a>s and
|
||||
<a href="range.html#external_range">ExternalRange</a>-based algorithms
|
||||
as it is for iterators and iterator-based algorithms.
|
||||
If a conventional set of names are adopted, we can avoid misunderstandings
|
||||
and write generic function prototypes that are <i>self-documenting</i>.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Since iterator ranges are characterized by a specific underlying
|
||||
iterator type, we get a type of iterator range for each type of
|
||||
iterator. Hence we can speak of the following types of iterator
|
||||
ranges:
|
||||
<ul>
|
||||
<li> Range
|
||||
<li> ReversibleRange
|
||||
<li> <i>Value access</i> category:
|
||||
<ul>
|
||||
<li> ReadableRange
|
||||
<li> WriteableRange
|
||||
<li> SwappableRange
|
||||
<li> LvalueRange
|
||||
</ul>
|
||||
<li> <i>Traversal</i> category:
|
||||
<ul>
|
||||
<li> IncrementableRange
|
||||
<li> SinglePassRange
|
||||
<li> ForwardRange
|
||||
<li> BidirectionalRange
|
||||
<li> RandomAccessRange
|
||||
</ul>
|
||||
</ul>
|
||||
Notice how we have used the categories from the
|
||||
<a href=../../iterator/doc/new-iter-concepts.html>new style iterators</a>.
|
||||
Similarly, for <a href="range.html#external_range">ExternalRange</a>
|
||||
we have
|
||||
<ul>
|
||||
<li> XRange
|
||||
<li> XReversibleRange
|
||||
<li> <i>Value access</i> category:
|
||||
<ul>
|
||||
<li> XReadableRange
|
||||
<li> XWriteableRange
|
||||
<li> XSwappableRange
|
||||
<li> XLvalueRange
|
||||
</ul>
|
||||
<li> <i>Traversal</i> category:
|
||||
<ul>
|
||||
<li> XIncrementableRange
|
||||
<li> XSinglePassRange
|
||||
<li> XForwardRange
|
||||
<li> XBidirectionalRange
|
||||
<li> XRandomAccessRange
|
||||
</ul>
|
||||
</ul>
|
||||
The convention of using an <code>X</code> to mean "External" save us from
|
||||
rediculously long parameter names and is easy to associate with an
|
||||
<a href=external_concepts.html>external concept</a>.
|
||||
|
||||
<p>
|
||||
Notice that an interator (and therefore an iterator range) has
|
||||
one <i>traversal</i> property and one or more properties from the
|
||||
<i>value access</i> category. So in reality we will mostly talk about
|
||||
mixtures such as <ul> <li>RandomAccessReadableWriteableRange
|
||||
<li>XForwardLvalueRange
|
||||
</ul>
|
||||
By convention, we should always specify the <i>travelsal</i> property first
|
||||
as done above. This seems resonable since there will only be one
|
||||
<i>traversal</i> property, but perhaps many <i>value acccess</i> properties.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
As an example, consider how we specify the interface of
|
||||
<code>std::sort()</code>. The iterator-based version looks like
|
||||
this:
|
||||
|
||||
<pre>
|
||||
<table border="0" >
|
||||
<tr>
|
||||
<td ><img src="cboost.gif" border="0" ></td>
|
||||
<td ><h1 align="center">Boost.Range </h1></td> </tr>
|
||||
</table>
|
||||
|
||||
<h2>Terminology and style guidelines </h2>
|
||||
|
||||
<p>
|
||||
The use of a consistent terminologi is as important for iterator <a href="range.html#range">Range</a>s
|
||||
and <a href="range.html#external_range">ExternalRange</a>-based algorithms as it
|
||||
is for iterators and iterator-based algorithms. If a conventional set of names
|
||||
are adopted, we can avoid misunderstandings and write generic function
|
||||
prototypes that are <i>self-documenting</i>.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Since iterator ranges are characterized by a specific underlying iterator type,
|
||||
we get a type of iterator range for each type of iterator. Hence we can speak of
|
||||
the following types of iterator ranges:
|
||||
<ul>
|
||||
<li>
|
||||
Range
|
||||
<li>
|
||||
ReversibleRange
|
||||
<li>
|
||||
<i>Value access</i> category:
|
||||
<ul>
|
||||
<li>
|
||||
ReadableRange
|
||||
<li>
|
||||
WriteableRange
|
||||
<li>
|
||||
SwappableRange
|
||||
<li>
|
||||
LvalueRange
|
||||
</ul>
|
||||
<li>
|
||||
<i>Traversal</i> category:
|
||||
<ul>
|
||||
<li>
|
||||
IncrementableRange
|
||||
<li>
|
||||
SinglePassRange
|
||||
<li>
|
||||
ForwardRange
|
||||
<li>
|
||||
BidirectionalRange
|
||||
<li>
|
||||
RandomAccessRange
|
||||
</ul>
|
||||
</ul>
|
||||
Notice how we have used the categories from the <a href=../../iterator/doc/new-iter-concepts.html>new
|
||||
style iterators</a>.
|
||||
|
||||
<p>
|
||||
Notice that an interator (and therefore an iterator range) has one <i>traversal</i>
|
||||
property and one or more properties from the <i>value access</i> category. So in
|
||||
reality we will mostly talk about mixtures such as
|
||||
<ul>
|
||||
<li>
|
||||
RandomAccessReadableWriteableRange
|
||||
<li>
|
||||
ForwardLvalueRange
|
||||
</ul>
|
||||
By convention, we should always specify the <i>travelsal</i> property first as
|
||||
done above. This seems resonable since there will only be one <i>traversal</i>
|
||||
property, but perhaps many <i>value acccess</i> properties.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
As an example, consider how we specify the interface of <code>std::sort()</code>.
|
||||
The iterator-based version looks like this:
|
||||
|
||||
<pre>
|
||||
template< class RandomAccessTraversalReadableWritableIterator >
|
||||
void sort( RandomAccessTraversalReadableWritableIterator first,
|
||||
RandomAccessTraversalReadableWritableIterator last );
|
||||
</pre>
|
||||
For external iterator ranges the interface becomes
|
||||
|
||||
<pre>
|
||||
template< class XRandomAccessReadableWritableRange >
|
||||
void sort( XRandomAccessReadableWritableRange& r );
|
||||
</pre>
|
||||
Had the function been specified like
|
||||
|
||||
<pre>
|
||||
For iterator ranges the interface becomes
|
||||
|
||||
<pre>
|
||||
template< class RandomAccessReadableWritableRange >
|
||||
void sort( RandomAccessReadableWritableRange& r );
|
||||
</pre>
|
||||
|
||||
we should expect the underlying code to call <code>r.begin()</code>
|
||||
and <code>r.end()</code> to extract the iterators instead of
|
||||
<code>begin( r )</code> and <code>end( r )</code>. In general
|
||||
it is much more flexible to rely on external iterator ranges
|
||||
than iterator ranges.
|
||||
</p>
|
||||
</p>
|
||||
|
||||
|
||||
<hr>
|
||||
<p>
|
||||
|
||||
|
||||
</p>
|
||||
|
||||
|
||||
<hr>
|
||||
<p>
|
||||
(C) Copyright Thorsten Ottosen 2003-2004
|
||||
</p>
|
||||
</p>
|
||||
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
<br>
|
||||
|
||||
|
||||
</body>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
|
||||
14
index.html
14
index.html
@ -34,18 +34,15 @@
|
||||
</p>
|
||||
|
||||
<ul>
|
||||
<li> Introduction
|
||||
<li> <a href=doc/intro.html>Introduction </a></code>
|
||||
|
||||
<li> Concepts:
|
||||
<li> <a href=doc/range.htm>Concepts:</a>
|
||||
<ul>
|
||||
<li> <a href="doc/range.htm#range">Range</a>
|
||||
<li> <a href="doc/range.htm#reversible_range">ReversibleRange</a>
|
||||
<li> ExternalRange
|
||||
<li> ExternalReversibleRange
|
||||
</ul>
|
||||
|
||||
<li> <a href=doc/boost_range.html>Implementation</a> of ExternalReversibleRange for
|
||||
<ul>
|
||||
<li> <a href=doc/boost_range.html>Implementation</a> of Range and ReversibleRange for <ul>
|
||||
<li> arrays
|
||||
<li> Ranges
|
||||
<li> strings
|
||||
@ -58,7 +55,10 @@
|
||||
<li> Class <a href="doc/utility_class.html#sub_range"><code>sub_range</code></a> </ul>
|
||||
|
||||
<li> <a href=doc/style.html>Terminology and style guidelines </a>
|
||||
<li><a href="#headers">Headers</a> </li>
|
||||
<li><a href="doc/headers.html">Headers</a> </li>
|
||||
<li><a href="doc/portability.html">Portability</a>
|
||||
<li><a href="doc/faq.html">FAQ</a>
|
||||
<li><a href="doc/history_ack.html">History and acknowledgment</a>
|
||||
|
||||
</ul>
|
||||
|
||||
|
||||
Reference in New Issue
Block a user