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.

ExternalCollectionConcept

The concept is defined by the type-generators 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
    {
        //
        // type generators
        //
        
        template< typename EC >
        struct value_type_of
        {
            typedef ... type; // type of stored objects
        };
                     
        template< typename EC >
        struct iterator_of
        {
            typedef ... type; // iterator over stored objects
        };
        
        template< typename EC >
        struct const_iterator_of
        {
            typedef ... type; // iterator over immutable stored objects
        };

        template< typename EC >
        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< EC >::type >::difference_type>::value );
        };

        template< typename EC >
        struct size_type_of
        {
            typedef ... type;
            BOOST_STATIC_ASSERT( boost::is_unsigned< type >::value );
            BOOST_STATIC_ASSERT( sizeof( type ) >= sizeof( 
            difference_type_of< EC >::type ) );
        };

        template< typename EC >
        struct result_iterator_of
        {
            typedef ... type;
            // iterator_of< EC >::type if EC is non-const, 
            const_iterator_of< EC >::type otherwise
        };
                     
        //
        // funtions
        //
        
        template< typename EC >
        inline typename iterator_of::type
        begin( EC& c );
    
        template< typename EC >
        inline typename const_iterator_of< EC >::type
        begin( const EC& c );
            
        template< typename EC >
        inline typename iterator_of< EC >::type
        end( EC& c );
                          
        template< typename EC >
        inline typename const_iterator_of< EC >::type
        end( const EC& c );
        
        template< typename EC >
        inline bool
        empty( const EC& c );
                   
        template< typename EC >
        inline typename size_type_of< EC >::type
        size( const EC& 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