C++ named requirements: LegacyForwardIterator - cppreference.com (original) (raw)

A LegacyForwardIterator is a LegacyIterator that can read data from the pointed-to element.

Unlike LegacyInputIterator and LegacyOutputIterator, it can be used in multipass algorithms.

If a LegacyForwardIterator it originates from a Container, then it's value type is the same as the container's, so dereferencing (*it) obtains the container's value type.

[edit] Requirements

Type	Definition
X	A forward iterator type
T	The value type of X (i.e. std::iterator_traits<X>::value_type)
Ref	std::iterator_traits<X>::reference
Value	Definition
i, j	Values of type X or const X
r	A value of type X&

X satisfies LegacyForwardIterator if all following conditions are satisfied:

X satisfies LegacyInputIterator.
X satisfies DefaultConstructible.
If X is a mutable iterator, Ref is a reference to T.
If X is a constant iterator, Ref is a reference to const T.
Objects of the type X provide multi-pass guarantee.
If i and j are equal, then either i and j are both dereferenceable or else neither is dereferenceable.
If i and j are both dereferenceable, then i == j if and only if *i and *j are bound to the same object.
The following expressions must be valid and have their specified effects:

Expression	Type	Effects
r++	convertible to const X&	Equivalent to X x = r;++r;return x;.
*i++	Ref

[edit] Equality domain

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

However, value-initialized forward iterators can be compared, and must compare equal to other value-initialized iterators of the same type.In other words, value-initialized forward iterators behave as if they refer past the end of the same empty sequence.	(since C++14)

[edit] Multi-pass guarantee

Two dereferenceable iterators a and b of type X offer the multi-pass guarantee if all following conditions are satisfied:

a == b implies ++a == ++b.
Any of the following conditions is satisfied:
X is a pointer type.
The expression (void)++X(a), *a is equivalent to the expression *a.

Concept For the definition of std::iterator_traits, the following exposition-only concept is defined. where the exposition-only concept __LegacyInputIterator is described in LegacyInputIterator.	(since C++20)

[edit] Notes

Unlike the std::forward_iterator concept, the LegacyForwardIterator requirements requires dereference to return a reference.

[edit] Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DR	Applied to	Behavior as published	Correct behavior
LWG 1212(N3066)	C++98	the type of i++ did not match the type ofi-- required by LegacyBidirectionalIterator	changed thetype to Ref
LWG 1311(N3066)	C++98	“a == b implies ++a == ++b” alonedid not offer multipass guarantee[1]	also requires “a == bimplies ++a != b”[2]
LWG 3798	C++20	__LegacyForwardIterator requiredstd::iter_reference_t<It> to be an lvalue reference type	also allows rvaluereference types

↑ In the scenario where a and b use the same underlying iterator, evaluating the expression ++a == ++b actually increments the underlying container twice, but the result is still true.
↑ Formally also requires implying ++b != a.