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-02 15:56:35

Vicente J. Botet Escriba wrote:
>> a)  To me, the range library/concept is not appreciated to the extent
>> it should be.  I don't think that potential users appreciate the
>> utility of being able to compose adaptors.  I think the
>> documentation would benefit from more examples.'

> How do you know what potential users appreciate or not.
> Almost any Boost library could improve its documentation I I think
> some of them are already doing it.

lol - well of course I can't KNOW what other users would appreciate.
I'll agree that this is conjecture on my part. Let's give me a break
and call it "informed conjecture".

>> d) When I've used the library - I've found that I've had to
>> spelunk through the code to understand how to "make it
>> work".  Of course now I don't recall the specific cases other
>> than the one which motivated this post, but they are common.
>> I believe that more examples and tests would smoke these out.
> I'm sure that if you post here the specific example that was
> confusing, the authors will try to correct it.

lol - That's what I'm doing here!

>> e) Somethings are not quite right - the thing that motivated this
>> post is the confluence of containers and ranges.  There might
>> be other things.

> What do you mean?

That's what I've been trying to explain here. I concede with limited
success.  The documentation suggests that a SinglePassRange
is sort of a "pair of interators".  But it turns out that any Container
is also a SinglePassRange.  I'm sorry that's confusing to a plain
reading. (note: understand how things are implemented so
please don't re-explain it to me).  I would expect something more
along the lines of

Nomenclature

R SinglePassRange type
r instance of a type R

valid expressions

r.begin()
r.end()

In this case then a any container would full fill the requirements
of a SinglePassRange.

To be conforming, something like "struct iterator_range" would have
to supply the same functions.  The notion boost::begin(r) and boost::end(r)
seems out of place to me.  I haven't thought through all the implications
of this as it would have rippled through the library design.  So cut me
some slack here.

Basically, I don't think the range library exploits the "concept" concept
properly and the library suffers for it..  (off topic - I would love to hang 
the
person who came up the with the name "concept" for what to me would better
be called "type requirement".)

Robert Ramey