|
| |
|
| Category: iterators | | Component type: concept |
Description
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.
Refinement of
trivial.
Associated types
| 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. |
Notation
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 |
Definitions
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].
Valid expressions
In addition to the expressions defined in trivial, the following expressions must be valid.
| Name | Expression | Type requirements | Return type |
| Preincrement | ++i | | X& |
| Postincrement | (void)i++ | | |
| Postincrement and dereference | *i++ | | T |
Expression semantics
| Name | Expression | Precondition | Semantics | Postcondition |
| Dereference | *t | 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] |
Complexity guarantees
All operations are amortized constant time.
Invariants
Models
Notes
[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 deferenceable.
[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.
See also
OutputIterator, Iterators
