[input.iterators] (original) (raw)
24 Iterators library [iterators]
24.3 Iterator requirements [iterator.requirements]
24.3.5 C++17 iterator requirements [iterator.cpp17]
24.3.5.3 Input iterators [input.iterators]
A class or pointer typeXmeets the requirements of an input iterator for the value typeTifX meets the Cpp17Iterator ([iterator.iterators]) and_Cpp17EqualityComparable_ (Table 28) requirements and the expressions in Table 77 are valid and have the indicated semantics.
In Table 77, 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 1:
The call find(a,b,x)is defined only if the value of ahas the property _p_defined as follows:b has property _p_and a value ihas property p_if (*i==x) or if (*i!=xand++ihas property_p).
— _end example_]
Table 77 — Cpp17InputIterator requirements (in addition to Cpp17Iterator) [tab:inputiterator]
| 🔗Expression | Return type | Operational | Assertion/note |
|---|---|---|---|
| 🔗 | semantics | pre-/post-condition | |
| 🔗a != b | decltype(a != b) models boolean-testable | !(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; } |
Recommended practice: The implementation of an algorithm on input iterators should never attempt to pass through the same iterator twice; such an algorithm should be a single pass algorithm.
[Note 1:
For input iterators, a == b does not imply ++a == ++b.
(Equality does not guarantee the substitution property or referential transparency.)
Value type T is not required to be a Cpp17CopyAssignable type (Table 34).
Such an algorithm can be used with istreams as the source of the input data through theistream_iteratorclass template.
— _end note_]