24 Iterators library [iterators]

24.2 Iterator requirements [iterator.requirements]

24.2.3 Input iterators [input.iterators]

A class or pointer type X satisfies the requirements of an input iterator for the value type T if X satisfies the Iterator ([iterator.iterators]) and EqualityComparable (Table [equalitycomparable]) requirements and the expressions in Table [tab:iterator.input.requirements] are valid and have the indicated semantics.

In Table [tab:iterator.input.requirements], 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 107 — Input iterator requirements (in addition to Iterator)
ExpressionReturn typeOperationalAssertion/note
semanticspre-/post-condition
a != b contextually convertible to bool !(a == b) pre: (a,b) is in the domain of ==.
*a convertible to T pre: 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 pre: a is dereferenceable.
++r X& pre: r is dereferenceable.
post: r is dereferenceable or r is past-the-end.
post: any copies of the previous value of r are no longer required either to be dereferenceable or 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 CopyAssignable type (Table [copyassignable]). These algorithms can be used with istreams as the source of the input data through the istream_iterator class template.  — end note ]