123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192 |
- [section:counting Counting Iterator]
- A `counting_iterator` adapts an object by adding an `operator*` that
- returns the current value of the object. All other iterator operations
- are forwarded to the adapted object.
- [h2 Example]
- This example fills an array with numbers and a second array with
- pointers into the first array, using `counting_iterator` for both
- tasks. Finally `indirect_iterator` is used to print out the numbers
- into the first array via indirection through the second array.
- int N = 7;
- std::vector<int> numbers;
- typedef std::vector<int>::iterator n_iter;
- std::copy(boost::counting_iterator<int>(0),
- boost::counting_iterator<int>(N),
- std::back_inserter(numbers));
- std::vector<std::vector<int>::iterator> pointers;
- std::copy(boost::make_counting_iterator(numbers.begin()),
- boost::make_counting_iterator(numbers.end()),
- std::back_inserter(pointers));
- std::cout << "indirectly printing out the numbers from 0 to "
- << N << std::endl;
- std::copy(boost::make_indirect_iterator(pointers.begin()),
- boost::make_indirect_iterator(pointers.end()),
- std::ostream_iterator<int>(std::cout, " "));
- std::cout << std::endl;
- The output is:
- indirectly printing out the numbers from 0 to 7
- 0 1 2 3 4 5 6
- The source code for this example can be found [@../example/counting_iterator_example.cpp here].
- [h2 Reference]
- [h3 Synopsis]
- template <
- class Incrementable
- , class CategoryOrTraversal = use_default
- , class Difference = use_default
- >
- class counting_iterator
- {
- public:
- typedef Incrementable value_type;
- typedef const Incrementable& reference;
- typedef const Incrementable* pointer;
- typedef /* see below */ difference_type;
- typedef /* see below */ iterator_category;
- counting_iterator();
- counting_iterator(counting_iterator const& rhs);
- explicit counting_iterator(Incrementable x);
- Incrementable const& base() const;
- reference operator*() const;
- counting_iterator& operator++();
- counting_iterator& operator--();
- private:
- Incrementable m_inc; // exposition
- };
- If the `Difference` argument is `use_default` then
- `difference_type` is an unspecified signed integral
- type. Otherwise `difference_type` is `Difference`.
- `iterator_category` is determined according to the following
- algorithm:
- if (CategoryOrTraversal is not use_default)
- return CategoryOrTraversal
- else if (numeric_limits<Incrementable>::is_specialized)
- return |iterator-category|_\ (
- random_access_traversal_tag, Incrementable, const Incrementable&)
- else
- return |iterator-category|_\ (
- iterator_traversal<Incrementable>::type,
- Incrementable, const Incrementable&)
-
- [blurb *Note:* implementers are encouraged to provide an implementation of
- `operator-` and a `difference_type` that avoids overflows in
- the cases where `std::numeric_limits<Incrementable>::is_specialized`
- is true.]
- [h3 Requirements]
- The `Incrementable` argument shall be Copy Constructible and Assignable.
- If `iterator_category` is convertible to `forward_iterator_tag`
- or `forward_traversal_tag`, the following must be well-formed:
- Incrementable i, j;
- ++i; // pre-increment
- i == j; // operator equal
- If `iterator_category` is convertible to
- `bidirectional_iterator_tag` or `bidirectional_traversal_tag`,
- the following expression must also be well-formed:
- --i
- If `iterator_category` is convertible to
- `random_access_iterator_tag` or `random_access_traversal_tag`,
- the following must must also be valid:
- counting_iterator::difference_type n;
- i += n;
- n = i - j;
- i < j;
- [h3 Concepts]
- Specializations of `counting_iterator` model Readable Lvalue
- Iterator. In addition, they model the concepts corresponding to the
- iterator tags to which their `iterator_category` is convertible.
- Also, if `CategoryOrTraversal` is not `use_default` then
- `counting_iterator` models the concept corresponding to the iterator
- tag `CategoryOrTraversal`. Otherwise, if
- `numeric_limits<Incrementable>::is_specialized`, then
- `counting_iterator` models Random Access Traversal Iterator.
- Otherwise, `counting_iterator` models the same iterator traversal
- concepts modeled by `Incrementable`.
- `counting_iterator<X,C1,D1>` is interoperable with
- `counting_iterator<Y,C2,D2>` if and only if `X` is
- interoperable with `Y`.
- [h3 Operations]
- In addition to the operations required by the concepts modeled by
- `counting_iterator`, `counting_iterator` provides the following
- operations.
- counting_iterator();
- [*Requires: ] `Incrementable` is Default Constructible.[br]
- [*Effects: ] Default construct the member `m_inc`.
- counting_iterator(counting_iterator const& rhs);
- [*Effects: ] Construct member `m_inc` from `rhs.m_inc`.
- explicit counting_iterator(Incrementable x);
- [*Effects: ] Construct member `m_inc` from `x`.
- reference operator*() const;
- [*Returns: ] `m_inc`
- counting_iterator& operator++();
- [*Effects: ] `++m_inc`[br]
- [*Returns: ] `*this`
- counting_iterator& operator--();
- [*Effects: ] `--m_inc`[br]
- [*Returns: ] `*this`
- Incrementable const& base() const;
- [*Returns: ] `m_inc`
- [endsect]
|