[input.iterators] (original) (raw)
23 Iterators library [iterators]
23.3 Iterator requirements [iterator.requirements]
23.3.5 C++17 iterator requirements [iterator.cpp17]
23.3.5.2 Input iterators [input.iterators]
A class or pointer typeXmeets the requirements of an input iterator for the value typeTifX meets the Cpp17Iterator ([iterator.iterators]) andCpp17EqualityComparable (Table 25) requirements and the expressions in Table 85 are valid and have the indicated semantics.
In Table 85, the termthe domain of ==is used in the ordinary mathematical sense to denote the set of values over which== is (required to be) defined.
This set can change over time.
Each algorithm places additional requirements on the domain of== for the iterator values it uses.
These requirements can be inferred from the uses that algorithm makes of == and !=.
[ Example
:
The call find(a,b,x)is defined only if the value of ahas the property pdefined as follows:b has property pand a value ihas property pif (*i==x) or if (*i!=xand++ihas propertyp).
— end example
]
Table 85: Cpp17InputIterator requirements (in addition to Cpp17Iterator) [tab:inputiterator]
| Expression | Return type | Operational | Assertion/note |
|---|---|---|---|
| semantics | pre-/post-condition | ||
| a != b | contextually convertible to bool | !(a == b) | Preconditions: (a, b) is in the domain of ==. |
| *a | reference, convertible to T | Preconditions: a is dereferenceable. The expression(void)*a, *a is equivalent to *a. If a == b and (a, b) is in the domain of == then *a is equivalent to *b. | |
| a->m | (*a).m | Preconditions: a is dereferenceable. | |
| ++r | X& | Preconditions: r is dereferenceable. Postconditions: r is dereferenceable or r is past-the-end; any copies of the previous value of r are no longer required to be dereferenceable nor to be in the domain of ==. | |
| (void)r++ | equivalent to (void)++r | ||
| *r++ | convertible to T | { T tmp = *r; ++r; return tmp; } |
[ Note
:
For input iterators,a == bdoes not imply++a == ++b.
(Equality does not guarantee the substitution property or referential transparency.)
Algorithms on input iterators should never attempt to pass through the same iterator twice.
They should besingle passalgorithms.
Value type T is not required to be a Cpp17CopyAssignable type (Table 31).
These algorithms can be used with istreams as the source of the input data through theistream_iteratorclass template.
— end note
]