My concern is very simple:
The page http://www.boost.org/doc/libs/1_51_0/libs/range/doc/html/range/concepts/sing... is crystal clear. It says that any SinglePassRange must implement the expression boost::begin(a) where a is a model of a SinglePassRange.
This is not actually a requirement on any model of a SinglePassRange but rather a requirement on boost::begin. But boost::begin is not supplied by the user! This documentation doesn't tell me what operation the type argument has to support in order to be used as argument to a range. It's just non-sensical and therefore confusing. There is nothing on this page which would indicate to me that something like <vector> would satisify the concept. The page is does not document a "concept" in the C++ manner.
It is common practice in Boost libraries for a concept to be associated with two sets of interfaces: an interface that the consumer of the concept uses to work with models of the concept, and the interface that the provider of the concept (that is, the programmer who is writing a type to model the concept or adapting a third-party type to model the concept) uses to make his type model the concept. It is of course possible for the two interfaces to be the same, but in some cases this is problematic. If this single interface uses member functions, then third-party types which do not have those member functions cannot be adapted to model the concept. An interface that uses non-member functions avoids this problem, but sometimes there are pre-existing conventions (e.g. container classes having begin() and end() member functions) that that are already in wide use and it would be annoying if every class that already uses those conventions would now have to write member function wrappers to model the interface. Having two different interfaces solves this problem: consumers of the concept use the interface meant for them, and providers of models of the concepts use mechanisms meant for them to model the concept. The library defining the concept provides the glue between the two. This is the case with Boost.Range: the interface for consumers is boost::begin() and boost::end(). Model providers have a choice of either using member begin() and end() functions, or non-member range_begin() and range_end() functions found using ADL. The C++0x concepts proposal was going to alleviate this need for two interfaces by providing a language construct named "concept_map" which allowed writing the glue code that allows adapting a type with a different interface to model a concept with the required interface. Sadly, that proposal did not pass, so in Boost today we have to keep using this work-around with two interfaces.
d) I forgot to add this. The exposition of each function, template etc, could benefit by including a small example. This is common practice among other similar libraries. It is generally very helpful.
Agreed. Once again, I'm sure the maintainers would welcome patches.
lol - so by making this observation it's incumbant on me to to create and test 100 examples of each feature of the library?
Not at all. I'm just pointing out that *someone* has to do it, and in the world of free/open-source software, often the person with sufficient motivation to implement a feature (or write documentation snippet etc.) is the one who asks for it. Regards, Nate