Category: iterators
Component type: concept
An Input Iterator is an iterator that may be dereferenced to refer to some object, and that may be incremented to obtain the next iterator in a sequence. Input Iterators are not required to be mutable.
| Value type | The type of the value obtained by dereferencing an Input Iterator |
| Distance type | A signed integral type used to represent the distance from one iterator to another, or the number of elements in a range. |
X | A type that is a model of Input Iterator |
T | The value type of X |
i, j | Object of type X |
t | Object of type T |
An iterator is past-the-end if it points beyond the last element of a container. Past-the-end values are nonsingular and nondereferenceable.
An iterator is valid if it is dereferenceable or past-the-end.
An iterator i is incrementable if there is a "next" iterator, that is, if ++i is well-defined. Past-the-end iterators are not incrementable.
An Input Iterator j is reachable from an Input Iterator i if, after applying operator++ to i a finite number of times, i == j. [1]
The notation [i,j) refers to a range of iterators beginning with i and up to but not including j.
The range [i,j) is a valid range if both i and j are valid iterators, and j is reachable from i [2].
In addition to the expressions defined in Trivial Iterator, the following expressions must be valid.
| Name | Expression | Type requirements | Return type |
|---|---|---|---|
| Preincrement | ++i | X& | |
| Postincrement | (void)i++ | ||
| Postincrement and dereference | *i++ | T |
| Name | Expression | Precondition | Semantics | Postcondition |
|---|---|---|---|---|
| Dereference | *i | i is incrementable | ||
| Preincrement | ++i | i is dereferenceable | i is dereferenceable or past-the-end [3] [4] | |
| Postincrement | (void)i++ | i is dereferenceable | Equivalent to (void)++i | i is dereferenceable or past-the-end [3] [4] |
| Postincrement and dereference | *i++ | i is dereferenceable | Equivalent to {T t = *i; ++i; return t;} | i is dereferenceable or past-the-end [3] [4] |
All operations are amortized constant time.
[1] i == j does not imply ++i == ++j.
[2] Every iterator in a valid range [i, j) is dereferenceable, and j is either dereferenceable or past-the-end. The fact that every iterator in the range is dereferenceable follows from the fact that incrementable iterators must be dereferenceable.
[3] After executing ++i, it is not required that copies of the old value of i be dereferenceable or that they be in the domain of operator==.
[4] It is not guaranteed that it is possible to pass through the same input iterator twice.
Input Iterator, Output Iterator, Forward Iterator, Bidirectional Iterator, Bidirectional Iterator LOGN, Random Access Iterator, Random Access Iterator LOGN, Arbitrary Access Iterator LOGN, Forward Arbitrary Access Iterator, Forward Arbitrary Access Iterator LOGN, Reverse Arbitrary Access Iterator, Reverse Arbitrary Access Iterator LOGN, Iterator Overview
1.7.3
