[boost] Re: libs/iterator/doc/iterator_facade.html typo?

From: David Abrahams (dave_at_[hidden])
Date: 2004-02-13 07:43:16

[Jeremy, I hope you can comment on this because some of it relates to
your writings]

"David Bergman" <davidb_at_[hidden]> writes:

> In the Design section of the proposal, you write
>
> 	"Our design reuses iterator_traits<Iter>::iterator_category to
> indicate an iterator's traversal capability."
>
> That use of iterator category does pertain to the Traversal "dimension"
> (attribute, or whatever we want to call it), or?
>
> I want there to be an explanation, such as
>
> 	"Our design reuses iterator_traits<Iter>::iterator_category to
> indicate not only the old-style, combined traversal and access capabilities
> of the iterator, but also the iterator's traversal capability alone. See the
> category-to-traversal schema for conversion from the old-style iterator
> categories to corresponding traversal capability categories. Note that the
> access capability of the iterator is not incorporated in any iterator
> category, but derivable from the associated value_type of the concept."

That's very comprehensible, and a good suggestion, thank you.  The
wording should be slightly different, but it's good.

> Some of of the 'iterator_traits::iterator_category' instances refer to
> traversal capabilities, as in the quoted text above, and some to the
> old-style concepts. I.e., there are new "iterator categories" that only
> treat the Traversal attribute/dimension.

That's a stretch.  We don't want to call traversal concepts
"categories".  They just happen to be indicated via the
iterator_category member of iterator_traits.

>> > Could one not make that clear, such as:
>> >
>> > 	"category tags can dispatch
>> 
>> Tags don't dispatch, and I consider that phrase extremely 
>> confusing, and possibly misleading.
>
> I obviously meant "category tags enable dispatching on both ..."
>
>> > based on both traversal capability and the combined capabilities of 
>> > traversal and access"
>> 
>> Besides that, I have no clue about the intended meaning of 
>> the above statement, so I wouldn't make it in an effort to 
>> clarify anything.
>
> I meant that one can dispatch based solely on the traversal property of the
> iterator and the combined traversal and access properties.

Actually no, not directly.  If you want to dispatch on traversal you
have to use iterator_traversal<It>::type to get at the traversal
property.  Old-style iterators' iterator_category doesn't have any
convertibility relationship to the traversal tags.

>> > I understand, and always understood, your proposal, which is very
>> > welcome, but I do also understand if others might find the
>> > mentioning of "category" a bit misleading, since we have the old,
>> > combined world, and the new dichotomy to deal with.
>> 
>> I still don't understand what you consider misleading.  
>> Please point to a sentence and describe how it can be misread.
>
> See above. You still think you use "category" only for the combined
> old-style concepts?

Yes.  "category" (roman font) and "iterator_category" (typewriter
font) are two different ideas.

>> > And... one does, unfortunately, use the word "category" in generic 
>> > programming for both a single concept and a family of related 
>> > concepts,
>> 
>> I've never heard that before, and I'm pretty well-versed in 
>> GP.  If you could point me to an example in the literature, 
>> I'd be indebted.
>
> In the article http://www.oonumerics.org/tmpw01/willcock.pdf, co-written by
> Jeremy Siek, they use "category" very similar to how the C++ Standard deals
> with iterator categories (i.e., as axiomatic sets):
>
> 	In 4.1.1.1: "Each concept must have a name and optionally a
> category."
>
> Does "category" there not refer to a qualification being isomorphic
> to a family of concepts?
>
> Also, in the same article:
>
> 	In 4.3: "A concept is described within the scope of a concept tag
> which contains the concept name and the
> category of the concept (in this case \Utility" for STL utility concepts)."
>
> Thus, Utility is here an (axiomatic or not) family, or set, of concepts. A
> category...
>

I guess so, though I think when you get to the example use of
"Utility", there's no real relationship among family members.  This
usage, however, has not caught on in GP AFAICT even though it is the
normal meaning of "category".  Its intersection with
"iterator_category" is an unfortunate accident caused by the original
STL design, and I don't think it should be up to the Boost iterator
docs to try to clear it up.

> For (unfortunate) examples where "category" is used synonymous to "concept,"
> look at the eminent book "Generative Programming," by Czarnecki and
> Eisenecker, where they (in A.1) state that
>
> 	"... in the context of categorization, concepts are often called
> categories or classes ..."
>
> So, "category" does carry a meaning in GP, and is not specific to the
> (old-style) C++ iterators.

Maybe we just need to say at the beginning that when we refer to
"iterator categories" we mean the old-style concepts?

>> > often including refinement hierarchies :-| I prefer the less
>> > charged word "set of concepts" that you used.
>> 
>> I appreciate that you're only trying to be helpful, but I 
>> really can't understand you.  Trying to figure out what you 
>> mean takes a lot of time.  If you won't take this suggestion,
>> 
>>   Quote some text from the paper, say "I think it should say
>>   ________" instead, and then say why you think so.
>> 
>> I don't think I'm going to spend much more time trying to 
>> figure out what you want.
>
> I am quoting

It worked brilliantly, thank you!

> , and I hope you see that (A) you do use "iterator category" for
> both the old-style iterator classification and the pure traversal
> capability

Nope, we never use it for pure traversal.

> classification and (B) that "category" is used in GP for sets of
> (related) concepts.

It looks like "category" has a confusing usage in the literature, but
I don't know how/what we should do about it.

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com