Boost.Range

Range and ReversibleRange Implementation

Overview

Five types of objects are currently supported by the library:

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 boost::array<> anyway). Also note that arrays and pointers of char or whar_t are treated special because of their use in string algorithms.

The concept is defined by the metafunction and the functions below. Even though these functions are defined in namespace boost, 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.

Synopsis

namespace boost
{
    //
    // Range metafunctions
    //
    
    template< class T >
    struct value_type_of
    {
        typedef ... type; // type of stored objTts
    };
                 
    template< class T >
    struct iterator_of
    {
        typedef ... type; // iterator over stored objects
    };
    
    template< class T >
    struct const_iterator_of
    {
        typedef ... type; // iterator over immutable stored objects
    };
    
    template< class T >
    struct difference_type_of
    {
        typedef ... type;
        BOOST_STATIC_ASSERT( boost::is_signed< type >::value );
        //
        // remark: if std::iterator_traits<> works for the type, this assertion must
        hold
        //
        BOOST_STATIC_ASSERT( boost::is_same< type, std::iterator_traits< typename
                                                   iterator_of< T >::type >::difference_type>::value );
    };
    
    template< class T >
    struct size_type_of
    {
        typedef ... type;
        BOOST_STATIC_ASSERT( boost::is_unsigned< type >::value );
        BOOST_STATIC_ASSERT( sizeof( type ) >= sizeof( 
        difference_type_of< T >::type ) );
    };
    
    template< class T >
    struct result_iterator_of
    {
        typedef ... type;
        // iterator_of< T >::type if T is non-const, 
        const_iterator_of< T >::type otherwise
    };
                 
    //
    // funtions
    //
    
    template< class T >
    inline typename iterator_of::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 );
               
    template< class T >
    inline typename size_type_of< T >::type
    size( const T& c );
                 
} // namespace 'boost'

Semantics

In the table C is a type that conforms to the ExternalCollectionConcept and c is an object of that type. SC will denote a standard container, T[sz] will denote an array of type T of size sz, P will denote std::pair<>, I means an iterator which default construction denotes the end of the range and sc,t,p,i are objects of these types, respectively. Special cases for char* and wchar_t* are described explicitly.

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

Expression Return type Returns Complexity
begin( c ) result_iterator_of<C>::type sc.begin()
t
p.first
constant time
end( c ) result_iterator_of<C>::type sc.end()
t + std::char_traits<C>::length( t ) if C is char* or wchar_t*
t + sz - 1 if C is char[sz] or wchar_t[sz]
t + sz otherwise
p.second
linear if C is char* or wchar_t*
constant time otherwise
empty( c ) Convertible to bool sc.empty()
size( t ) == 0
p.first == p.second
linear if C is char* or wchar_t*
constant time otherwise
size( c ) size_type_of<C>::type sc.size()
end( t ) - begin( t )
distance( p. first, p.second )
linear if C is char* or wchar_t*
or if std::distance() is linear
constant time otherwise
rbegin( c ) reverse_result_iterator_of<C>::type reverse_result_iterator_of<C>::type( end( c ) )
same as end()
rend( c ) reverse_result_iterator_of<C>::type reverse_result_iterator_of<C>::type( begin( c ) ) same as begin()

Please note that char*,whar_t*,char[], and wchar_t[] behaves differently from normal arrays only for size() and end(). Note that the null pointer is allowed as an argument in these cases.

Examples

Some examples are given in the accompanying test files:

(C) Copyright Thorsten Ottosen 2003-2004