Difference between revisions of "cpp/named req/OutputIterator"
From cppreference.com
m (→See also: ~ {{see_also_iterator_library}}) |
m (fmt) |
||
| (4 intermediate revisions by 3 users not shown) | |||
| Line 9: | Line 9: | ||
===Requirements=== | ===Requirements=== | ||
| + | The type {{c|X}} satisfies {{named req/core|OutputIterator}} if | ||
| − | + | * The type {{c|X}} satisfies {{named req|Iterator}} | |
| − | + | * {{c|X}} is a class type or a pointer type | |
| − | * The type {{ | + | |
| − | * {{ | + | |
And, given | And, given | ||
| − | * {{ | + | * {{c|o}}, a value of some type that is writable to the output iterator (there may be multiple types that are writable, e.g. if {{c|1= operator=}} may be a template. There is no notion of {{tt|value_type}} as for the input iterators) |
| − | * {{ | + | * {{c|r}}, an lvalue of type {{c|X}}, |
The following expressions must be valid and have their specified effects | The following expressions must be valid and have their specified effects | ||
| Line 24: | Line 23: | ||
!Expression||Return||Equivalent expression||Pre-condition||Post-conditions||Notes | !Expression||Return||Equivalent expression||Pre-condition||Post-conditions||Notes | ||
|- | |- | ||
| − | |{{c|*r | + | |{{c|1=*r = o}} |
|(not used) | |(not used) | ||
| | | | ||
| − | |{{ | + | |{{c|r}} is dereferenceable |
| − | |{{ | + | |{{c|r}} is incrementable |
| − | |After this operation {{ | + | |After this operation {{c|r}} is not required to be dereferenceable and any copies of the previous value of {{c|r}} are no longer required to be dereferenceable or incrementable. |
|- | |- | ||
|{{c|++r}} | |{{c|++r}} | ||
|{{c|X&}} | |{{c|X&}} | ||
| | | | ||
| − | |{{ | + | |{{c|r}} is incrementable |
| − | |{{c|r}} and {{c|++r}} designate the same iterator object, {{ | + | |{{c|r}} and {{c|++r}} designate the same iterator object, {{c|r}} is dereferenceable or past-the-end |
| − | |After this operation {{ | + | |After this operation {{c|r}} is not required to be incrementable and any copies of the previous value of {{c|r}} are no longer required to be dereferenceable or incrementable. |
|- | |- | ||
|{{c|r++}} | |{{c|r++}} | ||
|convertible to {{c|const X&}} | |convertible to {{c|const X&}} | ||
| − | |{{c| | + | |{{c|1= |
| − | X temp | + | X temp = r; |
++r; | ++r; | ||
return temp; | return temp; | ||
| Line 49: | Line 48: | ||
| | | | ||
|- | |- | ||
| − | |{{c|*r++ | + | |{{c|1=*r++ = o}} |
|(not used) | |(not used) | ||
| − | |{{c|*r | + | |{{c|1=*r = o; |
++r;}} | ++r;}} | ||
| | | | ||
| Line 59: | Line 58: | ||
===Notes=== | ===Notes=== | ||
| − | The only valid use of {{ | + | The only valid use of {{c|operator*}} with an output iterator is on the left of an assignment: {{c|operator*}} may return a proxy object, which defines a member {{c|1= operator=}} (which may be a template). |
| − | Equality and inequality may not be defined for output iterators. Even if an {{ | + | Equality and inequality may not be defined for output iterators. Even if an {{c|1= operator==}} is defined, {{c|1= x == y}} need not imply {{c|1= ++x == ++y}}. |
Assignment through the same value of an output iterator happens only once: algorithms on output iterators must be single-pass algorithms. | Assignment through the same value of an output iterator happens only once: algorithms on output iterators must be single-pass algorithms. | ||
| − | Assignment through an output iterator is expected to alternate with incrementing. Double-increment is undefined behavior (C++ standard currently claims that double increment is supported, contrary to the STL documentation; this is | + | Assignment through an output iterator is expected to alternate with incrementing. Double-increment is undefined behavior (C++ standard currently claims that double increment is supported, contrary to the STL documentation; this is {{lwg|2035}}). |
| − | Pure output-only iterator is allowed to declare its {{ | + | Pure output-only iterator is allowed to declare its {{c|iterator_traits<X>::value_type}}, {{c|iterator_traits<X>::difference_type}}, {{c|iterator_traits<X>::pointer}}, and {{c|iterator_traits<X>::reference}} to be {{c|void}} (and iterators such as {{lc|std::back_insert_iterator}} do just that{{rev inl|since=c++20| except for {{tt|difference_type}}, which is now defined to satisfy {{lc|std::output_iterator}} }}). |
===Standard library=== | ===Standard library=== | ||
| Line 79: | Line 78: | ||
===See also=== | ===See also=== | ||
{{dsc begin}} | {{dsc begin}} | ||
| − | {{dsc inc | cpp/iterator/dsc | + | {{dsc inc|cpp/iterator/dsc output_iterator}} |
{{see_also_iterator_library}} | {{see_also_iterator_library}} | ||
{{dsc end}} | {{dsc end}} | ||
{{langlinks|de|es|fr|it|ja|pt|ru|zh}} | {{langlinks|de|es|fr|it|ja|pt|ru|zh}} | ||
Latest revision as of 10:54, 25 September 2022
A LegacyOutputIterator is a LegacyIterator that can write to the pointed-to element.
An example of a type that implements LegacyOutputIterator is std::ostream_iterator.
When LegacyForwardIterator, LegacyBidirectionalIterator, or LegacyRandomAccessIterator satisfies the LegacyOutputIterator requirements in addition to its own requirements, it is described as mutable.
Contents |
[edit] Requirements
The type X satisfies LegacyOutputIterator if
- The type X satisfies LegacyIterator
- X is a class type or a pointer type
And, given
- o, a value of some type that is writable to the output iterator (there may be multiple types that are writable, e.g. if operator= may be a template. There is no notion of
value_typeas for the input iterators) - r, an lvalue of type X,
The following expressions must be valid and have their specified effects
| Expression | Return | Equivalent expression | Pre-condition | Post-conditions | Notes |
|---|---|---|---|---|---|
| *r = o | (not used) | r is dereferenceable | r is incrementable | After this operation r is not required to be dereferenceable and any copies of the previous value of r are no longer required to be dereferenceable or incrementable. | |
| ++r | X& | r is incrementable | r and ++r designate the same iterator object, r is dereferenceable or past-the-end | After this operation r is not required to be incrementable and any copies of the previous value of r are no longer required to be dereferenceable or incrementable. | |
| r++ | convertible to const X& | X temp = r; ++r; |
|||
| *r++ = o | (not used) | *r = o; ++r; |
[edit] Notes
The only valid use of operator* with an output iterator is on the left of an assignment: operator* may return a proxy object, which defines a member operator= (which may be a template).
Equality and inequality may not be defined for output iterators. Even if an operator== is defined, x == y need not imply ++x == ++y.
Assignment through the same value of an output iterator happens only once: algorithms on output iterators must be single-pass algorithms.
Assignment through an output iterator is expected to alternate with incrementing. Double-increment is undefined behavior (C++ standard currently claims that double increment is supported, contrary to the STL documentation; this is LWG issue 2035).
Pure output-only iterator is allowed to declare its iterator_traits<X>::value_type, iterator_traits<X>::difference_type, iterator_traits<X>::pointer, and iterator_traits<X>::reference to be void (and iterators such as std::back_insert_iterator do just that except for difference_type, which is now defined to satisfy std::output_iterator (since C++20)).
[edit] Standard library
The following standard library iterators are output iterators that are not forward iterators:
- std::ostream_iterator
- std::ostreambuf_iterator
- std::insert_iterator
- std::back_insert_iterator
- std::front_insert_iterator
[edit] See also
| (C++20) |
specifies that a type is an output iterator for a given value type, that is, values of that type can be written to it and it can be both pre- and post-incremented (concept) |
| Iterator library | provides definitions for iterators, iterator traits, adaptors, and utility functions |
