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: Neil Groves (neil_at_[hidden])
Date: 2010-05-16 06:06:07

On Sun, May 16, 2010 at 3:59 AM, Mostafa <mostafa_working_away_at_[hidden]>wrote:

> On Sat, 15 May 2010 14:59:25 -0700, Neil Groves <neil_at_[hidden]>
> wrote:
>
> (Personal rant: another reason for this response is that too often I see
> C++ programmers, especially the older crowd, sacrificing generic/decoupled
> design out of cost concerns, without first putting into perspective what
> those costs entail, ie, a) what is the range of the measured cost and b) is
> it acceptable?)
>
>
My comment started with an urge to caution about applying the approach
generally. 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.

>
>
>  You can use the boost::iterator_range type and the
>> boost::make_iterator_range function to help create a range from iterators.
>>
>
> I'm reading the Boost.Range documentation and I have a number of
> questions/comments, listed below:
>
> 1) The documentation is a great reference.  It's a frustrating as an
> introduction.  It's a frustrating as a tutorial.  (Please don't take this
> the wrong way, or personally.)
>
>
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. Of course if you
wish to contribute to the tutorial that would be very welcome.

> 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

> Additionally, right next to this definition, can you give examples of some
> common types which match the definition of Range?  (Some are alluded to in
> the Introduction.)
>
>
That's a useful idea. I will do that.

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

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

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

> 6) Same thing as 5) for the following comment "If an instance of
> iterator_range  is constructed by a client with two iterators, the client
> must ensure that the two iterators delimit a valid closed-open range
> [begin,end)." in the following page:
>
>
> http://www.boost.org/doc/libs/1_43_0/libs/range/doc/html/range/reference/utilities/iterator_range.html
>
> It's just too easy to miss these important preconditions if they're not
> blatantly in your face.
>
>
This can indeed be improved. All of the range classes should ideally have
the full contract and indeed complexity specification.

> 7) The use of operator| is jarring.  Especially in the introductory
> examples without any textual introduction.  (Yes, I did read the motivation
> behind it, but it still doesn't jive with me.  Maybe it's all those years of
> math/cs indoctrination.)  I think programmers won't freak out as much if the
> introductory examples used function composition first then showed the
> alternative with operator|.
>
>
There is an alternative for those that don't like the '|' to allow users to
choose. I prefer the '|' as do many others, but as the library author I must
not dictate a use pattern that is currently controversial. Hence you already
have the option to use the alternative syntax. Some of us that prefer the
'|' have done a little math too ;-)

> See page:
>
>
> http://www.boost.org/doc/libs/1_43_0/libs/range/doc/html/range/reference/adaptors/introduction.html
>
>
>
>  However for cases like these
>> where you would like to have some syntactic sugar I would write this:
>>
>
> Finally, thanks for providing a usable any_range example.  It's very
> gracious of you.
>
>
I hope it is of some use. I had briefly tested the any_range code with GCC
4.3 in Linux, after obtaining the any_iterator code.

>
>
> Thanks,
>
> -Mostafa
>
>
I sincerely hope that this helps,
Neil Groves