Re: [boost] [iterator] why isn't there a mapped_type iterator adaptor in boost?

Subject: Re: [boost] [iterator] why isn't there a mapped_type iterator adaptor in boost?
From: Mostafa (mostafa_working_away_at_[hidden])
Date: 2010-05-16 23:49:03

On Sun, 16 May 2010 03:06:07 -0700, Neil Groves <neil_at_[hidden]>  
wrote:

> I have acknowledged on this mailing list that a tutorial would make the
> Boost.Range documentation better. My schedule only just allowed a good,
> correct implementation with reference documentation for 1.43. Delaying  
> for
> another release to fit in a tutorial would not have been the right  
> decision.
> I apologise for the steeper than optimal learning curve.

No problem.  Let me clarify that I am approaching the  
documentation/library from three perspectives: as an individual  
programmer, as an employee of company X, and as a supervisor with  
technological decision making responsibilities.  From a an individual  
programmer's perspective, I can figure out how to use the library from the  
documentation, and if I find the syntax a little funny, I can live with  
that, same goes for the naming convention.  But it's mostly from an  
employee's perspective and a supervisor's perspective that I am  
approaching this.  Why?  Because I think that Boost can make my life  
easier at work, and I would like to be able to use it.  And the only way I  
would be able to use it would be to sell it to my boss and my peers.  On  
technical grounds, it's a pretty easy sell.  On usability, it's harder.   
What's a crucial factor in making usability easier, the documentation.   
Hence my comments/criticisms/suggestions on it (with no guarantee that any  
of it is actually valid, but, which is given in good faith).

>  Of course if you wish to contribute to the tutorial that would be very  
> welcome.

Let me see what I can come up with.

>> 2) What exactly is the definition of Range?  Is it any type that meets  
>> the
>> requirements of any one of the following concepts: Single Pass Range
>> Concept, Forward Range Concept, Bidirectional Range Concept, Random  
>> Access
>> Range Concept?
>>
>>
> I normally speak of a Range as something that models the
> SinglePassRangeConcept or above.
>
>
>> If so, can you explicitly and prominently declare that in the
>> documentation?  The documentation here:
>> http://www.boost.org/doc/libs/1_43_0/libs/range/doc/html/range/concepts/overview.html,  
>> really beats around the bush.  It describes some attributes of Range,  
>> but
>> doesn't quite define it.
>>
>>
> The above link is to an overview of the Range concept. From my  
> perspective
> it therefore, by definition, does not fully describe the Range Concepts.
> Specific improvements or at an example improvement would be more  
> applicable
> feedback. The technical explanations for each of the range concepts is
> provided here:
>
> http://www.boost.org/doc/libs/1_43_0/libs/range/doc/html/range/concepts/single_pass_range.html
> http://www.boost.org/doc/libs/1_43_0/libs/range/doc/html/range/concepts/forward_range.html
> http://www.boost.org/doc/libs/1_43_0/libs/range/doc/html/range/concepts/bidirectional_range.html
> http://www.boost.org/doc/libs/1_43_0/libs/range/doc/html/range/concepts/random_access_range.html
>

Specifically I would suggest putting the definition of 2) in the  
Overview.  (I take from your response that that is indeed the definition  
of Range.)

>> 3) Why is the library named Range when it seems that only iterator_range
>> actually encompasses a range of iterators.  Am I missing something here?
>>
>>
> I don't understand this point. The library is called Range because it
> defines Range types, Range algorithms and Range adaptors. This has been  
> one
> of the less controversial naming decisions.
>

Maybe if Range was defined early on I wouldn't have this question.  The  
reason I bring it up is because the word Range, in the absence of any  
definition, immediately conjures up something along the lines of [x, y) or  
some variation thereof.  But, from my reading of the documentation a range  
can be any stl container, an array, a std::string, a pair of iterators,  
etc...  And when I see the word Range, the first thing that pops to mind  
isn't exactly a container or an array, I have an easier time associating  
iterator_range with Range.

>> 4) Having both range_iterator and iterator_range is just confusing.  Are
>> you trying to purposefully make me dyslexic? ;)
>>
>
> I appreciate that this can be a little confusing but coming up with a  
> better
> name for range_iterator is very tricky, and there is actually a formulaic
> naming convention applied to the metafunctions where range_ is prefixed  
> to
> the type that is extracted by the metafunction. iterator_range is the  
> most
> sensible name for a range of iterators. That is the rationale, and of  
> course
> it is too late to be flexible on this issue. This was not listed as a
> concern by anyone during the review process IIRC.
>

No problem.  I'm approaching this with no expectations on my part.  My  
only goal is to raise usability flags where I think there exists some.

>>
>> 5) Put "Notice that the above functions should always be called with
>> qualification (boost::) to prevent unintended  Argument Dependent Lookup
>> (ADL)." prominently at the *top* of the following document, preferably  
>> with
>> some sort of advisory icon.
>>
>>
>> http://www.boost.org/doc/libs/1_43_0/libs/range/doc/html/range/reference/concept_implementation/semantics/functions.html
>>
>>
> No! I respectfully disagree that it would be an improvement. Accidental  
> ADL
> lookup for non-member functions is a general C++ issue, the only reason  
> for
> the clarification requirement in the reference documentation is to ensure
> that it is understood that not using ADL will not prohibit the  
> invocation of
> the extension mechanism. The extension mechanism is carefully designed to
> support extension even when the user is making fully qualified calls.
>
> I probably should alter the documentation to clarify my intent however.
>
> One of the hardest jobs of being a maintainer is saying 'No', but if I  
> put
> to the top everything that each user considered the most important I  
> would
> simply be shuffling the docs perpetually.

Just to clarify, as a general rule should the client always use boost:: ?

If so, then let me explain my rationale.  I'm working on a laptop with  
1280 x 800 resolution.  When I first land on the above website I see a  
table of functions that's cut off at "const_begin(x)".  Okay, I mentally  
tell myself, it's just a table of functions and their explanations, good  
for reference, don't need it now, then press the "->" at the top of the  
page and keep reading on.  Because the "->" appears on both the top of the  
page and the bottom, I'm not forced to scroll down to go to the next page,  
hence I miss whatever info is at the bottom.  (This may very well be a bad  
habit on my part, but I don't think I'm the only one.)  Even if I return  
to this page to lookup something, what I'll most likely be interested in  
can still be found without scrolling down enough to see that there exists  
non-tabular information at the bottom of the page.

> This was carefully chosen language that actually resembles the
> documentation that the original author of any_iterator provides. A rant
> appears to be an inappropriate response.

Maybe I shouldn't have used the word rant; and hopefully I haven't  
dissuaded you from providing future insights/advice.

Thanks,

-Mostafa