C++ named requirements: LegacyInputIterator
A LegacyInputIterator is a LegacyIterator that can read from the pointed-to element. LegacyInputIterators only guarantee validity for single pass algorithms: once a LegacyInputIterator i has been incremented, all copies of its previous value may be invalidated.
Contents |
[edit] Requirements
Type | Definition |
X
|
An input iterator type |
T
|
The value type of X (i.e. std::iterator_traits<X>::value_type)
|
R
|
std::iterator_traits<X>::reference |
Value | Definition |
i, j | Values of type X or const X
|
r | A value of type X&
|
X
satisfies LegacyInputIterator if all following conditions are satisfied:
-
X
satisfies LegacyIterator. -
X
satisfies EqualityComparable. - The following expressions must be valid and have their specified effects:
Expression | Type | Effects | Conditions | |
---|---|---|---|---|
i != j | contextually convertible to bool (until C++23) |
Equivalent to !(i == j). | Pre | i and j are in the domain of ==. |
models boolean-testable (since C++23) |
Post | No explicit requirement | ||
*i | R , convertible to T
|
|
Pre | i is dereferenceable. |
Post | No explicit requirement | |||
i->m | Equivalent to (*i).m. | Pre | i is dereferenceable. | |
Post | No explicit requirement | |||
++r | X&
|
Pre | r is dereferenceable. | |
Post |
| |||
(void)r++ | Equivalent to (void)++r. | No explicit requirement | ||
*r++ | convertible to T
|
Equivalent to T x = *r; ++r; return x;. |
No explicit requirement |
[edit] Equality domain
The term the domain of == is used in the ordinary mathematical sense to denote the set of values which can be compared using ==. This set can change over time.
Each algorithm places additional requirements on the equality domain for the iterator values it uses. These requirements can be inferred from the uses that algorithm makes of == and !=.
[edit] Notes
For an input iterator X
that is not a LegacyForwardIterator, std::iterator_traits<X>::reference does not have to be a reference type: dereferencing an input iterator may return a proxy object or std::iterator_traits<X>::value_type itself by value (as in the case of std::istreambuf_iterator).
ConceptFor the definition of std::iterator_traits, the following exposition-only concept is defined.
where the exposition-only concept |
(since C++20) |
[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 98 | C++98 | the return type of *i++ was required to be T
|
it can be any type convertible to T
|
[edit] See also
(C++20) |
specifies that a type is an input iterator, that is, its referenced values can be read and it can be both pre- and post-incremented (concept) |
Iterator library | provides definitions for iterators, iterator traits, adaptors, and utility functions |