C++ named requirements: LegacyForwardIterator
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.
Contents |
[edit] 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
- Let T be the value type of It. The type std::iterator_traits<It>::reference must be either
- T& or T&& (since C++11) if It satisfies LegacyOutputIterator (It is mutable), or
- const T& or const T&& (since C++11) 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 lvalue 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 |
---|---|---|
i++ | It | It ip = i; ++i; return ip; |
*i++ | reference |
A mutable LegacyForwardIterator is a LegacyForwardIterator that additionally satisfies the LegacyOutputIterator requirements.
[edit] 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 iteratorsA 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) |
ConceptFor the definition of std::iterator_traits, the following exposition-only concept is defined.
where the exposition-only concept Note that whilst LegacyForwardIterator allows for iterators to have their reference types being rvalue reference types, this concept does not. And so it is important for such iterators (e.g. std::move_iterator) to explicitly specify their It::iterator_category to be std::forward_iterator_tag (or stronger iterator category tags), as std::iterator_traits<It>::iterator_category would be incorrectly deduced as std::input_iterator_tag otherwise. |
(since C++20) |
[edit] See also
(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 |