123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333 |
- [section:adaptor Iterator Adaptor]
- The `iterator_adaptor` class template adapts some `Base` [#base]_
- 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.
- .. [#base] The term "Base" here does not refer to a base class and is
- not meant to imply the use of derivation. We have followed the lead
- of the standard library, which provides a base() function to access
- the underlying iterator object of a `reverse_iterator` adaptor.
- 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
- `iterator_facade` core requirements table. The `Base` type need
- not meet the full requirements for an iterator; it need only
- support the operations used by the core interface functions of
- `iterator_adaptor` that have not been redefined in the user's
- derived class.
- Several of the template parameters of `iterator_adaptor` default
- to `use_default`. This allows the
- user to make use of a default parameter even when she wants to
- specify a parameter later in the parameter list. Also, the
- defaults for the corresponding associated types are somewhat
- complicated, so metaprogramming is required to compute them, and
- `use_default` can help to simplify the implementation. Finally,
- the identity of the `use_default` type is not left unspecified
- because specification helps to highlight that the `Reference`
- template parameter may not always be identical to the iterator's
- `reference` type, and will keep users from making mistakes based on
- that assumption.
- [section:adaptor_reference Reference]
- [h2 Synopsis]
- template <
- class Derived
- , class Base
- , class Value = use_default
- , class CategoryOrTraversal = use_default
- , class Reference = use_default
- , class Difference = use_default
- >
- class iterator_adaptor
- : public iterator_facade<Derived, *V'*, *C'*, *R'*, *D'*> // see details
- {
- friend class iterator_core_access;
- public:
- iterator_adaptor();
- explicit iterator_adaptor(Base const& iter);
- typedef Base base_type;
- Base const& base() const;
- protected:
- typedef iterator_adaptor iterator_adaptor\_;
- Base const& base_reference() const;
- Base& base_reference();
- private: // Core iterator interface for iterator_facade.
- typename iterator_adaptor::reference dereference() const;
- template <
- class OtherDerived, class OtherIterator, class V, class C, class R, class D
- >
- bool equal(iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& x) const;
-
- void advance(typename iterator_adaptor::difference_type n);
- void increment();
- void decrement();
- template <
- class OtherDerived, class OtherIterator, class V, class C, class R, class D
- >
- typename iterator_adaptor::difference_type distance_to(
- iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& y) const;
- private:
- Base m_iterator; // exposition only
- };
- __ base_parameters_
- .. _requirements:
- [h2 Requirements]
- `static_cast<Derived*>(iterator_adaptor*)` shall be well-formed.
- The `Base` argument shall be Assignable and Copy Constructible.
- .. _base_parameters:
- [h2 Base Class Parameters]
- The *V'*, *C'*, *R'*, and *D'* parameters of the `iterator_facade`
- used as a base class in the summary of `iterator_adaptor`
- above are defined as follows:
- [pre
- *V'* = if (Value is use_default)
- return iterator_traits<Base>::value_type
- else
- return Value
- *C'* = if (CategoryOrTraversal is use_default)
- return iterator_traversal<Base>::type
- else
- return CategoryOrTraversal
- *R'* = if (Reference is use_default)
- if (Value is use_default)
- return iterator_traits<Base>::reference
- else
- return Value&
- else
- return Reference
- *D'* = if (Difference is use_default)
- return iterator_traits<Base>::difference_type
- else
- return Difference
- ]
- [h2 Operations]
- [h3 Public]
- iterator_adaptor();
- [*Requires:] The `Base` type must be Default Constructible.[br]
- [*Returns:] An instance of `iterator_adaptor` with
- `m_iterator` default constructed.
- explicit iterator_adaptor(Base const& iter);
- [*Returns:] An instance of `iterator_adaptor` with
- `m_iterator` copy constructed from `iter`.
- Base const& base() const;
- [*Returns:] `m_iterator`
- [h3 Protected]
- Base const& base_reference() const;
- [*Returns:] A const reference to `m_iterator`.
- Base& base_reference();
- [*Returns:] A non-const reference to `m_iterator`.
- [h3 Private]
- typename iterator_adaptor::reference dereference() const;
- [*Returns:] `*m_iterator`
- template <
- class OtherDerived, class OtherIterator, class V, class C, class R, class D
- >
- bool equal(iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& x) const;
- [*Returns:] `m_iterator == x.base()`
- void advance(typename iterator_adaptor::difference_type n);
- [*Effects:] `m_iterator += n;`
- void increment();
- [*Effects:] `++m_iterator;`
- void decrement();
- [*Effects:] `--m_iterator;`
- template <
- class OtherDerived, class OtherIterator, class V, class C, class R, class D
- >
- typename iterator_adaptor::difference_type distance_to(
- iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& y) const;
- [*Returns:] `y.base() - m_iterator`
- [endsect]
- [section:adaptor_tutorial Tutorial]
- In this section we'll further refine the `node_iter` class
- template we developed in the |fac_tut|_. If you haven't already
- read that material, you should go back now and check it out because
- we're going to pick up right where it left off.
- .. |fac_tut| replace:: `iterator_facade` tutorial
- .. _fac_tut: iterator_facade.html#tutorial-example
- [blurb [*`node_base*` really *is* an iterator][br][br]
- It's not really a very interesting iterator, since `node_base`
- is an abstract class: a pointer to a `node_base` just points
- at some base subobject of an instance of some other class, and
- incrementing a `node_base*` moves it past this base subobject
- to who-knows-where? The most we can do with that incremented
- position is to compare another `node_base*` to it. In other
- words, the original iterator traverses a one-element array.
- ]
- You probably didn't think of it this way, but the `node_base*`
- object that underlies `node_iterator` is itself an iterator,
- just like all other pointers. If we examine that pointer closely
- from an iterator perspective, we can see that it has much in common
- with the `node_iterator` we're building. First, they share most
- of the same associated types (`value_type`, `reference`,
- `pointer`, and `difference_type`). Second, even some of the
- core functionality is the same: `operator*` and `operator==` on
- the `node_iterator` return the result of invoking the same
- operations on the underlying pointer, via the `node_iterator`\ 's
- |dereference_and_equal|_). The only real behavioral difference
- between `node_base*` and `node_iterator` can be observed when
- they are incremented: `node_iterator` follows the
- `m_next` pointer, while `node_base*` just applies an address offset.
- .. |dereference_and_equal| replace:: `dereference` and `equal` member functions
- .. _dereference_and_equal: iterator_facade.html#implementing-the-core-operations
- It turns out that the pattern of building an iterator on another
- iterator-like type (the `Base` [#base]_ type) while modifying
- just a few aspects of the underlying type's behavior is an
- extremely common one, and it's the pattern addressed by
- `iterator_adaptor`. Using `iterator_adaptor` is very much like
- using `iterator_facade`, but because iterator_adaptor tries to
- mimic as much of the `Base` type's behavior as possible, we
- neither have to supply a `Value` argument, nor implement any core
- behaviors other than `increment`. The implementation of
- `node_iter` is thus reduced to:
- template <class Value>
- class node_iter
- : public boost::iterator_adaptor<
- node_iter<Value> // Derived
- , Value* // Base
- , boost::use_default // Value
- , boost::forward_traversal_tag // CategoryOrTraversal
- >
- {
- private:
- struct enabler {}; // a private type avoids misuse
- public:
- node_iter()
- : node_iter::iterator_adaptor_(0) {}
- explicit node_iter(Value* p)
- : node_iter::iterator_adaptor_(p) {}
- template <class OtherValue>
- node_iter(
- node_iter<OtherValue> const& other
- , typename boost::enable_if<
- boost::is_convertible<OtherValue*,Value*>
- , enabler
- >::type = enabler()
- )
- : node_iter::iterator_adaptor_(other.base()) {}
- private:
- friend class boost::iterator_core_access;
- void increment() { this->base_reference() = this->base()->next(); }
- };
- Note the use of `node_iter::iterator_adaptor_` here: because
- `iterator_adaptor` defines a nested `iterator_adaptor_` type
- that refers to itself, that gives us a convenient way to refer to
- the complicated base class type of `node_iter<Value>`. [Note:
- this technique is known not to work with Borland C++ 5.6.4 and
- Metrowerks CodeWarrior versions prior to 9.0]
- You can see an example program that exercises this version of the
- node iterators
- [@../example/node_iterator3.cpp `here`].
- In the case of `node_iter`, it's not very compelling to pass
- `boost::use_default` as `iterator_adaptor` 's `Value`
- argument; we could have just passed `node_iter` 's `Value`
- along to `iterator_adaptor`, and that'd even be shorter! Most
- iterator class templates built with `iterator_adaptor` are
- parameterized on another iterator type, rather than on its
- `value_type`. For example, `boost::reverse_iterator` takes an
- iterator type argument and reverses its direction of traversal,
- since the original iterator and the reversed one have all the same
- associated types, `iterator_adaptor` 's delegation of default
- types to its `Base` saves the implementor of
- `boost::reverse_iterator` from writing:
- std::iterator_traits<Iterator>::*some-associated-type*
- at least four times.
- We urge you to review the documentation and implementations of
- |reverse_iterator|_ and the other Boost `specialized iterator
- adaptors`__ to get an idea of the sorts of things you can do with
- `iterator_adaptor`. In particular, have a look at
- |transform_iterator|_, which is perhaps the most straightforward
- adaptor, and also |counting_iterator|_, which demonstrates that
- `iterator_adaptor`\ 's `Base` type needn't be an iterator.
- .. |reverse_iterator| replace:: `reverse_iterator`
- .. _reverse_iterator: reverse_iterator.html
- .. |counting_iterator| replace:: `counting_iterator`
- .. _counting_iterator: counting_iterator.html
- .. |transform_iterator| replace:: `transform_iterator`
- .. _transform_iterator: transform_iterator.html
- __ index.html#specialized-adaptors
- [endsect]
- [endsect]
|