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

From: Giovanni Bajo (giovannibajo_at_[hidden])
Date: 2003-12-04 14:29:53

Hello,

I think the new IA library is missing a quick walkthrough, or a how-to-use
document, or both. 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'm here to know what
iterator_adaptor is and what I can use it for, not how it is implemented
internally. 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. 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.

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; }
    };

but it didn't work. It seems like I should define also some copy
constructors, but the documentation didn't tell me. 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.

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.

Giovanni Bajo