Boost.Range utility classes

Having an abstraction that encapsulates a pair of iterators is very useful. The standard library uses std::pair in some cercumstances, but that class is cumbersome to use because we need to specify two template arguments, and for all range algorithm purposes, we must enforce the two template arguments to be the same. Moreover, std::pair<iterator,iterator> is hardly self-documenting whereas more domain specific class names are. Therefore these two classes are provided:

The iterator_range class is templated on an iterator and should be used whenever super general code is needed. The sub_range class is templated on an ExternalRange and it is less general, but a bit easier to use since its template argument is easier to specify.

Class iterator_range

The intention of the iterator_range class is to encapsulate two iterators so they fulfill the Range concept. A few other functions are also provided for convinience.

Synopsis

namespace boost
{
    template< class Iterator > 
    class iterator_range
    {
        iterator_range(); // not implemented
        
    public: // Range types
        typedef ...        value_type;
        typedef ...        difference_type;
        typedef ...        size_type;
        typedef Iterator   iterator;        
        typedef Iterator   const_iterator;

    public: // construction, assignment
        template< class Iterator >
        iterator_range( Iterator Begin, Iterator End );
                    
        template< class XRange >
        iterator_range( XRange& r ); 
  
        template< class XRange >
        iterator_range( const XRange& r ); 
        
        template< class XRange >
        iterator_range& operator=( XRange& r );

        template< class XRange >
        iterator_range& operator=( const XRange& r );
    
    public: // Range functions
        iterator  begin() const; 
        iterator  end() const; 
        size_type size() const;
        bool      empty() const;
        
    public: // convenience
        operator  unspecified_bool_type() const;
        void      swap( iterator_range& r );
    };
    
    // stream output
    template< class Iterator, class T, class Traits >
    std::basic_ostream<T,Traits>& operator<<( std::basic_ostream<T,Traits>& Os,
                                              const iterator_range<Iterator>& r );

    // comparison
    template< class Iterator > 
    bool operator==( const iterator_range<Iterator>& l, const iterator_range<Iterator>& r );
    
    template< class Iterator > 
    bool operator!=( const iterator_range<Iterator>& l, const iterator_range<Iterator>& r );

    // external construction
    template< class Iterator >
    iterator_range< Iterator > 
    make_iterator_range( Iterator Begin, Iterator End ); 
       
    template< class XRange >
    iterator_range< typename iterator_of<XRange>::type >
    make_iterator_range( XRange& r ); 

    template< class XRange >
    iterator_range< typename const_iterator_of<XRange>::type >
    make_iterator_range( const XRange& r ); 

    // convenience
    template< class Sequence, class XRange >
    Sequence copy_range( const XRange& r )

    template< class Sequence, class XRange, class Func >
    Sequence transform_range( const XRange& r, Func func );

} // namespace 'boost'

It is worth noticing that the templated constructors and assignment operators allow conversion from iterator_range to iterator_range. If an instance of iterator_range is constructed by a client with two iterators, the client must ensure that the two iterators delimit a valid closed-open range [begin,end).

Class sub_range

The sub_range class inherits all its functionality from the iterator_range class. The sub_range class is often easier to use because one must specify the ExternalRange template argument instead of an iterator.

Synopsis

namespace boost
{
    
    template< class XRange > 
    class sub_range : public iterator_range< typename result_iterator_of<XRange>::type > 
    {
    public: // construction, assignment
        template< class Iterator >
        sub_range( Iterator Begin, Iterator End );

        template< class XRange2 >
        sub_range( XRange2& r );
         
        template< class XRange2 >
        sub_range( const Range2& r );
         
        template< class XRange2 >
        sub_range& operator=( XRange2& r );

        template< class XRange2 >
        sub_range& operator=( const XRange2& r );
        
    public:
        // rest of interface inherited from iterator_range
    };
    
} // namespace 'boost'

(C) Copyright Thorsten Ottosen 2003-2004