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

Subject: Re: [Boost-users] [range] questions about documentation and usage
From: Oswin Krause (Oswin.Krause_at_[hidden])
Date: 2012-11-02 02:16:37

Hi,

a)
this is the range extension mechanism. By default the usual v.begin() 
and v.end() is allowed and thus  boost::begin(v) is of course a valid 
expression. For classes which don't adhere to the usual convention, you 
have to specialize the templates you found:

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

so boost::begin(v) is more flexible than v.begin() and that's why 
boost::begin is required instead of v.begin. But you re right that it 
should be stated, that this is a valid expression for containers.

b) "The intention of the iterator_range class is to encapsulate two 
iterators so they fulfill the Forward Range concept". First line.

http://www.boost.org/doc/libs/1_51_0/libs/range/doc/html/range/reference/utilities/iterator_range.html

c) The convention is: big libraries get their own namespace, small 
libraries don't need to. Also in this case it is convenient as one can 
replace std::find with boost::find instead of boost::range::find which - 
espcially in conjunction with the adaptors - leads to a lot of noise for 
a simple thing.

On 2012-11-02 07:11, Robert Ramey wrote:
> 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
>
>
>
>
>
> _______________________________________________
> Boost-users mailing list
> Boost-users_at_[hidden]
> http://lists.boost.org/mailman/listinfo.cgi/boost-users