# C++ named requirements: LegacyForwardIterator

From cppreference.com
< cpp‎ | named req

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

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

### Requirements

The type `It` satisfies LegacyForwardIterator if

- The type `It` satisfies LegacyInputIterator
- The type `It` satisfies DefaultConstructible
- Objects of the type `It` provide multipass guarantee described below
- The type `std::iterator_traits<It>::reference` must be exactly

  - `T&` if `It` satisfies LegacyOutputIterator (`It` is mutable)
  - `const T&` otherwise (`It` is constant),
  (where `T` is the type denoted by std::iterator_traits<It>::value_type)

- Equality and inequality comparison is defined over all iterators for the same underlying sequence and the value initialized-iterators (since C++14).

And, given

- `i`, dereferenceable iterator of type `It`
- `reference,` the type denoted by `std::iterator_traits<It>::reference`

The following expressions must be valid and have their specified effects

Expression | Return type | Equivalent expression | Notes
--- | --- | --- | ---
i++ | It | It ip=i; ++i; return ip; |
*i++ | reference |  |

A mutable LegacyForwardIterator is a LegacyForwardIterator that additionally satisfies the LegacyOutputIterator requirements.

### Multipass guarantee

Given `a` and `b`, dereferenceable iterators of type `It`

- If `a` and `b` compare equal (`a == b` is contextually convertible to `true`) then either they are both non-dereferenceable or `*a` and `*b` are references bound to the same object
- If `*a` and `*b` refer to the same object, then `a` == `b`.
- Assignment through a mutable `ForwardIterator` iterator cannot invalidate the iterator (implicit due to `reference` defined as a true reference)
- incrementing a copy of `a` does not change the value read from `a` (formally, either `It` is a raw pointer type or the expression (void)++It(a), *a is equivalent to the expression *a)
- `a == b` implies `++a == ++b`

### Singular iterators

A value-initialized LegacyForwardIterator behaves like the past-the-end iterator of some unspecified empty container: it compares equal to all value-initialized LegacyForwardIterators of the same type.

(since C++14)

### Concept

For the definition of std::iterator_traits, the following exposition-only concept is defined.

template<class I> concept __LegacyForwardIterator = __LegacyInputIterator<I> && std::Constructible<I> && std::is_lvalue_reference_v<std::iter_reference_t<I>> && std::Same<std::remove_cvref_t<std::iter_reference_t<I>>, typename std::readable_traits<I>::value_type> && requires(I i) { { i++ } -> const I&; { *i++ } -> std::Same<std::iter_reference_t<I>>; }; |  |

where the exposition-only concept `__LegacyInputIterator<T>` is described in LegacyInputIterator#Concept.

(since C++20)

### See also

ForwardIterator | specifies that an `InputIterator` is a forward iterator, supporting equality comparison and multi-pass (concept)

- Iterator library

Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/named_req/ForwardIterator&oldid=109808"