boost_range.qbk

Boost provides free peer-reviewed portable C++ source libraries. We emphasize libraries that work

[h4 See also]

__implementation_of_metafunctions__

__implementation_of_functions__

[endsect]


[section Random Access Range]

[h4 Description]

A range `X` where `boost::range_iterator<X>::type` is a model of __random_access_traversal_iterator__.

[h4 Refinement of]

__bidirectional_range__

[endsect]


[section Concept Checking]

Each of the range concepts has a corresponding concept checking class in the file [@../../boost/range/concepts.hpp `boost/range/concepts.hpp`]. These classes may be used in conjunction with the __concept_check__ to insure that the type of a template parameter is compatible with a range concept. If not, a meaningful compile time error is generated. Checks are provided for the range concepts related to iterator traversal categories. For example, the following line checks that the type `T` models the __forward_range__ concept.

``
function_requires<ForwardRangeConcept<T> >();
``
    
An additional concept check is required for the value access property of the range based on the range's iterator type. For example to check for a ForwardReadableRange, the following code is required.

``
function_requires<ForwardRangeConcept<T> >();
    function_requires<
        ReadableIteratorConcept<
            typename range_iterator<T>::type
        >
    >();
``    

The following range concept checking classes are provided.

* Class SinglePassRangeConcept checks for __single_pass_range__
* Class ForwardRangeConcept checks for __forward_range__
* Class BidirectionalRangeConcept checks for __bidirectional_range__
* Class RandomAccessRangeConcept checks for __random_access_range__

[h4 See also]

[link boost.range.style_guide Range Terminology and style guidelines]

__iterator_concepts__

__concept_check__

[endsect] 

[endsect]



[section Reference]

[section Overview]

Four types of objects are currently supported by the library:

* standard-like containers
* `std::pair<iterator,iterator>`
* null terminated strings (this includes `char[]`,`wchar_t[]`, `char*`, and `wchar_t*`)

