| Home | Libraries | People | FAQ | More

### Iterator Adaptor

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.

#### Reference

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