Boost logo

Boost :

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.


> 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

> 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

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