[boost] Re: New IA - Is there a quick walkthrough?

From: David Abrahams (dave_at_[hidden])
Date: 2003-12-04 20:26:19

"Giovanni Bajo" <giovannibajo_at_[hidden]> writes:

> Hello,
>
> I think the new IA library is missing a quick walkthrough, or a how-to-use
> document, or both. 

Yes, we know.  We haven't had a chance to write the user-level
documentation.  We've been over this before.

See http://article.gmane.org/gmane.comp.lib.boost.devel/28886

> I'm upgrading some old code using the old IA library (and
> this to say that I've an idea how the whole stuff work), but I can't find
> answers to my questions. The documentation explains (in rather complex
> words) what a boost::iterator_adaptor/facade is (entering also technical
> discussions that really end-users *shouldn't* care). I find the
> documentation too much technical. For instance:
>
> boost\libs\iterator\doc\iterator_adaptor.html:
>
> --------- QUOTE -----------
>       abstract:
>
> Each specialization of the iterator_adaptor class template is derived from a
> specialization of iterator_facade.  core interface functions expected by
> iterator_facade are implemented in terms of the iterator_adaptor's Base
> template parameter. [...]
> --------- UNQUOTE -----------
>
> These are technical details I don't care. 

I promise you, you do care about those details.  They're not just
implementation details since they affect both your ability to
understand and use iterator_adaptor.

> I'm here to know what
> iterator_adaptor is and what I can use it for, 

We will provide more introduction in the user-level docs.  But
seriously, was the foregoing sentence

   "The iterator_adaptor class template adapts some Base type to
   create a new iterator."

really inadequate?  Oh, you're looking at
libs/iterator/doc/iterator_adaptor.html.  That's not ready for
prime-time yet.  Please use the standard proposal:
libs/iterator/doc/facade-and-adaptor.html in the meantime.

> not how it is implemented internally.

Without knowing about iterator_adaptor's implementation and its
relationship to iterator_facade, you can't use it
effectively... unless we were to basically repeat all the
iterator_facade docs (bad idea IMO).

> This first paragraph is totally misplaced IMO.
>
> Luckily, we have an introduction (a bit later):
>
> --------- QUOTE -----------
> The iterator_adaptor class template adapts some Base 1 type to create a new
> iterator. Instantiations of iterator_adaptor are derived from a
> corresponding instantiation of iterator_facade and implement the core
> behaviors in terms of the Base type. In essence, iterator_adaptor merely
> forwards all operations to an instance of the Base type, which it stores as
> a member.
> --------- UNQUOTE -----------

> The second sentence is tech-talkie again. The first and the third sentence
> instead give me an outlook of the library, which is what I was expecting to
> see at the very beginning of the document.
>
>
> --------- QUOTE -----------
> The user of iterator_adaptor creates a class derived from an instantiation
> of iterator_adaptor and then selectively redefines some of the core member
> functions described in the table above.
>  --------- UNQUOTE -----------
>
> Interesting, but there is absolutely no table above. 

That's because of the not-ready-for-prime-time effect I described
earlier.

> Then a full paragraph
> about "use_default" and why (techinically, again) you need it (I really
> wouldn't care, it'd be enough if you told me "just use 'use_default' for the
> other template parameters"). Then, Reference, with implementation code.
>
> Then, an "usage" paragraph:
>
> --------- QUOTE -----------
> The Derived template parameter must be a publicly derived from
> iterator_adaptor. In order for Derived to model the iterator concepts
> corresponding to iterator_traits<Derived>::iterator_category, the
> expressions involving m_iterator in the specifications of those private
> member functions of iterator_adaptor that may be called by
> iterator_facade<Derived, ``\ *V*\, \ *C*\, \ *R*\, \ *D*\>`` in evaluating
> any valid expression involving Derived in those concepts' requirements.
>  --------- UNQUOTE -----------
>
> which I can barely grok, let alone being any helpful to me. Then,
> standard-like member function explanations (most of them are private, which
> I shouldn't care, should I?).
>
> And that's it (for iterator_adaptor).
>
> I read it a few times, I went through iterator_facade.html as well (which is
> maybe slightly better, but still too many technical-centered), and I still
> don't know how to use iterator_adaptor. I don't have ANY clue. Luckily, the
> paragraph "upgrading from old iterator adaptor library" gave me some ideas
> about what to do, so I started something.

Please go through the standard proposal and let us know if you still
have no clue.

> I'm trying to write an iterator which behaves like
> std::map<whatever,whatever>::iterator, but returns the values when
> dereferenced, that is pair's second element (iterator over the values, like
> Python's dict.itervalues()). I don't need it to be generic for all maps
> (that would be a plus, but hey), I need it only for my very map
> instantiation. I tried this:
>
>   struct Attribute { /* blah */ };
>
>    typedef std::map<int, Attribute> attribute_map_t;
>
>     class AttributeIterator
>         : public boost::iterator_adaptor
>         <
>             AttributeIterator,
>             attribute_map_t::iterator,
>             Attribute
>         >
>     {
>         Attribute dereference(void) const
>         { return this->base()->second; }
>     };

I'd use a transform_iterator for that, with a function object which
returns the second element.

> but it didn't work. 

What "didn't work" about it?

> It seems like I should define also some copy constructors, but the
> documentation didn't tell me. 

There's usually no need for a copy ctor other than the one you'll get
by default.

> It didn't even tell me I can change dereference, since there is no
> table. Of course, I can't find any document explaining me how the
> derefence prototype has to look like, and stuff like that.

See above.

> Then I'd need also a const iterator (and I heard the new IA should generate
> const iterators even more easily), but I can't find how to do it without cut
> & pasting.
>
> Now, tell me that I missed begginer.html, please, and that it's right there.
> I think this library needs a whole introduction document, which drives you
> step by step, and shows you how to use iterator_facade and iterator_adaptor
> to do very simple tasks. It seems like Boost.Python without the "Tutorial
> Introduction", I doubt anybody will know how to use it just by staring at
> the
> refence.
>
> Just my 2c, hope it helps.

Thanks for the feedback.  Please let us know how you do once you've
read the standard proposal.

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