# C++ named requirements: LegacyForwardIterator

> C++ Atlas: `cppatlas.com/w/cpp/named_req/ForwardIterator` | Source: https://en.cppreference.com/w/cpp/named_req/ForwardIterator | Domain: Named Requirements | Standards: C++14, C++20

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

## Official Specification Summary (cppreference)

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.

(since C++14):

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.

### 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`.

(since C++20):

### Concept

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

```cpp
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.

### 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[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 |

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`](https://en.cppreference.com/w/cpp/iterator/forward_iterator) (C++20): specifies that an `input_iterator` is a forward iterator, supporting equality comparison and multi-pass (concept)
- [**Iterator library**](https://en.cppreference.com/w/cpp/iterator): provides definitions for iterators, iterator traits, adaptors, and utility functions

---
Attribution: content from https://en.cppreference.com/w/cpp/named_req/ForwardIterator (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.