Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/named req/OutputIterator"

From cppreference.com
< cpp‎ | named req
(Created page with "{{cpp/concept/title|OutputIterator}} {{cpp/concept/sidebar}} An Iterator that can access the pointed element for writing.<br/> A class implementing this concept is [[cpp/iterato...")
 
m (fmt)
 
(36 intermediate revisions by 11 users not shown)
Line 1: Line 1:
−
{{cpp/concept/title|OutputIterator}}
+
{{cpp/named req/title|OutputIterator}}
−
{{cpp/concept/sidebar}}
+
{{cpp/named req/navbar}}
  
−
An Iterator that can access the pointed element for writing.<br/>
+
A {{named req|OutputIterator}} is a {{named req|Iterator}} that can write to the pointed-to element.  
−
A class implementing this concept is [[cpp/iterator/ostream_iterator|std::ostream_iterator]].
+
 
 +
An example of a type that implements {{named req/core|OutputIterator}} is [[cpp/iterator/ostream_iterator|std::ostream_iterator]].
 +
 
 +
When {{named req|ForwardIterator}}, {{named req|BidirectionalIterator}}, or {{named req|RandomAccessIterator}} satisfies the {{named req/core|OutputIterator}} requirements in addition to its own requirements, it is described as '''mutable'''.
  
 
===Requirements===
 
===Requirements===
 +
The type {{c|X}} satisfies {{named req/core|OutputIterator}} if
  
−
* [[cpp/concept/Iterator|Iterator]]
+
* The type {{c|X}} satisfies {{named req|Iterator}}
 +
* {{c|X}} is a class type or a pointer type
  
 +
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
 
{|table class="wikitable"
 
{|table class="wikitable"
 
|-
 
|-
−
!Expression||Return||Equivalent expression||Notes
+
!Expression||Return||Equivalent expression||Pre-condition||Post-conditions||Notes
 
|-
 
|-
−
|{{cpp|*i {{=}} o}}|| || || it may not be possible to write twice in the same iterator
+
|{{c|1=*r = o}}
 +
|(not used)
 +
|
 +
|{{c|r}} is dereferenceable
 +
|{{c|r}} is incrementable
 +
|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.
 
|-
 
|-
−
|{{cpp|++i}}||{{cpp|It&}}||  
+
|{{c|++r}}
−
|After this, copies of {{ttb|a}} may be invalidated.<br>
+
|{{c|X&}}
−
'''Post''': {{cpp|&r {{==}} &++r}}
+
|
 +
|{{c|r}} is incrementable
 +
|{{c|r}} and {{c|++r}} designate the same iterator object, {{c|r}} is dereferenceable or past-the-end
 +
|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.
 
|-
 
|-
−
|{{cpp|i++}}|| {{cpp|const It&}} || {{cpp|
+
|{{c|r++}}
−
It temp {{=}} i;
+
|convertible to {{c|const X&}}
−
++i;
+
|{{c|1=
 +
X temp = r;
 +
++r;
 
return temp;
 
return temp;
 
}}
 
}}
 +
|
 +
|
 
|
 
|
 
|-
 
|-
−
|{{cpp|*i++ {{=}} o}} || ||{{cpp|
+
|{{c|1=*r++ = o}}
−
*i {{=}} o;
+
|(not used)
−
++i;
+
|{{c|1=*r = o;
−
}}
+
++r;}}  
 +
|
 +
|
 
|
 
|
 
|}
 
|}
 +
 +
===Notes===
 +
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 {{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 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 {{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===
 +
The following standard library iterators are output iterators that are not forward iterators:
 +
* {{lc|std::ostream_iterator}}
 +
* {{lc|std::ostreambuf_iterator}}
 +
* {{lc|std::insert_iterator}}
 +
* {{lc|std::back_insert_iterator}}
 +
* {{lc|std::front_insert_iterator}}
 +
 +
===See also===
 +
{{dsc begin}}
 +
{{dsc inc|cpp/iterator/dsc output_iterator}}
 +
{{see_also_iterator_library}}
 +
{{dsc end}}
 +
 +
{{langlinks|de|es|fr|it|ja|pt|ru|zh}}

Latest revision as of 10:54, 25 September 2022

 
C++
 
C++ named requirements
 

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_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;

[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:

[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) [edit]
Iterator library provides definitions for iterators, iterator traits, adaptors, and utility functions
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/named_req/OutputIterator&oldid=143751"