|
|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ALegacyOutputIterator is aLegacyIterator that can write to the pointed-to element.
An example of a type that implementsLegacyOutputIterator isstd::ostream_iterator.
WhenLegacyForwardIterator,LegacyBidirectionalIterator, orLegacyRandomAccessIterator satisfies theLegacyOutputIterator requirements in addition to its own requirements, it is described asmutable.
Contents |
The typeX satisfiesLegacyOutputIterator if
And, given
value_type as for the input iterators)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 operationr is not required to be dereferenceable and any copies of the previous value ofr 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 operationr is not required to be incrementable and any copies of the previous value ofr are no longer required to be dereferenceable or incrementable. | |
| r++ | convertible toconst X& | X temp= r; ++r; | |||
| *r++= o | (not used) | *r= o; ++r; |
The only valid use ofoperator* with an output iterator is on the left of an assignment:operator* may return a proxy object, which defines a memberoperator= (which may be a template).
Equality and inequality may not be defined for output iterators. Even if anoperator== 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 isLWG issue 2035).
Pure output-only iterator is allowed to declare itsiterator_traits<X>::value_type,iterator_traits<X>::difference_type,iterator_traits<X>::pointer, anditerator_traits<X>::reference to bevoid (and iterators such asstd::back_insert_iterator do just that except fordifference_type, which is now defined to satisfystd::output_iterator(since C++20)).
The following standard library iterators are output iterators that are not forward iterators:
| output iterator that writes tostd::basic_ostream (class template)[edit] | |
| output iterator that writes tostd::basic_streambuf (class template)[edit] | |
| iterator adaptor for insertion into a container (class template)[edit] | |
| iterator adaptor for insertion at the end of a container (class template)[edit] | |
| iterator adaptor for insertion at the front of a container (class template)[edit] |
(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)[edit] |
| Iterator library | provides definitions for iterators, iterator traits, adaptors, and utility functions |
