Synopsis and ReferenceOverviewThree types of objects are currently supported by the library:
iterator_range implements the minimal
interface required to make the class a Forward
Range
.
Please also see Range concepts for more details. Synopsis
namespace boost { // // Single Pass Range metafunctions // template< class T > struct range_iterator; template< class T > struct range_value; template< class T > struct range_reference; template< class T > struct range_pointer; template< class T > struct range_category; // // Forward Range metafunctions // template< class T > struct range_difference; // // Bidirectional Range metafunctions // template< class T > struct range_reverse_iterator; // // Single Pass Range functions // template< class T > typename range_iterator<T>::type begin( T& r ); template< class T > typename range_iterator<const T>::type begin( const T& r ); template< class T > typename range_iterator<T>::type end( T& r ); template< class T > typename range_iterator<const T>::type end( const T& r ); template< class T > bool empty( const T& r ); // // Forward Range functions // template< class T > typename range_difference<T>::type distance( const T& r ); // // Bidirectional Range functions // template< class T > typename range_reverse_iterator<T>::type rbegin( T& r ); template< class T > typename range_reverse_iterator<const T>::type rbegin( const T& r ); template< class T > typename range_reverse_iterator<T>::type rend( T& r ); template< class T > typename range_reverse_iterator<const T>::type rend( const T& r ); // // Random Access Range functions // template< class T > typename range_difference<T>::type size( const T& r ); // // Special const Range functions // template< class T > typename range_iterator<const T>::type const_begin( const T& r ); template< class T > typename range_iterator<const T>::type const_end( const T& r ); template< class T > typename range_reverse_iterator<const T>::type const_rbegin( const T& r ); template< class T > typename range_reverse_iterator<const T>::type const_rend( const T& r ); // // String utilities // template< class T > iterator_range<...see below...> as_literal( T& r ); template< class T > iterator_range<...see below...> as_literal( const T& r ); template< class T > iterator_range< typename range_iterator<T>::type > as_array( T& r ); template< class T > iterator_range< typename range_iterator<const T>::type > as_array( const T& r ); } // namespace 'boost' Semanticsnotation
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
Functions
The special
Notice that the above functions should always be called with
qualification ( Extending the library
Method 1: provide member functions and nested typesThis 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
Notice that The required member types are:
Again one should notice that member types Method 2: provide free-standing functions and specialize metafunctionsThis 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
You must also specialize two metafunctions for your type
A complete example is given here: #include <boost/range.hpp> #include <iterator> // for std::iterator_traits, std::distance() 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; }; } // namespace 'Foo' namespace boost { // // Specialize metafunctions. We must include the range.hpp header. // We must open the 'boost' namespace. // template< class T > struct range_mutable_iterator< Foo::Pair<T> > { typedef T type; }; template< class T > struct range_const_iterator< Foo::Pair<T> > { // // Remark: this is defined similar to 'range_mutable_iterator' // because the 'Pair' type does not distinguish // between an iterator and a const_iterator. // typedef T type; }; } // namespace 'boost' 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 range_begin( Pair<T>& x ) { return x.first; } template< class T > inline T range_begin( const Pair<T>& x ) { return x.first; } template< class T > inline T range_end( Pair<T>& x ) { return x.last; } template< class T > inline T range_end( const Pair<T>& x ) { return 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_difference< Foo::Pair<iter> >::type s = boost::size( pair ); s = boost::size( cpair ); boost::range_reverse_iterator< const Foo::Pair<iter> >::type ri = boost::rbegin( cpair ), re = boost::rend( cpair ); } © Copyright Thorsten Ottosen 2008. Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at www.boost.org/LICENSE_1_0.txt) |