Boost logo

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]>

> 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:
>> 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:

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.
> No! I respectfully disagree that it would be an improvement. Accidental
> 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.



Boost list run by bdawes at, gregod at, cpdaniel at, john at