24.6.1 Range operations

The functions range_begin() and range_end() are intended to be overloaded for a user-defined type T in the namespace of T.

The functions begin() and end() are intended to be called qualified with the std namespace, and they are always called qualified within the standard library. From these two functions the call to range_begin() and range_end(), respectively, is without namespace qualification to enable argument dependent lookup.

template< class Range > auto range_begin( Range&& r ) -> decltype( r.begin() );

• Returns: r.begin()

template< class Iterator > Iterator range_begin( const pair<Iterator,Iterator>& p );

• Returns: p.first

template< class T, size_t N > T* range_begin( T (&array)[N] )

• Returns: array

template< class Range > auto begin( Range&& r ) -> decltype( range_begin(r) );

• Returns: range_begin(r)

template< class Range > auto range_end( Range&& r ) -> decltype( r.end() );

• Returns: r.end()

template< class Iterator > Iterator range_end( const pair<Iterator,Iterator>& p );

• Returns: p.second

template< class T, size_t N > T* range_end( T (&array)[N] );

• Returns: array + N

template< class Range > auto end( Range&& r ) -> decltype( range_end(r) );

• Returns: range_end(r)

template< class RandomAccessRange > typename range_difference<RandomAccessRange>::type size( const RandomAccessRange& r );

• Returns: std::end(r) - std::begin(r)

template< class BidirectionalRange > typename range_reverse_iterator<BidirectionalRange>::type rbegin( BidirectionalRange&& r );

• Returns: typename range_reverse_iterator<BidirectionalRange>::type(std::end(r))

template< class BidirectionalRange > typename range_reverse_iterator<BidirectionalRange>::type rend( BidirectionalRange&& r );

• Returns: typename range_reverse_iterator<BidirectionalRange>::type(std::begin(r))

template< class Range > typename range_iterator<const Range>::type const_begin( const Range& r );

• Returns: std::begin(r)

template< class Range > typename range_iterator<const Range>::type const_end( const Range& r );

• Returns: std::end(r)

template< class BidirectionalRange > typename range_reverse_iterator<const BidirectionalRange>::type const_rbegin( const BidirectionalRange& r );

• Returns: std::rbegin(r)

template< class BidirectionalRange > typename range_reverse_iterator<const BidirectionalRange>::type const_rend( const BidirectionalRange& r );

• Returns: std::rend(r)

24.6.2 Range traits

For convenience the type and properties of an associated iterator type of a range can be queried by range traits. Each trait is a TransformationTrait and so define a nested type called type.

template< class Range > struct range_iterator;

• Definition of type: Let ptr be a variable of type Range*, then the nested type is typedef decltype( begin(*ptr) ) type;

template< class BidirectionalRange > struct range_reverse_iterator;

• Definition of type: typedef reverse_iterator< typename range_iterator<BidirectionalRange>:type > type;

template< class Range > struct range_value;

• Definition of type: typedef typename iterator_traits< typename range_iterator<Range>::type >::value_type type;

template< class Range > struct range_reference;

• Definition of type: typedef typename iterator_traits< typename range_iterator<Range>::type >::reference type;

template< class Range > struct range_pointer;

• Definition of type: typedef typename iterator_traits< typename range_iterator<Range>::type >::pointer type;

template< class Range > struct range_difference;

• Definition of type: typedef typename iterator_traits< typename range_iterator<Range>::type >::difference_type type;

template< class Range > struct range_category;

• Definition of type: typedef typename iterator_traits< typename range_iterator<Range>::type >::iterator_category type;

24.6.3 Range utilities

For convenience the library provides two iterator-view helper classes. These two classes make comparison between view-objects and container-objects easy and provide a safer and more convenient encapsulation of iterator-views.

namespace std
{
        template< class Iterator >
        class range
        {
        public: // types
                typedef typename iterator_traits<Iterator>::value_type       value_type;
                typedef typename iterator_traits<Iterator>::reference        reference;
                typedef typename iterator_traits<Iterator>::difference_type  difference_type;
                typedef Iterator                                             iterator;
                typedef Iterator                                             const_iterator;
        
        public: // construction, assignment
                range();
                
                template< class Iterator2 >
                range( const Iterator2& begin, const Iterator2& end );
                        
                template< class Range >
                range( Range&& r );
        
                template< class Range >
                range& operator=( Range&& r );
        
        public: // forward range functions
                iterator        begin() const;
                iterator        end() const;
                difference_type size() const;
                bool            empty() const;
                
        public: // convenience
                operator    unspecified_bool_type() const;
                bool        equal( const range& ) const;
                reference   front() const;
                reference   back() const;
                reference   operator[]( difference_type at ) const;
                range&      advance_begin( difference_type n );
                range&      advance_end( difference_type n );
        
        private:
                Iterator first; // exposition only
                Iterator last;  // exposition only    
        }; 

        template< class Range >
        class sub_range : public range< typename range_iterator<Range>::type >
        {
        public: 
                typedef range< typename range_iterator<Range>::type >        base_type
                typedef typename range_iterator<Range>::type                 iterator;
                typedef typename range_iterator<const Range>::type           const_iterator;
                typedef typename iterator_traits<const_iterator>::reference  const_reference;
                using base_type::value_type;
                using base_type::reference;
                using base_type::difference_type;
                
        public: // construction, assignment
                sub_range();
                
                template< class Iterator >
                sub_range( const Iterator& begin, const Iterator& end );
                
                template< class Range2 >
                sub_range( Range2&& r );
                 
                template< class Range2 >
                sub_range& operator=( Range2&& r );
                
        public:  // forward range functions 
                iterator        begin();
                const_iterator  begin() const;
                iterator        end();
                const_iterator  end() const;    
                
