[forward.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.4 Forward iterators [forward.iterators]

A class or pointer typeXmeets the requirements of a forward iterator if

• X meets the Cpp17InputIterator requirements ([input.iterators]),
• X meets the Cpp17DefaultConstructiblerequirements ([utility.arg.requirements]),
• if X is a mutable iterator, reference is a reference to T; if X is a constant iterator, reference is a reference to const T,
• the expressions in Table 87are valid and have the indicated semantics, and
• objects of type X offer the multi-pass guarantee, described below.

The domain of == for forward iterators is that of iterators over the same underlying sequence.

However, value-initialized iterators may be compared and shall compare equal to other value-initialized iterators of the same type.

[ Note

:

Value-initialized iterators behave as if they refer past the end of the same empty sequence.

— end note

]

Two dereferenceable iterators a and b of type X offer themulti-pass guarantee if:

• a == b implies ++a == ++b and
• X is a pointer type or the expression(void)++X(a), *a is equivalent to the expression *a.

[ Note

:

The requirement thata == bimplies++a == ++b(which is not true for input and output iterators) and the removal of the restrictions on the number of the assignments through a mutable iterator (which applies to output iterators) allows the use of multi-pass one-directional algorithms with forward iterators.

— end note

]

Table 87: Cpp17ForwardIterator requirements (in addition to Cpp17InputIterator) [tab:forwarditerator]

If a and b are equal, then either a and bare both dereferenceable or else neither is dereferenceable.

If a and b are both dereferenceable, then a == bif and only if*a and *b are bound to the same object.