[boost] Re: have there been some major changes in iterator_adaptor?

From: David Abrahams (dave_at_[hidden])
Date: 2003-11-23 22:17:48

Matthias Schabel <boost_at_[hidden]> writes:

>>> The documentation is a bit...sparse...
>> Seriously?  Did you follow the links to the standard proposals?
>
> To quote from http://www.boost-consulting.com/boost/libs/iterator/doc/
> :
>
> "Testing and Concept Checking iterator_archetypes.hpp: Add
> summary here iterator_concepts.hpp: Add summary"

Yes, those are new components which don't have any particular bearing
on you if you're just interested in upgrading.  You'll have to pester
Jeremy about documenting those ones, though.

> "Upgrading from the old Boost Iterator Adaptor Library
>
> Turn your policy class into the body of the iterator
>
> Use transform_iterator with a true reference type for
> projection_iterator."
>
> I consider those sections to be "sparse"... 

True, I'm working on the content for those sections now.  Here's what
I currently have:

  =======================================================
   Upgrading from the old Boost Iterator Adaptor Library
  =======================================================

  .. _Upgrading:

  If you have been using the old Boost Iterator Adaptor library to
  implement iterators, you probably wrote a ``Policies`` class which
  captures the core operations of your iterator.  In the new library
  design, you'll move those same core operations into the body of the
  iterator class itself.  If you were writing a family of iterators,
  you probably wrote a `type generator`_ to build the
  ``iterator_adaptor`` specialization you needed; in the new library
  design you don't need a type generator (though may want to keep it
  around as a compatibility aid for older code) because, due to the
  use of the Curiously Recurring Template Pattern (CRTP) [Cop95]_,
  you can now define the iterator class yourself and acquire
  functionality through inheritance from ``iterator_facade`` or
  ``iterator_adaptor``.  As a result, you also get much finer control
  over how your iterator works: you can add additional constructors,
  or even override the iterator functionality provided by the
  library.

  .. _`type generator`: ../../../more/generic_programming.html#type_generator

  If you're looking for the old ``projection_iterator`` component,
  its functionality has been merged into ``transform_iterator``: as
  long as the function object's ``result_type`` (or the ``Reference``
  template argument, if explicitly specified) is a true reference
  type, ``transform_iterator`` will behave like
  ``projection_iterator`` used to.

> I guess I was hoping for a
> small set of examples demonstrating actual use of the new iterator
> adaptors for a range of cases spanning the basically trivial case
> above to something more non-trivial.  

We're going to be providing tutorial docs, but in the meantime you
should just take a look at the specialized adaptors that are already
in Boost.  You can browse quite a few of them at
http://boost-consulting.com/boost/boost/iterator/, and you'll also
find examples in the tokenizer, filesystem, and multi_array libraries.

> It would be nice to have one functioning program demonstrating each
> major concept

You seriously want a functioning program demonstrating,
e.g. WritableIterator, and another demonstrating
IncrementableIterator, etc?  I don't think that would be very helpful,
nor very reasonable.

> or intended use of the library.  

Aside from iterator_archetypes.hpp and iterator_concepts.hpp, which
are for concept checking, the library is intended for building
iterators and iterator adaptors.  We are going to provide an example
walkthrough of building a transform iterator adaptor, and probably
another of building an iterator from scratch using iterator_facade.  

> The existing docs
> (including, esp., the proposal) are heavy on theory 

Hmm, there's nothing I'd call "theory" in there.

> and short on implementation.  

Do you mean examples?  Yes, that's because those are proposals for
the standard.  There will be a few examples in the Boost docs.

> Maybe it's just me, but I find it much easier to understand
> concepts, particularly fairly complex abstractions such as the new
> iterator proposal relies on, if there is a reasonably complete set
> of example cases of functioning code to refer to.

http://boost-consulting.com/boost/boost/iterator/
http://boost-consulting.com/boost/boost/filesystem/path.hpp
http://boost-consulting.com/boost/boost/token_iterator.hpp

> Furthermore, there is so much in the iterator adaptor
> library that one could spend a significant amount of time and energy
> trying to understand it all.  

It's actually become quite a bit simpler in the new version, IMO.

> While this is well and good, I think there will be a decent body of
> users who are mostly interested in a quick and effective solution
> for simple iterator adaptors for whom the investment of time in
> understanding the details may not be efficient.  If the user has to
> spend more time reading the documentation than it would take to slap
> together a simple home-grown implementation, it may impede adoption
> of the library.

I appreciate your concern.

>>> I assume I can just plug back in the old iterator adaptor stuff
>> I don't know what you mean by that.
>
> Use the old <boost/iterator_adaptors.hpp> which was perfectly fine for
> my purposes - the answer appears to be yes.

I wouldn't count on it staying that way; we're not maintaining that
file anymore and it's been removed from the CVS>

>>> and be on my merry way until things have shaken out?  Or is there
>>> an easy way to accomplish the above with the new system?
>> What's "the above?"
>
> Wrapping a bare pointer to form a well-behaved iterator and wrapping
> that iterator to form a reverse iterator.

A bare pointer isn't a well-behaved iterator?

Anyway:

        template <class It>
        class identity_iterator
           : iterator_adaptor<identity_iterator<It>, It>
        {
            typedef iterator_adaptor<identity_iterator<It>, It> base;
         public:
            identity_iterator();
            explicit identity_iterator(It p) : base(p) {}
        };
 
That wraps any iterator in an iterator_adaptor.

To get a reversed one, why wouldn't you just use
boost::reverse_iterator<whatever> 
??

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