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

Subject: Re: [Boost-users] [range] questions about documentation and usage
From: Robert Ramey (ramey_at_[hidden])
Date: 2012-11-03 19:20:19

Nathan Crookston wrote:
> On Fri, Nov 2, 2012 at 11:20 AM, Robert Ramey <ramey_at_[hidden]> wrote:

>> The page
>> http://www.boost.org/doc/libs/1_51_0/libs/range/doc/html/range/concepts/single_pass_range.html
>> is crystal clear.  It says that any SinglePassRange must implement
>> the expression boost::begin(a) where a is a model of a
>> SinglePassRange.
>>
> On the page you reference, it describes that a particular expression
> must be valid for types modeling the SinglePassRange concept.  It
> doesn't claim that you must implement it.

> I admit that it's a fine distinction.  I thought that the "See Also"
> section on that same page was helpful, however -- the link titled
> "Extending the library for UDTs" seems to provide the information
> you're looking for.

OK - I see you're point here. And I'll even agree with it.
The requirement that boost::begin(a) can be specified as part of
the concept of the type of a.  But from a practical standpoint
this causes a lot of problems.  I have a type std::vector<int>.
Apparently the authors of Boost.Range have inmplemented
boost::begin<std::vector<int> > somewhere.  But how can I
possible know this? And if this is defined - what header do
I have to include to get it? or what.  Basically, whether or
not boost::range<T> is going to function is dependent upon
information not readily available to the reader - hence the need
to spelunk through the code to find stuff and figure it out.

A plain reading of the documentation will lead one to expect
that the following should compile:

class my_class {};
namespace boost {
  int * begin(my_class & b);
  int * end(my_class & e);
} // namespace boost
void test3(){
  my_class x;
  boost::begin(x);
  boost::end(x);
  BOOST_CONCEPT_ASSERT((boost::SinglePassRangeConcept<my_class>)); // error 
(1)
  boost::find(x, 0); // error (2)
}

when in fact it does not. There is no way that both the documentation
and the implementation of constant checking can be correct. This is
illustrated by error(1).

error(2) doesn't not fail within a concept definition.  In other words, the
library fails to use it's own concepts to check the types of parameters
passed to its own templates.  The chief benefit is usage of concepts
is to help users passing the wrong types to template functions and
classes.  This is apparently not done in this library.

Robert Ramey