[:[*Warning: ['support for null-terminated strings is deprecated and will disappear in the next Boost release (1.34).]]]

* built-in arrays

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.

[endsect]


[section Synopsis]

``
namespace boost
{
    //
    // Single Pass Range metafunctions
    //

    template< class T >
    struct range_value;

    template< class T >
    struct range_iterator;

    template< class T >
    struct range_const_iterator;

    //
    // Forward Range metafunctions
    //

    template< class T >
    struct range_difference;

    template< class T >
    struct range_size;

    //
    // Bidirectional Range metafunctions
    //

    template< class T >
    struct range_reverse_iterator;

    template< class T >
    struct range_const_reverse_iterator;

    //
    // Special metafunctions
    //

    template< class T >
    struct range_result_iterator;

    template< class T >
    struct range_reverse_result_iterator;

    //
    // Single Pass Range functions
    //

    template< class T >
    typename range_iterator<T>::type
    begin( T& c );

    template< class T >
    typename range_const_iterator<T>::type
    begin( const T& c );

    template< class T >
    typename range_iterator<T>::type
    end( T& c );

    template< class T >
    typename range_const_iterator<T>::type
    end( const T& c );

    template< class T >
    bool
    empty( const T& c );

    //
    // Forward Range functions
    //

    template< class T >
    typename range_size<T>::type
    size( const T& c );

    //
    // Bidirectional Range functions
    //

    template< class T >
    typename range_reverse_iterator<T>::type
    rbegin( T& c );

    template< class T >
    typename range_const_reverse_iterator<T>::type
    rbegin( const T& c );

    template< class T >
    typename range_reverse_iterator<T>::type
    rend( T& c );

    template< class T >
    typename range_const_reverse_iterator<T>::type
    rend( const T& c );

    //
    // Special const Range functions
    //

    template< class T >
    typename range_const_iterator<T>::type 
    const_begin( const T& r );

    template< class T >
    typename range_const_iterator<T>::type 
    const_end( const T& r );

    template< class T >
    typename range_const_reverse_iterator<T>::type 
    const_rbegin( const T& r );

    template< class T >
    typename range_const_reverse_iterator<T>::type 
    const_rend( const T& r );

} // namespace 'boost' 
``

[endsect]


[section Semantics]

[h5 notation]

[table
  [[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.

[section Metafunctions]

[table
  [[Expression] [Return type] [Complexity]]
  [[`range_value<X>::type`] [`T::value_type`[br]
`boost::iterator_value<P::first_type>::type`[br]
`A`[br]
`Char`] [compile time]]
  [[`range_iterator<X>::type`] [`T::iterator`[br]
`P::first_type`[br]
`A*`[br]
`Char*`] [compile time]]
  [[`range_const_iterator<X>::type`] [`T::const_iterator`[br]
`P::first_type`[br]
`const A*`[br]
`const Char*`] [compile time]]
  [[`range_difference<X>::type`] [`T::difference_type`[br]
`boost::iterator_difference<P::first_type>::type`[br]
`std::ptrdiff_t`[br]
`std::ptrdiff_t`] [compile time]]
  [[`range_size<X>::type`] [`T::size_type`[br]
`std::size_t`[br]
`std::size_t`[br]
`std::size_t`] [compile time]]
  [[`range_result_iterator<X>::type`] [`range_const_iterator<X>::type` if `X` is `const`[br]
`range_iterator<X>::type` otherwise] [compile time]]
  [[`range_reverse_iterator<X>::type`] [`boost::reverse_iterator< typename range_iterator<T>::type >`] [compile time]]
  [[`range_const_reverse_iterator<X>::type`] [`boost::reverse_iterator< typename range_const_iterator<T>::type >`] [compile time]]
  [[`range_reverse_result_iterator<X>::type`] [`boost::reverse_iterator< typename range_result_iterator<T>::type >`] [compile time]]
]

The special metafunctions `range_result_iterator` and `range_reverse_result_iterator` 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.

[endsect]

[section Functions]

[table
  [[Expression] [Return type] [Returns] [Complexity]]

  [[`begin(x)`] [`range_result_iterator<X>::type`] [`p.first` if `p` is of type `std::pair<T>`[br]
`a` if `a` is an array[br]
`s` if `s` is a string literal[br]
`boost_range_begin(x)` if that expression would invoke a function found by ADL[br]
`t.begin()` otherwise] [constant time]]

  [[`end(x)`] [`range_result_iterator<X>::type`] [`p.second` if `p` is of type `std::pair<T>`[br]
`a + sz` if `a` is an array of size `sz`[br]
`s + std::char_traits<X>::length( s )` if `s` is a `Char*`[br]
`s + sz - 1` if `s` is a string literal of size `sz`[br]
`boost_range_end(x)` if that expression would invoke a function found by ADL[br]
`t.end()` otherwise] [linear if `X` is `Char*`
constant time otherwise]]

  [[`empty(x)`] [`bool`] [`begin(x) == end( x )`] [linear if `X` is `Char*`[br]
constant time otherwise]]

  [[`size(x)`] [`range_size<X>::type`] [`std::distance(p.first,p.second)` if `p` is of type `std::pair<T>`[br]
`sz` if `a` is an array of size `sz`[br]
`end(s) - s` if `s` is a string literal or a `Char*`[br]
`boost_range_size(x)` if that expression would invoke a function found by ADL[br]
`t.size()` otherwise] [linear if `X` is `Char*` or if `std::distance()` is linear[br]
constant time otherwise]]

  [[`rbegin(x)`] [`range_reverse_result_iterator<X>::type`] [`range_reverse_result_iterator<X>::type( end(x) )`] [same as `end(x)`]]

  [[`rend(x)`] [`range_reverse_result_iterator<X>::type`] [`range_reverse_result_iterator<X>::type( begin(x) )`] [same as `begin(x)`]]

  [[`const_begin(x)`] [`range_const_iterator<X>::type`] [`range_const_iterator<X>::type( begin(x) )`] [same as `begin(x)`]]

  [[`const_end(x)`] [`range_const_iterator<X>::type`] [`range_const_iterator<X>::type( end(x) )`] [same as `end(x)`]]

  [[`const_rbegin(x)`] [`range_const_reverse_iterator<X>::type`] [`range_const_reverse_iterator<X>::type( rbegin(x) )`] [same as `rbegin(x)`]]

  [[`const_rend(x)`] [`range_const_reverse_iterator<X>::type`] [`range_const_reverse_iterator<X>::type( rend(x) )`] [same as `rend(x)`]]
]

The special const functions are not part of any Range concept, but are very useful when you want to document clearly that your code is read-only.

[endsect]

[endsect]

[section:extending Extending the library]