doc/reference/extending.qbk

[/
    Copyright 2010 Neil Groves
    Distributed under the Boost Software License, Version 1.0.
    (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
[section:extending Extending the library]

[section:method_1 Method 1: provide member functions and nested types]

This procedure assumes that you have control over the types that should be made conformant to a Range concept. If not, see [link range.reference.extending.method_2 method 2].

The primary templates in this library are implemented such that standard containers will work automatically and so will __boost_array__. Below is given an overview of which member functions and member types a class must specify to be useable as a certain Range concept.

[table
  [[Member function] [Related concept      ]]
  [[`begin()`      ] [__single_pass_range__]]
  [[`end()`        ] [__single_pass_range__]]
]

Notice that `rbegin()` and `rend()` member functions are not needed even though the container can support bidirectional iteration.

The required member types are:

[table
  [[Member type     ] [Related concept      ]]
  [[`iterator`      ] [__single_pass_range__]]
  [[`const_iterator`] [__single_pass_range__]]
]

Again one should notice that member types `reverse_iterator` and `const_reverse_iterator` are not needed.

[endsect]

[section:method_2 Method 2: provide free-standing functions and specialize metafunctions]

This procedure assumes that you cannot (or do not wish to) change the types that should be made conformant to a Range concept. If this is not true, see [link range.reference.extending.method_1 method 1].

The primary templates in this library are implemented such that certain functions are found via argument-dependent-lookup (ADL). Below is given an overview of which free-standing functions a class must specify to be useable as a certain Range concept. Let `x` be a variable (`const` or `mutable`) of the class in question.

[table
  [[Function              ] [Related concept      ]]
  [[`range_begin(x)`] [__single_pass_range__]]
  [[`range_end(x)`  ] [__single_pass_range__]]
  [[`range_calculate_size(x)`] [ Optional. This can be used to specify a mechanism for constant-time computation of the size of a range. The default behaviour is to return `boost::end(x) - boost::begin(x)` for random access ranges, and to return `x.size()` for ranges with lesser traversal capability. This behaviour can be changed by implementing `range_calculate_size` in a manner that will be found via ADL. The ability to calculate size in O(1) is often possible even with ranges with traversal categories less than random access.]]
]

`range_begin()` and `range_end()` must be overloaded for both `const` and `mutable` reference arguments.

You must also specialize two metafunctions for your type `X`:

[table
  [[Metafunction                 ] [Related concept      ]]
  [[`boost::range_mutable_iterator`] [__single_pass_range__]]
  [[`boost::range_const_iterator`] [__single_pass_range__]]
]

A complete example is given here:

``
    #include <boost/range.hpp>
    #include <iterator>         // for std::iterator_traits, std::distance()

    namespace Foo
    {
        //
        // Our sample UDT. A 'Pair'
        // will work as a range when the stored
        // elements are iterators.
        //
        template< class T >
        struct Pair
        {
            T first, last;
        };

    } // namespace 'Foo'

    namespace boost
    {
        //
        // Specialize metafunctions. We must include the range.hpp header.
        // We must open the 'boost' namespace.
        //

    	template< class T >
    	struct range_mutable_iterator< Foo::Pair<T> >
    	{
    		typedef T type;
    	};

    	template< class T >
    	struct range_const_iterator< Foo::Pair<T> >
    	{
    		//
    		// Remark: this is defined similar to 'range_iterator'
    		//         because the 'Pair' type does not distinguish
    		//         between an iterator and a const_iterator.
    		//
    		typedef T type;
    	};

    } // namespace 'boost'

    namespace Foo
    {
    	//
    	// The required functions. These should be defined in
    	// the same namespace as 'Pair', in this case
    	// in namespace 'Foo'.
    	//

    	template< class T >
    	inline T range_begin( Pair<T>& x )
    	{
    		return x.first;
    	}

    	template< class T >
    	inline T range_begin( const Pair<T>& x )
    	{
    		return x.first;
    	}

    	template< class T >
    	inline T range_end( Pair<T>& x )
    	{
    		return x.last;
    	}

    	template< class T >
    	inline T range_end( const Pair<T>& x )
    	{
    		return x.last;
    	}

    } // namespace 'Foo'

    #include <vector>

    int main(int argc, const char* argv[])
    {
    	typedef std::vector<int>::iterator  iter;
    	std::vector<int>                    vec;
    	Foo::Pair<iter>                     pair = { vec.begin(), vec.end() };
    	const Foo::Pair<iter>&              cpair = pair;
    	//
    	// Notice that we call 'begin' etc with qualification.
    	//
    	iter i = boost::begin( pair );
    	iter e = boost::end( pair );
    	i      = boost::begin( cpair );
    	e      = boost::end( cpair );
    	boost::range_difference< Foo::Pair<iter> >::type s = boost::size( pair );
    	s      = boost::size( cpair );
    	boost::range_reverse_iterator< const Foo::Pair<iter> >::type
    	ri     = boost::rbegin( cpair ),
    	re     = boost::rend( cpair );

    	return 0;
    }
``

[endsect]

[section:method_3 Method 3: provide range adaptor implementations]

[section:method_3_1 Method 3.1: Implement a Range Adaptor without arguments]

To implement a Range Adaptor without arguments (e.g. reversed) you need to:

# Provide a range for your return type, for example:
``
#include <boost/range/iterator_range.hpp>
#include <boost/iterator/reverse_iterator.hpp>

template< typename R >
struct reverse_range :
    boost::iterator_range<
        boost::reverse_iterator<
            typename boost::range_iterator<R>::type> >
{
private:
    typedef boost::iterator_range<
        boost::reverse_iterator<
            typename boost::range_iterator<R>::type> > base;

public:
    typedef boost::reverse_iterator<
        typename boost::range_iterator<R>::type > iterator;

    reverse_range(R& r)
        : base(iterator(boost::end(r)), iterator(boost::begin(r)))
    { }
};
``

# Provide a tag to uniquely identify your adaptor in the `operator|` function overload set
``
namespace detail {
    struct reverse_forwarder {};
}
``

# Implement `operator|`
``
template< class BidirectionalRng >
inline reverse_range<BidirectionalRng>
operator|( BidirectionalRng& r, detail::reverse_forwarder )
{
	return reverse_range<BidirectionalRng>( r );
}

template< class BidirectionalRng >
inline reverse_range<const BidirectionalRng>
operator|( const BidirectionalRng& r, detail::reverse_forwarder )
{
	return reverse_range<const BidirectionalRng>( r );
}
``

# Declare the adaptor itself (it is a variable of the tag type).
``
namespace
{
    const detail::reverse_forwarder reversed = detail::reverse_forwarder();
}
``

[endsect]

[section:method_3_2 Method 3.2: Implement a Range Adaptor with arguments]

# Provide a range for your return type, for example:
``
#include <boost/range/adaptor/argument_fwd.hpp>
#include <boost/range/iterator_range.hpp>
#include <boost/iterator/transform_iterator.hpp>

template<typename Value>
class replace_value
{
public:
    typedef const Value& result_type;
    typedef const Value& argument_type;

    replace_value(const Value& from, const Value& to)
        : m_from(from), m_to(to)
    {
    }

    const Value& operator()(const Value& x) const
    {
        return (x == m_from) ? m_to : x;
    }
private:
    Value m_from;
    Value m_to;
};

template<typename Range>
class replace_range
: public boost::iterator_range<
    boost::transform_iterator<
        replace_value<typename boost::range_value<Range>::type>,
        typename boost::range_iterator<Range>::type> >
{
private:
    typedef typename boost::range_value<Range>::type value_type;
    typedef typename boost::range_iterator<Range>::type iterator_base;
    typedef replace_value<value_type> Fn;
    typedef boost::transform_iterator<Fn, iterator_base> replaced_iterator;
    typedef boost::iterator_range<replaced_iterator> base_t;

public:
    replace_range(Range& rng, value_type from, value_type to)
        : base_t(replaced_iterator(boost::begin(rng), Fn(from,to)),
                 replaced_iterator(boost::end(rng), Fn(from,to)))
     {
     }
 };
``

# Implement a holder class to hold the arguments required to construct the RangeAdaptor.
The holder combines multiple parameters into one that can be passed as the right operand of `operator|()`.
``
template<typename T>
class replace_holder : public boost::range_detail::holder2<T>
{
public:
    replace_holder(const T& from, const T& to)
        : boost::range_detail::holder2<T>(from, to)
    { }
private:
    void operator=(const replace_holder&);
};
``

# Define an instance of the holder with the name of the adaptor
``
static boost::range_detail::forwarder2<replace_holder>
replaced = boost::range_detail::forwarder2<replace_holder>();
``

# Define `operator|`
``
template<typename SinglePassRange>
inline replace_range<SinglePassRange>
operator|(SinglePassRange& rng,
          const replace_holder<typename boost::range_value<SinglePassRange>::type>& f)
{
    return replace_range<SinglePassRange>(rng, f.val1, f.val2);
}

template<typename SinglePassRange>
inline replace_range<const SinglePassRange>
operator|(const SinglePassRange& rng,
          const replace_holder<typename boost::range_value<SinglePassRange>::type>& f)
{
    return replace_range<const SinglePassRange>(rng, f.val1, f.val2);
}
``

[endsect]

[endsect]

[endsect]