• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1[section:counting Counting Iterator]
2
3A `counting_iterator` adapts an object by adding an `operator*` that
4returns the current value of the object. All other iterator operations
5are forwarded to the adapted object.
6
7
8[h2 Example]
9
10
11This example fills an array with numbers and a second array with
12pointers into the first array, using `counting_iterator` for both
13tasks. Finally `indirect_iterator` is used to print out the numbers
14into the first array via indirection through the second array.
15
16    int N = 7;
17    std::vector<int> numbers;
18    typedef std::vector<int>::iterator n_iter;
19    std::copy(boost::counting_iterator<int>(0),
20              boost::counting_iterator<int>(N),
21              std::back_inserter(numbers));
22
23    std::vector<std::vector<int>::iterator> pointers;
24    std::copy(boost::make_counting_iterator(numbers.begin()),
25        boost::make_counting_iterator(numbers.end()),
26        std::back_inserter(pointers));
27
28    std::cout << "indirectly printing out the numbers from 0 to "
29        << N << std::endl;
30    std::copy(boost::make_indirect_iterator(pointers.begin()),
31        boost::make_indirect_iterator(pointers.end()),
32        std::ostream_iterator<int>(std::cout, " "));
33    std::cout << std::endl;
34
35
36The output is:
37
38[pre
39indirectly printing out the numbers from 0 to 7
400 1 2 3 4 5 6
41]
42
43The source code for this example can be found [example_link counting_iterator_example.cpp..here].
44
45[h2 Reference]
46
47
48[h3 Synopsis]
49
50  template <
51      class Incrementable
52    , class CategoryOrTraversal = use_default
53    , class Difference = use_default
54  >
55  class counting_iterator
56  {
57  public:
58      typedef Incrementable value_type;
59      typedef const Incrementable& reference;
60      typedef const Incrementable* pointer;
61      typedef /* see below */ difference_type;
62      typedef /* see below */ iterator_category;
63
64      counting_iterator();
65      counting_iterator(counting_iterator const& rhs);
66      explicit counting_iterator(Incrementable x);
67      Incrementable const& base() const;
68      reference operator*() const;
69      counting_iterator& operator++();
70      counting_iterator& operator--();
71  private:
72      Incrementable m_inc; // exposition
73  };
74
75
76If the `Difference` argument is `use_default` then
77`difference_type` is an unspecified signed integral
78type. Otherwise `difference_type` is `Difference`.
79
80`iterator_category` is determined according to the following
81algorithm:
82
83   if (CategoryOrTraversal is not use_default)
84       return CategoryOrTraversal
85   else if (numeric_limits<Incrementable>::is_specialized)
86       return |iterator-category|_\ (
87           random_access_traversal_tag, Incrementable, const Incrementable&)
88   else
89       return |iterator-category|_\ (
90            iterator_traversal<Incrementable>::type,
91            Incrementable, const Incrementable&)
92
93[blurb *Note:* implementers are encouraged to provide an implementation of
94  `operator-` and a `difference_type` that avoids overflows in
95  the cases where `std::numeric_limits<Incrementable>::is_specialized`
96  is true.]
97
98[h3 Requirements]
99
100
101The `Incrementable` argument shall be Copy Constructible and Assignable.
102
103If `iterator_category` is convertible to `forward_iterator_tag`
104or `forward_traversal_tag`, the following must be well-formed:
105
106    Incrementable i, j;
107    ++i;         // pre-increment
108    i == j;      // operator equal
109
110
111If `iterator_category` is convertible to
112`bidirectional_iterator_tag` or `bidirectional_traversal_tag`,
113the following expression must also be well-formed:
114
115    --i
116
117If `iterator_category` is convertible to
118`random_access_iterator_tag` or `random_access_traversal_tag`,
119the following must must also be valid:
120
121    counting_iterator::difference_type n;
122    i += n;
123    n = i - j;
124    i < j;
125
126
127[h3 Concepts]
128
129
130Specializations of `counting_iterator` model Readable Lvalue
131Iterator. In addition, they model the concepts corresponding to the
132iterator tags to which their `iterator_category` is convertible.
133Also, if `CategoryOrTraversal` is not `use_default` then
134`counting_iterator` models the concept corresponding to the iterator
135tag `CategoryOrTraversal`.  Otherwise, if
136`numeric_limits<Incrementable>::is_specialized`, then
137`counting_iterator` models Random Access Traversal Iterator.
138Otherwise, `counting_iterator` models the same iterator traversal
139concepts modeled by `Incrementable`.
140
141`counting_iterator<X,C1,D1>` is interoperable with
142`counting_iterator<Y,C2,D2>` if and only if `X` is
143interoperable with `Y`.
144
145
146[h3 Operations]
147
148
149In addition to the operations required by the concepts modeled by
150`counting_iterator`, `counting_iterator` provides the following
151operations.
152
153
154  counting_iterator();
155
156[*Requires: ] `Incrementable` is Default Constructible.[br]
157[*Effects: ] Default construct the member `m_inc`.
158
159
160  counting_iterator(counting_iterator const& rhs);
161
162[*Effects: ] Construct member `m_inc` from `rhs.m_inc`.
163
164
165
166  explicit counting_iterator(Incrementable x);
167
168[*Effects: ] Construct member `m_inc` from `x`.
169
170
171  reference operator*() const;
172
173[*Returns: ] `m_inc`
174
175
176  counting_iterator& operator++();
177
178[*Effects: ] `++m_inc`[br]
179[*Returns: ] `*this`
180
181
182  counting_iterator& operator--();
183
184[*Effects: ] `--m_inc`[br]
185[*Returns: ] `*this`
186
187
188  Incrementable const& base() const;
189
190[*Returns: ] `m_inc`
191
192
193[endsect]
194