PageRenderTime 25ms CodeModel.GetById 14ms app.highlight 7ms RepoModel.GetById 1ms app.codeStats 0ms

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

http://hadesmem.googlecode.com/
ReStructuredText | 149 lines | 102 code | 47 blank | 0 comment | 0 complexity | 649fd281b7a4ef6db9ba8eefb3395bc3 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::
  6
  7  template <
  8      class Incrementable
  9    , class CategoryOrTraversal = use_default
 10    , class Difference = use_default
 11  >
 12  class counting_iterator
 13  {
 14  public:
 15      typedef Incrementable value_type;
 16      typedef const Incrementable& reference;
 17      typedef const Incrementable* pointer;
 18      typedef /* see below */ difference_type;
 19      typedef /* see below */ iterator_category;
 20
 21      counting_iterator();
 22      counting_iterator(counting_iterator const& rhs);
 23      explicit counting_iterator(Incrementable x);
 24      Incrementable const& base() const;
 25      reference operator*() const;
 26      counting_iterator& operator++();
 27      counting_iterator& operator--();
 28  private:
 29      Incrementable m_inc; // exposition
 30  };
 31
 32
 33If the ``Difference`` argument is ``use_default`` then
 34``difference_type`` is an unspecified signed integral
 35type. Otherwise ``difference_type`` is ``Difference``.
 36
 37``iterator_category`` is determined according to the following
 38algorithm:
 39
 40.. parsed-literal::
 41
 42   if (CategoryOrTraversal is not use_default)
 43       return CategoryOrTraversal
 44   else if (numeric_limits<Incrementable>::is_specialized)
 45       return |iterator-category|_\ (
 46           random_access_traversal_tag, Incrementable, const Incrementable&)
 47   else
 48       return |iterator-category|_\ (
 49            iterator_traversal<Incrementable>::type, 
 50            Incrementable, const Incrementable&)
 51        
 52[*Note:* implementers are encouraged to provide an implementation of
 53  ``operator-`` and a ``difference_type`` that avoids overflows in
 54  the cases where ``std::numeric_limits<Incrementable>::is_specialized``
 55  is true.]
 56
 57``counting_iterator`` requirements
 58..................................
 59
 60The ``Incrementable`` argument shall be Copy Constructible and Assignable.
 61
 62If ``iterator_category`` is convertible to ``forward_iterator_tag``
 63or ``forward_traversal_tag``, the following must be well-formed::
 64
 65    Incrementable i, j;
 66    ++i;         // pre-increment
 67    i == j;      // operator equal
 68
 69
 70If ``iterator_category`` is convertible to
 71``bidirectional_iterator_tag`` or ``bidirectional_traversal_tag``,
 72the following expression must also be well-formed::
 73
 74    --i
 75
 76If ``iterator_category`` is convertible to
 77``random_access_iterator_tag`` or ``random_access_traversal_tag``,
 78the following must must also be valid::
 79
 80    counting_iterator::difference_type n;
 81    i += n;
 82    n = i - j;
 83    i < j;
 84
 85``counting_iterator`` models
 86............................
 87
 88Specializations of ``counting_iterator`` model Readable Lvalue
 89Iterator. In addition, they model the concepts corresponding to the
 90iterator tags to which their ``iterator_category`` is convertible.
 91Also, if ``CategoryOrTraversal`` is not ``use_default`` then
 92``counting_iterator`` models the concept corresponding to the iterator
 93tag ``CategoryOrTraversal``.  Otherwise, if
 94``numeric_limits<Incrementable>::is_specialized``, then
 95``counting_iterator`` models Random Access Traversal Iterator.
 96Otherwise, ``counting_iterator`` models the same iterator traversal
 97concepts modeled by ``Incrementable``.
 98
 99``counting_iterator<X,C1,D1>`` is interoperable with
100``counting_iterator<Y,C2,D2>`` if and only if ``X`` is
101interoperable with ``Y``.
102
103
104
105``counting_iterator`` operations
106................................
107
108In addition to the operations required by the concepts modeled by
109``counting_iterator``, ``counting_iterator`` provides the following
110operations.
111
112
113``counting_iterator();``
114
115:Requires: ``Incrementable`` is Default Constructible.
116:Effects: Default construct the member ``m_inc``.
117
118
119``counting_iterator(counting_iterator const& rhs);``
120
121:Effects: Construct member ``m_inc`` from ``rhs.m_inc``.
122
123
124
125``explicit counting_iterator(Incrementable x);``
126
127:Effects: Construct member ``m_inc`` from ``x``.
128
129
130``reference operator*() const;``
131
132:Returns: ``m_inc``
133
134
135``counting_iterator& operator++();``
136
137:Effects: ``++m_inc``
138:Returns: ``*this``
139
140
141``counting_iterator& operator--();``
142
143:Effects: ``--m_inc``
144:Returns: ``*this``  
145
146
147``Incrementable const& base() const;``
148
149:Returns: ``m_inc``