Namespaces
Variants

    cpp/named req/OutputIterator: Difference between revisions

    From cppreference.com
    ← Older edit
    Space Mission (talk | contribs)
    19,873 edits
    m fmt
    Space Mission (talk | contribs)
    19,873 edits
     
    Line 2: Line 2:
    {{cpp/named req/navbar}}
    {{cpp/named req/navbar}}


    A {{named req|OutputIterator}} is a {{named req|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 {{named req/core|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]].
    Line 51: Line 51:
    |(not used)
    |(not used)
    |{{c|1=*r = o;
    |{{c|1=*r = o;
    ++r;}}  
    ++r;}}
    |
    |
    |
    |
    Line 66: Line 66:
    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}}).
    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}} }}).
    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===
    The following standard library iterators are output iterators that are not forward iterators:
    The following standard library iterators are output iterators that are not forward iterators:
    * {{lc|std::ostream_iterator}}
    {{
    * {{lc|std::ostreambuf_iterator}}
    |ostream_iterator}}
    * {{lc|std::insert_iterator}}
    {{|ostreambuf_iterator}}
    * {{lc|std::back_insert_iterator}}
    {{|insert_iterator}}
    * {{lc|std::front_insert_iterator}}
    {{|back_insert_iterator}}
    {{|front_insert_iterator
    }}


    ===See also===
    ===See also===

    Latest revision as of 22:31, 21 November 2024

     
    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.

    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:

    		output iterator that writes to std::basic_ostream
    (class template) [edit]
    		output iterator that writes to std::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]

    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