Boost logo

Boost :

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


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:


--------- QUOTE -----------

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

Just my 2c, hope it helps.

Giovanni Bajo

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