C++ named requirements: LegacyForwardIterator

A LegacyForwardIterator is a LegacyIterator

Unlike LegacyInputIterator and LegacyOutputIterator

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

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
• If i and j are both dereferenceable, then i == j if and only if *i and *j
• 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

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)

Multi-pass guarantee

Two dereferenceable iterators a and b of type X offer the multi-pass guarantee

• 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. template < class It> concept __LegacyForwardIterator =     __LegacyInputIterator<It> && std::constructible_from <It> && std::is_reference_v < std::iter_reference_t <It>> && std::same_as < std::remove_cvref_t < std::iter_reference_t <It>>, typename std::indirectly_readable_traits <It> :: value_type > &&     requires(It it) { {  it++ } - > std::convertible_to < const It& > ; { *it++ } - > std::same_as < std::iter_reference_t <It>> ; } ; where the exposition-only concept __LegacyInputIterator<T> is described in LegacyInputIterator.

(since C++20)

Notes

Unlike the std::forward_iterator concept, the LegacyForwardIterator

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 of *i-- required by LegacyBidirectionalIterator	changed the type to Ref
LWG 1311 (N3066)	C++98	“a == b implies ++a == ++b” alone did not offer multipass guarantee[1]	also requires “a == b implies ++a != b”[2]
LWG 3798	C++20	__LegacyForwardIterator required std::iter_reference_t<It>	also allows rvalue reference types

1. ↑ 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
2. ↑ Formally also requires implying ++b != a.

See also

forward_iterator (C++20)	specifies that an input_iterator is a forward iterator, supporting equality comparison and multi-pass (concept)
Iterator library	provides definitions for iterators, iterator traits, adaptors, and utility functions