Namespaces
Variants
Views
Actions

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

From cppreference.com
< cpp‎ | named req
(24.4.1[iterator.traits]/1 special rule for output iterators and related LWG issue link)
m (fmt)
 
(18 intermediate revisions by 8 users not shown)
Line 1: Line 1:
−
{{cpp/concept/title|OutputIterator}}
+
{{cpp/named req/title|OutputIterator}}
−
{{cpp/concept/navbar}}
+
{{cpp/named req/navbar}}
  
−
An {{tt|OutputIterator}} is an {{concept|Iterator}} that can write to the pointed-to element.  
+
A {{named req|OutputIterator}} is a {{named req|Iterator}} that can write to the pointed-to element.  
  
−
An example of a type that implements {{tt|OutputIterator}} 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 {{concept|ForwardIterator}}, {{concept|BidirectionalIterator}}, or {{concept|RandomAccessIterator}} satisfies the {{concept|OutputIterator}} requirements in addition to its own requirements, it is described as '''mutable'''.
+
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
  
−
The type {{tt|X}} satisfies {{tt|OutputIterator}} if
+
* The type {{c|X}} satisfies {{named req|Iterator}}
−
 
+
* {{c|X}} is a class type or a pointer type
−
* The type {{tt|X}} satisfies {{concept|Iterator}}
+
−
* {{tt|X}} is a class type or a pointer type
+
  
 
And, given
 
And, given
−
* {{tt|o}}, a value of some type that is writable to the output iterator (there may be multiple types that are writable, e.g. if {{tt|operator{{=}}}} may be a template. There is no notion of {{tt|value_type}} as for the input iterators)
+
* {{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)
−
* {{tt|r}}, an lvalue of type {{tt|X}},
+
* {{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 {{=}} o}}
+
|{{c|1=*r = o}}
 
|(not used)
 
|(not used)
 
|
 
|
−
|{{tt|r}} is dereferencable
+
|{{c|r}} is dereferenceable
−
|{{tt|r}} is incrementable
+
|{{c|r}} is incrementable
−
|After this operation {{tt|r}} is not required to be dereferenceable and any copies of the previous value of {{tt|r}} are no longer required to be dereferenceable or 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.
 
|-
 
|-
 
|{{c|++r}}
 
|{{c|++r}}
 
|{{c|X&}}
 
|{{c|X&}}
 
|
 
|
−
|{{tt|r}} is incrementable
+
|{{c|r}} is incrementable
−
|{{c|&r {{==}} &++r}}, {{tt|r}} is dereferencable or past-the-end
+
|{{c|r}} and {{c|++r}} designate the same iterator object, {{c|r}} is dereferenceable or past-the-end
−
|After this operation {{tt|r}} is not required to be incrementable and any copies of the previous value of {{tt|r}} are no longer required to be dereferenceable or incrementable.
+
|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 {{=}} r;
+
X temp = r;
 
++r;
 
++r;
 
return temp;
 
return temp;
Line 49: Line 48:
 
|
 
|
 
|-
 
|-
−
|{{c|*r++ {{=}} o}}
+
|{{c|1=*r++ = o}}
 
|(not used)
 
|(not used)
−
|{{c|*r {{=}} o;
+
|{{c|1=*r = o;
 
++r;}}  
 
++r;}}  
 
|
 
|
Line 59: Line 58:
  
 
===Notes===
 
===Notes===
−
The only valid use of {{tt|operator*}} with an output iterator is on the left of an assignment: {{tt|operator*}} may return a proxy object, which defines a member {{tt|operator{{=}}}} (which may be a template)
+
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 {{tt|operator{{==}}}} is defined, {{tt|x {{==}} y}} need not imply {{tt|++x {{==}} ++y}}.
+
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 [http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-active.html#2035 LWG #2035])
+
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 {{tt|iterator_traits<X>::value_type}}, {{tt|iterator_traits<X>::difference_type}}, {{tt|iterator_traits<X>::pointer}}, and {{tt|iterator_traits<X>::reference}} to be {{c|void}}, although it contradicts the requirement that {{c|*r {{=}} o}} is valid: this is [http://cplusplus.github.io/LWG/lwg-active.html#2437 LWG #2437]
+
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 78: Line 77:
  
 
===See also===
 
===See also===
−
* [[cpp/iterator|Iterator library]]
+
{{dsc begin}}
 +
{{dsc inc|cpp/iterator/dsc output_iterator}}
 +
{{see_also_iterator_library}}
 +
{{dsc end}}
  
−
[[de:cpp/concept/OutputIterator]]
+
{{langlinks|de|es|fr|it|ja|pt|ru|zh}}
−
[[es:cpp/concept/OutputIterator]]
+
−
[[fr:cpp/concept/OutputIterator]]
+
−
[[it:cpp/concept/OutputIterator]]
+
−
[[ja:cpp/concept/OutputIterator]]
+
−
[[pt:cpp/concept/OutputIterator]]
+
−
[[ru:cpp/concept/OutputIterator]]
+
−
[[zh:cpp/concept/OutputIterator]]
+

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"