        public: // convenience 
                reference        front();
                const_reference  front() const;
                reference        back();
                const_reference  back() const;
                reference        operator[]( difference_type at );
                const_reference  operator[]( difference_type at ) const;   
                sub_range&       advance_begin( difference_type n );
                sub_range&       advance_end( difference_type n );
        };
}

[Example: An efficient way to find and manipulate a substring may be done with sub_range:

string s = ...;
sub_range<string> sub = find( s, ... );
if( sub == string("foo") )
{ 
   sub[0] = 'b'; 
   assert( sub == string("boo") );
}

-- end example]

range();

• Effects: Initializes its members as if implemented by: range() : first(), last() {}
• Remarks: The stored iterators are singular.

template< class Iterator2 > range( const Iterator2& begin, const Iterator2& end );

• Effects: Initializes first with begin and last with end.

template< class Range > range( Range&& r );

• Effects: Initializes first with std::begin(r) and last with std::end(r).

template< class Range > range& operator=( Range&& r );

• Effects: assigns std::begin(r) to first and std::end(r) to last.
• Returns: *this

iterator begin() const;

• Returns: first.

iterator end() const;

• Returns: last.

difference_type size() const;

• Returns: end() - begin();

bool empty() const;

• Returns: begin() == end();

operator unspecified_bool_type() const;

• Returns: a value convertible to bool indicating whether empty() is true.

bool equal( const range& ) const;

• Returns: begin() == r.begin() && end() == r.end().

reference front() const;

• Returns: *begin().

reference back() const;

• Returns: *--end().

reference operator[]( difference_type at ) const;

• Precondition: 0 <= at < size().
• Returns: *(begin() + at).

range& advance_begin( difference_type n );

• Effects: std::advance(first,n).
• Returns: *this

range& advance_end( difference_type n );

• Effects: std::advance(last,n).
• Returns: *this

sub_range();

template< class Iterator > sub_range( const Iterator& begin, const Iterator& end );

template< class Range2 > sub_range( Range2&& r );

• Effects: Calls corresponding base class constructor.

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

• Effects: base_type::operator=(r);
• Returns: *this

iterator begin();

• Returns: base_type::begin();

const_iterator begin() const;

• Returns: base_type::begin();

iterator end();

• Returns: base_type::end();

const_iterator end() const;

• Returns: base_type::end();

reference front();

• Returns: base_type::front();

const_reference front() const;

• Returns: base_type::front();

reference back();

• Returns: base_type::back();

const_reference back() const;

• Returns: base_type::back();

reference operator[]( difference_type at );

• Returns: base_type::operator[](at);

const_reference operator[]( difference_type at ) const;

• Returns: base_type::operator[](at);

sub_range& advance_begin( difference_type n );

• Effects: base_type::advance_begin(n);
• Returns: *this

sub_range& advance_end( difference_type n );

• Effects: base_type::advance_end(n);
• Returns: *this

template< class Iterator, class T, class Traits > std::basic_ostream<T,Traits>& operator<<( std::basic_ostream<T,Traits>& Os, const range<Iterator>& r );

• Effects: std::copy( r.begin(), r.end(), std::ostream_iterator< typename iterator_traits<Iterator>::value_type,T,Traits>(os)); return Os;.

template< class Iterator, class Iterator2 > bool operator==( const range<Iterator>& l, const range<Iterator2>& r );

template< class Iterator, class Range > bool operator==( const range<Iterator>& l, const Range& r );

template< class Iterator, class Range > bool operator==( const Range& l, const range<Iterator>& r );

• Returns: std::equal( std::begin(l), std::end(l), std::begin(r) );.
• Remarks: For random access ranges the function compares the size of the ranges first via std::size().

template< class Iterator, class Iterator2 > bool operator!=( const range<Iterator>& l, const range<Iterator2>& r );

template< class Iterator, class Range > bool operator!=( const range<Iterator>& l, const Range& r );

template< class Iterator, class Range > bool operator!=( const Range& l, const range<Iterator>& r );

• Returns: !( l == r ).

template< class Iterator, class Iterator2 > bool operator<( const range<Iterator>& l, const range<Iterator2>& r );

template< class Iterator, class Range > bool operator<( const range<Iterator>& l, const Range& r );

template< class Iterator, class Range > bool operator<( const Range& l, const range<Iterator>& r );

• Returns: std::lexicographical_compare(std::begin(l),std::end(l),std::begin(r), std::end(r)).

template< class Range, class Range2 > bool operator==( const sub_range<Range>& l, const sub_range<Range2>& r );

template< class Range, class Range2 > bool operator!=( const sub_range<Range>& l, const sub_range<Range2>& r )

template< class Range, class Range2 > bool operator<( const sub_range<Range>& l, const sub_range<Range2>& r );

• Effects: forwards to range version via static casts to a reference to the base class
• Remarks: these functions are needed to avoid ambiguity during overload resolution.

template< class Iterator > range<Iterator> make_range( const Iterator& begin, const Iterator& end );

• Returns: range<Iterator>(begin,end).

template< class Range > range<typename range_iterator<Range>::type> make_range( Range&& r );

• Returns: range<typename range_iterator<Range>::type>(r).

template< class Range > range<typename range_iterator<Range>::type> make_range( Range&& r, typename range_difference<Range>::type N, typename range_difference<Range>::type M );

• Effects: range<typename range_iterator<Range>::type> tmp(r); tmp.advance_begin(N); tmp.advance_end(M); return tmp;

template< class CopyableRange, class Range > CopyableRange copy_range( const Range& r );

• Returns: CopyableRange(std::begin(r),std::end(r)).

template< class ForwardRange > typename range_difference<ForwardRange>::type distance( const ForwardRange& r );

• Returns: std::distance(std::begin(r),std::end(r))