• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1.. Distributed under the Boost
2.. Software License, Version 1.0. (See accompanying
3.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
4
5.. Version 1.4 of this ReStructuredText document corresponds to
6   n1530_, the paper accepted by the LWG for TR1.
7
8.. Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003.
9
10.. parsed-literal::
11
12  template <
13      class Derived
14    , class Base
15    , class Value               = use_default
16    , class CategoryOrTraversal = use_default
17    , class Reference           = use_default
18    , class Difference = use_default
19  >
20  class iterator_adaptor
21    : public iterator_facade<Derived, *V'*, *C'*, *R'*, *D'*> // see details__
22  {
23      friend class iterator_core_access;
24   public:
25      iterator_adaptor();
26      explicit iterator_adaptor(Base const& iter);
27      typedef Base base_type;
28      Base const& base() const;
29   protected:
30      typedef iterator_adaptor iterator_adaptor\_;
31      Base const& base_reference() const;
32      Base& base_reference();
33   private: // Core iterator interface for iterator_facade.
34      typename iterator_adaptor::reference dereference() const;
35
36      template <
37      class OtherDerived, class OtherIterator, class V, class C, class R, class D
38      >
39      bool equal(iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& x) const;
40
41      void advance(typename iterator_adaptor::difference_type n);
42      void increment();
43      void decrement();
44
45      template <
46          class OtherDerived, class OtherIterator, class V, class C, class R, class D
47      >
48      typename iterator_adaptor::difference_type distance_to(
49          iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& y) const;
50
51   private:
52      Base m_iterator; // exposition only
53  };
54
55__ base_parameters_
56
57.. _requirements:
58
59``iterator_adaptor`` requirements
60---------------------------------
61
62``static_cast<Derived*>(iterator_adaptor*)`` shall be well-formed.
63The ``Base`` argument shall be Assignable and Copy Constructible.
64
65
66.. _base_parameters:
67
68``iterator_adaptor`` base class parameters
69------------------------------------------
70
71The *V'*, *C'*, *R'*, and *D'* parameters of the ``iterator_facade``
72used as a base class in the summary of ``iterator_adaptor``
73above are defined as follows:
74
75.. parsed-literal::
76
77   *V'* = if (Value is use_default)
78             return iterator_traits<Base>::value_type
79         else
80             return Value
81
82   *C'* = if (CategoryOrTraversal is use_default)
83             return iterator_traversal<Base>::type
84         else
85             return CategoryOrTraversal
86
87   *R'* = if (Reference is use_default)
88             if (Value is use_default)
89                 return iterator_traits<Base>::reference
90             else
91                 return Value&
92         else
93             return Reference
94
95   *D'* = if (Difference is use_default)
96             return iterator_traits<Base>::difference_type
97         else
98             return Difference
99
100.. ``iterator_adaptor`` models
101   ---------------------------
102
103   In order for ``Derived`` to model the iterator concepts corresponding
104   to ``iterator_traits<Derived>::iterator_category``, the expressions
105   involving ``m_iterator`` in the specifications of those private member
106   functions of ``iterator_adaptor`` that may be called by
107   ``iterator_facade<Derived, V, C, R, D>`` in evaluating any valid
108   expression involving ``Derived`` in those concepts' requirements.
109
110.. The above is confusing and needs a rewrite. -JGS
111.. That's why it's removed.  We're embracing inheritance, remember?
112
113``iterator_adaptor`` public operations
114--------------------------------------
115
116``iterator_adaptor();``
117
118:Requires: The ``Base`` type must be Default Constructible.
119:Returns: An instance of ``iterator_adaptor`` with
120    ``m_iterator`` default constructed.
121
122
123``explicit iterator_adaptor(Base const& iter);``
124
125:Returns: An instance of ``iterator_adaptor`` with
126    ``m_iterator`` copy constructed from ``iter``.
127
128``Base const& base() const;``
129
130:Returns: ``m_iterator``
131
132``iterator_adaptor`` protected member functions
133-----------------------------------------------
134
135``Base const& base_reference() const;``
136
137:Returns: A const reference to ``m_iterator``.
138
139
140``Base& base_reference();``
141
142:Returns: A non-const reference to ``m_iterator``.
143
144
145``iterator_adaptor`` private member functions
146---------------------------------------------
147
148``typename iterator_adaptor::reference dereference() const;``
149
150:Returns: ``*m_iterator``
151
152::
153
154  template <
155  class OtherDerived, class OtherIterator, class V, class C, class R, class D
156  >
157  bool equal(iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& x) const;
158
159:Returns: ``m_iterator == x.base()``
160
161
162``void advance(typename iterator_adaptor::difference_type n);``
163
164:Effects: ``m_iterator += n;``
165
166``void increment();``
167
168:Effects: ``++m_iterator;``
169
170``void decrement();``
171
172:Effects: ``--m_iterator;``
173
174::
175
176  template <
177      class OtherDerived, class OtherIterator, class V, class C, class R, class D
178  >
179  typename iterator_adaptor::difference_type distance_to(
180      iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& y) const;
181
182:Returns: ``y.base() - m_iterator``
183