Boost.Range

Single Pass Range, Forward Range and Bidirectional Range Implementation

Overview

Four types of objects are currently supported by the library:

Even though the behavior of the primary templates are exactly such that standard containers will be supported by default, the requirements are much lower than the standard container requirements. For example, the utility class 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 value_type_of;
                 
    template< class T >
    struct iterator_of;
    
    template< class T >
    struct const_iterator_of;
    
    //
    // Forward Range metafunctions
    //
    
    template< class T >
    struct difference_type_of;
    
    template< class T >
    struct size_type_of;
    
    //
    // Bidirectional Range metafunctions
    //
    
    template< class T >
    struct reverse_iterator_of;

    template< class T >
    struct const_reverse_iterator_of;
    
    //
    // Special metafunctions
    //
    
    template< class T >
    struct result_iterator_of;
                 
    template< class T >
    struct reverse_result_iterator_of;

    //
    // Single Pass Range functions
    //
    
    template< class T >
    inline typename iterator_of<T>::type
    begin( T& c );
    
    template< class T >
    inline typename const_iterator_of<T>::type
    begin( const T& c );
        
    template< class T >
    inline typename iterator_of<T>::type
    end( T& c );
                      
    template< class T >
    inline typename const_iterator_of<T>::type
    end( const T& c );
    
    template< class T >
    inline bool
    empty( const T& c );
               
    //
    // Forward Range functions
    //
    
    template< class T >
    inline typename size_type_of<T>::type
    size( const T& c );
                            
    //
    // Bidirectional Range functions
    //
                     
    template< class T >
    inline typename reverse_iterator_of<T>::type
    rbegin( T& c );
    
    template< class T >
    inline typename const_reverse_iterator_of<T>::type
    rbegin( const T& c );
        
    template< class T >
    inline typename reverse_iterator_of<T>::type
    rend( T& c );
                      
    template< class T >
    inline typename const_reverse_iterator_of<T>::type
    rend( const T& c );
    
} // namespace 'boost'

Semantics

notation

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.

Metafunctions

Expression Return type Complexity
value_type_of<X>::type T::value_type
boost::iterator_value<P::first_type>::type
A
Char 		compile time
iterator_of<X>::type T::iterator
P::first_type
A*
Char* 		compile time
const_iterator_of<X>::type T::const_iterator
P::first_type
const A*
const Char* 		compile time
difference_type_of<X>::type T::difference_type
boost_iterator_difference<P::first_type>::type
std::ptrdiff_t
std::ptrdiff_t
compile time
size_type_of<X>::type T::size_type
std::size_t
std::size_t
std::size_t
compile time
result_iterator_of<X>::type const_iterator_of<X>::type if X is const
iterator_of<X>::type otherwise 		compile time
reverse_iterator_of<X>::type boost::reverse_iterator< typename iterator_of<T>::type >
compile time
const_reverse_iterator_of<X>::type boost::reverse_iterator< typename const_iterator_of<T>::type >
compile time
reverse_result_iterator_of<X>::type boost::reverse_iterator< typename result_iterator_of<T>::type > compile time

The special metafunctions result_iterator_of and reverse_result_iterator_of 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.

Functions

Expression Return type Returns Complexity
begin(x) result_iterator_of<X>::type t.begin()
p.first
a
s 		constant time
end(x) result_iterator_of<X>::type t.end()
p.second
a + sz
s + std::char_traits<X>::length( s ) if X is Char*
s + sz - 1 if X is Char[sz]
linear if X is Char*
constant time otherwise
empty(x) bool begin(x) == end( x )
linear if X is Char*
constant time otherwise
size(x) size_type_of<X>::type t.size()
std::distance(p.first,p.second)
sz
end(s) - s 		linear if X is Char*
or if std::distance() is linear
constant time otherwise
rbegin(x) reverse_result_iterator_of<X>::type reverse_result_iterator_of<X>::type( end(x) )
same as end(x)
rend(x) reverse_result_iterator_of<X>::type reverse_result_iterator_of<X>::type( begin(x) ) same as begin(x)

(C) Copyright Thorsten Ottosen 2003-2004