# C++ named requirements: LegacyOutputIterator

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

A LegacyOutputIterator is a LegacyIterator that can write to the pointed-to element.

## Official Specification Summary (cppreference)

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**.

### 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_type` as 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; return temp;` |   |   |   |
| `*r++ = o` | (not used) | `*r = o; ++r;` |   |   |   |

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

### Standard library

The following standard library iterators are output iterators that are not forward iterators:

- `ostream_iterator`: output iterator that writes to `std::basic_ostream` (class template)
- `ostreambuf_iterator`: output iterator that writes to `std::basic_streambuf` (class template)
- `insert_iterator`: iterator adaptor for insertion into a container (class template)
- `back_insert_iterator`: iterator adaptor for insertion at the end of a container (class template)
- `front_insert_iterator`: iterator adaptor for insertion at the front of a container (class template)

### See also

- [`output_iterator`](https://en.cppreference.com/w/cpp/iterator/output_iterator) (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**](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/OutputIterator (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.