C++ named requirements: LegacyForwardIterator

 

C++

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)

Metaprogramming library (C++11)

Diagnostics library

General utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Numerics library

Localizations library

Input/output library

Filesystem library (C++17)

Regular expressions library (C++11)

Concurrency support library (C++11)

Execution support library (C++26)

Technical specifications

Symbols index

External libraries

 

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) Concurrency BasicLockable (C++11) Lockable (C++11) TimedLockable (C++11) SharedLockable (C++14) SharedTimedLockable (C++14) Mutex (C++11) TimedMutex (C++11) SharedMutex (C++17) SharedTimedMutex (C++14) Ranges RangeAdaptorObject (C++20) RangeAdaptorClosureObject (C++20) Multidimensional View LayoutMapping (C++23) LayoutMappingPolicy (C++23) AccessorPolicy (C++23) Other CharTraits RegexTraits (C++11)   BitmaskType LiteralType (C++11) NumericType UnaryTypeTrait (C++11) BinaryTypeTrait (C++11) TransformationTrait (C++11) Clock (C++11) TrivialClock (C++11)

 

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.

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

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 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. 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 requirements requires dereference to return a reference.

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	also requires “a == b implies ++a != b”
LWG 3798	C++20	__LegacyForwardIterator required std::iter_reference_t<It> to be an lvalue reference type	also allows rvalue reference types

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