Re: [Boost-users] [range] questions about documentation and usage

Subject: Re: [Boost-users] [range] questions about documentation and usage
From: Nathan Ridge (zeratul976_at_[hidden])
Date: 2012-11-02 02:15:23

> a) I see examples like
> 
> std::vector<T> v;
> boost::range::find(v, 0);
> 
> find(SinglePassRange& rng, Value val);
> 
> BUT  when looking at the documentation at
> http://www.boost.org/doc/libs/1_51_0/libs/range/doc/html/range/concepts/single_pass_range.html
> I see only two valid expressions
> 
> boost::begin(a)
> boost::end(a)
> 
> where in this case a would be v which is of type std::vector<int>.  BUT
> 
> boost:begin(v) is NOT a valid expression for the above.
> 
> Spelunking into the range header code reveals the following:
> 
> template< class T >
> inline BOOST_DEDUCED_TYPENAME range_iterator<T>::type begin( T& r )
> {
> #if !BOOST_WORKAROUND(__BORLANDC__, BOOST_TESTED_AT(0x564)) && \
> !BOOST_WORKAROUND(__GNUC__, < 3) \
> /**/
> using namespace range_detail;
> #endif
> return range_begin( r );
> }
> 
> 
> and
> 
> 
> template< typename C >
> inline BOOST_DEDUCED_TYPENAME range_iterator<C>::type
> range_begin( C& c )
> {
> //
> // If you get a compile-error here, it is most likely because
> // you have not implemented range_begin() properly in
> // the namespace of C
> //
> return c.begin();
> }
> 
> This effectively means that the "Valid Expressions" for SinglePassRange part 
> of the documenation should read:
> 
> a.begin()
> a.end()
> 
> Doesn't it.  I would be interested to know if I got this wrong.

Nope. 

Suppose I have a third-party library with a class named Vector
which has methods named Begin() and End() rather than begin() and
end(). I can't change Vector, but I'd still like to use it as a
SinglePassRange. Boost.Range allows me to do that, by overloading
range_begin() and range_end() in the namespace of Vector (so that
boost::begin() and boost::end() finds them by ADL) as described in [1].

namespace namespace_of_Vector
{
    Vector::Iterator range_begin(Vector& v) { return v.Begin(); }
    Vector::Iterator range_end(Vector& v) { return v.End(); }
    // overloads for const Vector&
}

Now if v is of type Vector, boost::begin(v) and boost::end(v) will be
valid expressions, but v.begin() and v.end() will not.

So this extra layer allows us to adapt third-party types that we have
no control over to model Boost.Range concepts such as SinglePassRange.

For this design to work, consumers of the SinglePassRange concept
must obey the interface of the concept and only use boost::begin(),
not the begin() member function, on models of SinglePassRange.

> b) I see the template iterator_range<ForwardTraversalIterator> -
> 
> which seem to be to in an instance of what the ForwardRangeConcept should 
> be.

I'm not sure I understand what the question/problem here is.
Could you elaborate?

> c) Another really annoying thing is that every thing is directly in the 
> boost namespace.  This breaks the convention that library headers are in 
> boost/<library name> and in the namespace boost::<library name>.  This 
> creates a lot of opportunity for conflict.

Agreed.

Regards,
Nate

[1] http://www.boost.org/doc/libs/1_51_0/libs/range/doc/html/range/reference/extending/method_2.html