C++ named requirements:LegacyForwardIterator

From cppreference.com

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros(C++20)
Language support library
Concepts library(C++20)
Diagnostics library
Memory management library
Metaprogramming library(C++11)
General utilities library
Containers library
Iterators library
Ranges library(C++20)
Algorithms library
Strings library
Text processing library
Numerics library
Date and time library
Input/output library
Filesystem library(C++17)
Concurrency support library(C++11)
Execution control library(C++26)
Technical specifications
Symbols index
External libraries

[edit]

C++ named requirements

Basic
DefaultConstructible
MoveConstructible (C++11)
CopyConstructible
CopyAssignable
MoveAssignable (C++11)
Destructible
Type properties
ScalarType
PODType
TriviallyCopyable (C++11)
TrivialType (C++11)
StandardLayoutType (C++11)
ImplicitLifetimeType
Library-wide
BooleanTestable
EqualityComparable
LessThanComparable
Swappable
ValueSwappable (C++11)
NullablePointer (C++11)
Hash (C++11)
Allocator
FunctionObject
Callable
Predicate
BinaryPredicate
Compare

Container
Container
ReversibleContainer
AllocatorAwareContainer
SequenceContainer
ContiguousContainer (C++17)
AssociativeContainer
UnorderedAssociativeContainer (C++11)
Container element
DefaultInsertable (C++11)
CopyInsertable (C++11)
MoveInsertable (C++11)
EmplaceConstructible (C++11)
Erasable (C++11)
Iterator
LegacyIterator
LegacyInputIterator
LegacyOutputIterator
LegacyForwardIterator
LegacyBidirectionalIterator
LegacyRandomAccessIterator
LegacyContiguousIterator (C++17)
ConstexprIterator (C++20)
Stream I/O
FormattedInputFunction
UnformattedInputFunction
FormattedOutputFunction
UnformattedOutputFunction
Formatters
BasicFormatter (C++20)
Formatter (C++20)

Random Numbers

SeedSequence

(C++11)

RandomNumberEngine

(C++11)

RandomNumberDistribution

(C++11)

UniformRandomBitGenerator

(C++11)

RandomNumberEngineAdaptor

(C++11)

(C++11)

(C++11)

(C++11)

(C++14)

(C++14)

(C++11)

(C++11)

(C++17)

(C++14)

(C++20)

RangeAdaptorClosureObject

(C++20)

Multidimensional View

(C++23)

(C++23)

(C++23)

CharTraits
RegexTraits (C++11)
BitmaskType
LiteralType (C++11)
NumericType

UnaryTypeTrait (C++11)
BinaryTypeTrait (C++11)
TransformationTrait (C++11)
Clock (C++11)
TrivialClock (C++11)

[edit]

ALegacyForwardIterator is aLegacyIterator that can read data from the pointed-to element.

UnlikeLegacyInputIterator andLegacyOutputIterator, it can be used in multipass algorithms.

If aLegacyForwardIteratorit originates from aContainer, thenit'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`	Thevalue 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` orconst X
r	A value of type`X&`

X satisfiesLegacyForwardIterator if all following conditions are satisfied:

X satisfiesLegacyInputIterator.
X satisfiesDefaultConstructible.
IfX is amutable iterator,Ref is a reference toT.
IfX is a constant iterator,Ref is a reference toconst T.
Objects of the typeX providemulti-pass guarantee.
Ifi andj are equal, then eitheri andj are bothdereferenceable or else neither is dereferenceable.
Ifi andj are both dereferenceable, theni== 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 toconst X&	Equivalent toX x= r; ++r; return x;.
*i++	`Ref`

[edit]Equality domain

Thedomain of== for forward iterators is that of iterators over the sameunderlying 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 iteratorsa andb of typeX offer themulti-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 ofstd::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>>, typenamestd::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 inLegacyInputIterator.

(since C++20)

[edit]Notes

Unlike thestd::forward_iterator concept, theLegacyForwardIterator 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 ofi++ did not match the type of i-- required byLegacyBidirectionalIterator	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> to be an lvalue reference type	also allows rvalue reference types

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

[edit]See also

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