PageRenderTime 69ms CodeModel.GetById 57ms app.highlight 8ms RepoModel.GetById 1ms app.codeStats 0ms

/Src/Dependencies/Boost/libs/iterator/doc/transform_iterator_ref.rst

http://hadesmem.googlecode.com/
ReStructuredText | 175 lines | 120 code | 55 blank | 0 comment | 0 complexity | f4538b4f3005f356dfc9f8687c58baed MD5 | raw file
  1.. Copyright David Abrahams 2006. 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.3 of this document was accepted for TR1
  6
  7::
  8
  9  template <class UnaryFunction,
 10            class Iterator, 
 11            class Reference = use_default, 
 12            class Value = use_default>
 13  class transform_iterator
 14  {
 15  public:
 16    typedef /* see below */ value_type;
 17    typedef /* see below */ reference;
 18    typedef /* see below */ pointer;
 19    typedef iterator_traits<Iterator>::difference_type difference_type;
 20    typedef /* see below */ iterator_category;
 21
 22    transform_iterator();
 23    transform_iterator(Iterator const& x, UnaryFunction f);
 24
 25    template<class F2, class I2, class R2, class V2>
 26    transform_iterator(
 27          transform_iterator<F2, I2, R2, V2> const& t
 28        , typename enable_if_convertible<I2, Iterator>::type* = 0      // exposition only
 29        , typename enable_if_convertible<F2, UnaryFunction>::type* = 0 // exposition only
 30    );
 31    UnaryFunction functor() const;
 32    Iterator const& base() const;
 33    reference operator*() const;
 34    transform_iterator& operator++();
 35    transform_iterator& operator--();
 36  private:
 37    Iterator m_iterator; // exposition only
 38    UnaryFunction m_f;   // exposition only
 39  };
 40
 41
 42If ``Reference`` is ``use_default`` then the ``reference`` member of
 43``transform_iterator`` is
 44``result_of<UnaryFunction(iterator_traits<Iterator>::reference)>::type``.
 45Otherwise, ``reference`` is ``Reference``.
 46
 47If ``Value`` is ``use_default`` then the ``value_type`` member is
 48``remove_cv<remove_reference<reference> >::type``.  Otherwise,
 49``value_type`` is ``Value``.
 50
 51
 52If ``Iterator`` models Readable Lvalue Iterator and if ``Iterator``
 53models Random Access Traversal Iterator, then ``iterator_category`` is
 54convertible to ``random_access_iterator_tag``. Otherwise, if
 55``Iterator`` models Bidirectional Traversal Iterator, then
 56``iterator_category`` is convertible to
 57``bidirectional_iterator_tag``.  Otherwise ``iterator_category`` is
 58convertible to ``forward_iterator_tag``. If ``Iterator`` does not
 59model Readable Lvalue Iterator then ``iterator_category`` is
 60convertible to ``input_iterator_tag``.
 61
 62
 63``transform_iterator`` requirements
 64...................................
 65
 66The type ``UnaryFunction`` must be Assignable, Copy Constructible, and
 67the expression ``f(*i)`` must be valid where ``f`` is an object of
 68type ``UnaryFunction``, ``i`` is an object of type ``Iterator``, and
 69where the type of ``f(*i)`` must be
 70``result_of<UnaryFunction(iterator_traits<Iterator>::reference)>::type``.
 71
 72The argument ``Iterator`` shall model Readable Iterator.  
 73
 74
 75``transform_iterator`` models
 76.............................
 77
 78The resulting ``transform_iterator`` models the most refined of the
 79following that is also modeled by ``Iterator``.
 80
 81  * Writable Lvalue Iterator if ``transform_iterator::reference`` is a non-const reference. 
 82
 83  * Readable Lvalue Iterator if ``transform_iterator::reference`` is a const reference.
 84
 85  * Readable Iterator otherwise. 
 86
 87The ``transform_iterator`` models the most refined standard traversal
 88concept that is modeled by the ``Iterator`` argument.
 89
 90If ``transform_iterator`` is a model of Readable Lvalue Iterator then
 91it models the following original iterator concepts depending on what
 92the ``Iterator`` argument models.
 93
 94+-----------------------------------+---------------------------------------+
 95| If ``Iterator`` models            | then ``transform_iterator`` models    |
 96+===================================+=======================================+
 97| Single Pass Iterator              | Input Iterator                        |
 98+-----------------------------------+---------------------------------------+
 99| Forward Traversal Iterator        | Forward Iterator                      |
100+-----------------------------------+---------------------------------------+
101| Bidirectional Traversal Iterator  | Bidirectional Iterator                |
102+-----------------------------------+---------------------------------------+
103| Random Access Traversal Iterator  | Random Access Iterator                |
104+-----------------------------------+---------------------------------------+
105
106If ``transform_iterator`` models Writable Lvalue Iterator then it is a
107mutable iterator (as defined in the old iterator requirements).
108
109``transform_iterator<F1, X, R1, V1>`` is interoperable with
110``transform_iterator<F2, Y, R2, V2>`` if and only if ``X`` is
111interoperable with ``Y``.
112
113
114
115``transform_iterator`` operations
116.................................
117
118In addition to the operations required by the concepts modeled by
119``transform_iterator``, ``transform_iterator`` provides the following
120operations.
121
122
123``transform_iterator();``
124
125:Returns: An instance of ``transform_iterator`` with ``m_f``
126  and ``m_iterator`` default constructed.
127
128
129``transform_iterator(Iterator const& x, UnaryFunction f);``
130
131:Returns: An instance of ``transform_iterator`` with ``m_f``
132  initialized to ``f`` and ``m_iterator`` initialized to ``x``.
133
134
135::
136
137    template<class F2, class I2, class R2, class V2>
138    transform_iterator(
139          transform_iterator<F2, I2, R2, V2> const& t
140        , typename enable_if_convertible<I2, Iterator>::type* = 0      // exposition only
141        , typename enable_if_convertible<F2, UnaryFunction>::type* = 0 // exposition only
142    );
143
144:Returns: An instance of ``transform_iterator`` with ``m_f``
145  initialized to ``t.functor()`` and ``m_iterator`` initialized to
146  ``t.base()``.
147:Requires: ``OtherIterator`` is implicitly convertible to ``Iterator``.
148
149
150``UnaryFunction functor() const;``
151
152:Returns: ``m_f``
153
154
155``Iterator const& base() const;``
156
157:Returns: ``m_iterator``
158
159
160``reference operator*() const;``
161
162:Returns: ``m_f(*m_iterator)``
163
164
165``transform_iterator& operator++();``
166
167:Effects: ``++m_iterator``
168:Returns: ``*this``
169
170
171``transform_iterator& operator--();``
172
173:Effects: ``--m_iterator``
174:Returns: ``*this``
175