Boost C++ Libraries Home Libraries People FAQ More

PrevUpHomeNext

Iterator Adaptor

Reference
Tutorial

The iterator_adaptor class template adapts some 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.

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

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:

Requirements

static_cast<Derived*>(iterator_adaptor*) shall be well-formed. The Base argument shall be Assignable and Copy Constructible.

.. _base_parameters:

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:

   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

Operations

Public

iterator_adaptor();

Requires: The Base type must be Default Constructible.
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

Protected

Base const& base_reference() const;

Returns: A const reference to m_iterator.

Base& base_reference();

Returns: A non-const reference to m_iterator.

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


PrevUpHomeNext