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

Subject: [Boost-users] [range] questions about documentation and usage
From: Robert Ramey (ramey_at_[hidden])
Date: 2012-11-02 02:11:59

I want to use Boost.Range in a bigger way.  But I have a few problems with 
it. I think most of them are just issues of understanding and the writting 
of the documentation

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.

b) I see the template iterator_range<ForwardTraversalIterator> -

which seem to be to in an instance of what the ForwardRangeConcept should 
be.

To me, the range documentation is out of whack.  I can figure it out - but 
it's misleading  - atleast to me.

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.

Robert Ramey