|
-
|
-
- Four types of objects are currently supported by the library: -
std::pair<iterator,iterator>
- char[],wchar_t[],
- char*, and wchar_t*)
- - Warning: support for null-terminated strings is deprecated and will - disappear in the next Boost release (1.34). -
- -iterator_range implements
- the minimal interface required to make the
- class a Forward Range.
-
-
- - Please also see Range concepts for more details. -
- -- -
+ +Boost.Range Range Implementation + + + + +
|
+
+ |
+
+ Four types of objects are currently supported by the library: +
std::pair<iterator,iterator>
+ char[],wchar_t[],
+ char*, and wchar_t*)
+ + Warning: support for null-terminated strings is deprecated and will + disappear in the next Boost release (1.34). +
+iterator_range implements the minimal
+ interface required to make the class a Forward
+ Range
+ .
+
+ + Please also see Range concepts for more details. +
+ ++
namespace boost { // @@ -207,341 +196,572 @@ class=identifier>T& } // namespace 'boost'- + + +
+
| + Type + | + Object + | + Describes + |
|---|---|---|
X
+ | x
+ | any type | +
T
+ |
+ t
+ | denotes behavior of the primary templates | +
P
+ | p
+ | denotes std::pair<iterator,iterator> |
+
A[sz]
+ | a
+ | denotes an array of type A of size sz
+ |
Char*
+ | s
+ | denotes either char* or wchar_t* |
+
+ 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. +
++
+ The special metafunctions range_result_iterator and range_reverse_result_iterator
+ are not part of any Range concept, but they are very useful when implementing
+ certain Range classes like sub_range
+ because of their ability to select iterators based on constness.
+
+
+ The special const functions are not part of any Range concept, but
+ are very useful when you want to document clearly that your code is read-only.
+
+ This procedure assumes that you have control over the types that should be made + conformant to a Range concept. If not, see method 2. +
+ +
+ The primary templates in this library are implemented such that standard
+ containers will work automatically and so will boost::array.
+ Below is given an overview of which member functions and member types a class
+ must specify to be useable as a certain Range concept.
+
+
| + Member function | ++ Related concept | +
|---|---|
begin() |
+ Single Pass Range | +
end()
+ |
+ Single Pass Range | +
size() |
+ Forward Range | +
+ Notice that rbegin() and rend() member functions are
+ not needed even though the container can support bidirectional iteration.
+
+ The required member types are: +
++
| + Member type | ++ Related concept | +
|---|---|
value_type |
+ Single Pass Range | +
iterator |
+ Single Pass Range | +
const_iterator |
+ Single Pass Range | +
difference_type |
+ Forward Range | +
size_type |
+ Forward Range | +
+ Again one should notice that member types reverse_iterator and const_reverse_iterator
+ are not needed.
+
+ 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 method 1. +
+ +
+ 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 x be a variable (const or mutable)
+ of the class in question.
+
+
| + Function | ++ Related concept | +
|---|---|
boost_range_begin(x) |
+ Single Pass Range | +
boost_range_end(x)
+ |
+ Single Pass Range | +
boos_range_size(x) |
+ Forward Range | +
boost_range_begin() and boost_range_end() must be
+ overloaded for both const and mutable reference arguments.
+
+ You must also specialize 3-5 metafunctions for your type X:
+
+
| + Metafunction | ++ Related concept | +
|---|---|
boost::range_value |
+ Single Pass Range | +
boost::range_iterator |
+ Single Pass Range | +
boost::range_const_iterator |
+ Single Pass Range | +
boost::range_difference |
+ Forward Range | +
boost::range_size |
+ Forward Range | +
+ A complete example is given here: +
+++ ++#include <boost/range.hpp> +#include <iterator> // for std::iterator_traits, std::distance() -notation
--
-
- +namespace Foo +{ + // + // Our sample UDT. A 'Pair' + // will work as a range when the stored + // elements are iterators. + // + template< class T > + struct Pair + { + T first, last; + }; -- -Type - Object - Describes - - -X-x-any type - - -- Tt-denotes behavior of the primary templates -- -P-p-denotes std::pair<iterator,iterator>-- A[sz]-a-denotes an array of type Aof sizesz-- - -Char*-s-denotes either char*orwchar_t*-- 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. -
-Metafunctions
--
- The special metafunctions
+ template< class T > + struct range_iterator< Foo::Pair<T> > + { + typedef T type; + }; -range_result_iteratorandrange_reverse_result_iterator- are not part of any Range concept, but they are very useful when implementing - certain Range classes likesub_rangebecause of their - ability to select iterators based on constness. -Functions
--
- The special
+namespace Foo +{ + // + // The required functions. These should be defined in + // the same namespace as 'Pair', in this case + // in namespace 'Foo'. + // + + template< class T > + inline T boost_range_begin( Pair<T>& x ) + { + return x.first; + } -constfunctions are not part of any Range concept, - but are very useful when you want to document clearly that your code is - read-only. -
-Extending the library
-- The primary templates in this library are implemented such that standard - containers will work automatically and so will
-boost::array. Below is given an overview of - which member functions and member types a class must specify to -be useable as a certain Range concept. --
-
- -- Member function -Related concept -- -- begin()Single Pass Range -- -- end()Single Pass Range -- + template< class T > + inline T boost_range_begin( const Pair<T>& x ) + { + return x.first; + } -- size()Forward Range -- Notice that
-rbegin()andrend()member functions - are not needed even though the container can support bidirectional iteration. -- The required member types are: -
--
-
- -- Member type -Related concept -- - -- value_typeSingle Pass Range -- -- iteratorSingle Pass Range -- -- const_iteratorSingle Pass Range -- -- difference_typeForward Range -- - -- size_typeForward Range -- Again one should notice that member types
- -reverse_iteratorand -const_reverse_iteratorare not needed. -
-- (C) Copyright Thorsten Ottosen 2003-2004 -
+ template< class T > + inline T boost_range_end( Pair<T>& x ) + { + return x.last; + } -
-
-
-
-
-
-
-
-
-
-
-
+ template< class T > + inline T boost_range_end( const Pair<T>& x ) + { + return x.last; + } + template< class T > + inline typename boost::range_size< Pair<T> >::type + boost_range_size( const Pair<T>& x ) + { + return std::distance(x.first,x.last); + } - +} // namespace 'Foo' + +#include <vector> + +int main() +{ + typedef std::vector<int>::iterator iter; + std::vector<int> vec; + Foo::Pair<iter> pair = { vec.begin(), vec.end() }; + const Foo::Pair<iter>& cpair = pair; + // + // Notice that we call 'begin' etc with qualification. + // + iter i = boost::begin( pair ); + iter e = boost::end( pair ); + i = boost::begin( cpair ); + e = boost::end( cpair ); + boost::range_size< Foo::Pair<iter> >::type s = boost::size( pair ); + s = boost::size( cpair ); + boost::range_const_reverse_iterator< Foo::Pair<iter> >::type + ri = boost::rbegin( cpair ), + re = boost::rend( cpair ); +} + +
+ (C) Copyright Thorsten Ottosen 2003-2004 +
+boost::range_const_reverse_iterator<X>::type
rboost::begin(a)boost::rbegin(a)boost::range_reverse_iterator<X>::type if
a is mutable, boost::range_const_reverse_iterator<X>::type
otherwise.boost::range_reverse_iterator<X>::type(boost::end(a)). rboost::end(a)boost::rend(a)boost::range_reverse_iterator<X>::type if
a is mutable, boost::range_const_reverse_iterator<X>::type
otherwise.rboost::begin(a) has the same complexity as boost::end(a) and rboost::end(a)
+ boost::rbegin(a) has the same complexity as boost::end(a) and boost::rend(a)
has the same complexity as boost::begin(a) from Forward Range.
@@ -414,13 +414,13 @@ otherwise.
| Valid reverse range | -For any Bidirectional Range a, [rboost::begin(a),rboost::end(a))
- is a valid range, that is, rboost::end(a) is reachable from rboost::begin(a)
+ | For any Bidirectional Range a, [boost::rbegin(a),boost::rend(a))
+ is a valid range, that is, boost::rend(a) is reachable from boost::rbegin(a)
in a finite number of increments. |
| Completeness | -An algorithm that iterates through the range [rboost::begin(a),rboost::end(a))
+ | An algorithm that iterates through the range [boost::rbegin(a),boost::rend(a))
will pass through every element of a. |