}
Notes [1] This is the reason that distance is not defined for output iterators: it is impossible to compare two output iterators for equality.
[2] Forgetting to initialize n to 0 is a common mistake.
[3] The new distance interface uses the iterator_traits class, which relies on a C++ feature known as partial specialization. Many of today's compilers don't implement the complete standard; in particular, many compilers do not support partial specialization. If your compiler does not support partial specialization, then you will not be able to use the newer version of distance, or any other STL components that involve iterator_traits.
See also distance_type, advance, Input iterator, Random access iterator, Iterator tags, iterator_traits, Iterator overview.
Categories: algorithms, iterators
Component type: function
Prototype template <class InputIterator, class Distance>
void advance(InputIterator& i, Distance n);
Description Advance(i, n) increments the iterator i by the distance n . If n > 0 it is equivalent to executing ++i n times, and if n < 0 it is equivalent to executing --i n times. If n == 0 , the call has no effect.
Definition Defined in the standard header iterator, and in the nonstandard backward-compatibility header iterator.h.
Requirements on types • InputIterator is a model of Input Iterator.
• Distance is an integral type that is convertible to InputIterator's distance type.
Preconditions • i is nonsingular.
• Every iterator between i and i+n (inclusive) is nonsingular.
• If InputIterator is a model of input iterator or forward iterator, then n must be nonnegative. If InputIterator is a model of bidirectional iterator or random access iterator, then this precondition does not apply.
Complexity Constant time if InputIterator is a model of random access iterator, otherwise linear time.
Example list<int> L;
L.push_back(0);
L.push_back(1);
list<int>::iterator i = L.begin();
advance(i, 2);
assert(i == L.end());
See also distance, Input iterator, Bidirectional Iterator, Random access iterator, iterator_traits, Iterator overview.
istream_iterator<T, Distance>
Category: iterators
Component type: type
Description An istream_iterator is an Input Iterator that performs formatted input of objects of type T from a particular istream. When end of stream is reached, the istream_iterator takes on a special end of stream value, which is a past-the-end iterator. Note that all of the restrictions of an Input Iterator must be obeyed, including the restrictions on the ordering of operator* and operator++ operations.
Example Fill a vector with values read from standard input.
vector<int> V;
copy(istream_iterator<int>(cin), istream_iterator<int>(), back_inserter (V));
Definition Defined in the standard header iterator, and in the nonstandard backward-compatibility header iterator.h.
Template parameters | Parameter | Description | Default |
| T | The istream_iterator's value type. Operator* returns a const T&. | |
Distance | The istream_iterator 's distance type. |
