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 type X meets the requirements of an input iterator for the value type T if X meets the Cpp17Iterator ([iterator.iterators]) and Cpp17EqualityComparable (Table 25) requirements and the expressions in Table 85 are valid and have the indicated semantics.

In Table 85, the term the 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 a has the property p defined as follows: b has property p and a value i has property p if (*i==x) or if (*i!=x and ++i has property p).

— 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 == b does 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 be single pass algorithms.

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 the istream_iterator class template.

— end note

]