std::insert_iterator

 

C++

Compiler support

Freestanding and hosted

Language

Standard library headers

Named requirements

Feature test macros (C++20)

Language support library

Concepts library (C++20)

Metaprogramming library (C++11)

Diagnostics library

General utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Numerics library

Localizations library

Input/output library

Filesystem library (C++17)

Regular expressions library (C++11)

Concurrency support library (C++11)

Technical specifications

Symbols index

External libraries

 

Iterator library

Iterator concepts
indirectly_readable (C++20) indirectly_writable (C++20) weakly_incrementable (C++20) incrementable (C++20) input_or_output_iterator (C++20) sentinel_for (C++20) sized_sentinel_for (C++20)	input_iterator (C++20) output_iterator (C++20) forward_iterator (C++20) bidirectional_iterator (C++20) random_access_iterator (C++20) contiguous_iterator (C++20)
Iterator primitives
iterator_traits input_iterator_tagoutput_iterator_tagforward_iterator_tagbidirectional_iterator_tagrandom_access_iterator_tagcontiguous_iterator_tag (C++20) iterator (deprecated in C++17)	incrementable_traits (C++20) indirectly_readable_traits (C++20) iter_value_titer_difference_titer_reference_titer_const_reference_titer_rvalue_reference_titer_common_reference_t (C++20)(C++20)(C++20)(C++23)(C++20)(C++20)
Algorithm concepts and utilities
Indirect callable concepts
indirectly_unary_invocableindirectly_regular_unary_invocable (C++20)(C++20)   indirect_unary_predicate (C++20)	indirect_binary_predicate (C++20) indirect_equivalence_relation (C++20) indirect_strict_weak_order (C++20)
Common algorithm requirements
indirectly_movable (C++20) indirectly_movable_storable (C++20) indirectly_copyable (C++20) indirectly_copyable_storable (C++20)	indirectly_swappable (C++20) indirectly_comparable (C++20) permutable (C++20) mergeable (C++20) sortable (C++20)
Utilities
indirect_result_t (C++20)	projected (C++20)
Iterator adaptors
reverse_iterator move_iterator (C++11) move_sentinel (C++20) common_iterator (C++20) counted_iterator (C++20) basic_const_iterator (C++23) const_iterator (C++23) const_sentinel (C++23) back_insert_iterator front_insert_iterator insert_iterator	make_reverse_iterator (C++14) make_move_iterator (C++11) default_sentinel_tdefault_sentinel (C++20)(C++20) unreachable_sentinel_tunreachable_sentinel (C++20)(C++20) make_const_iterator (C++23) make_const_sentinel (C++23) back_inserter front_inserter inserter
Stream iterators
istream_iterator ostream_iterator	istreambuf_iterator ostreambuf_iterator
Iterator customization points
ranges::iter_move (C++20)
ranges::iter_swap (C++20)
Iterator operations
advance distance prev (C++11) next (C++11)	ranges::advance (C++20) ranges::distance (C++20) ranges::prev (C++20) ranges::next (C++20)
Range access
begincbegin (C++11)(C++14) endcend (C++11)(C++14) sizessize (C++17)(C++20)	rbegincrbegin (C++14)(C++14) rendcrend (C++14)(C++14) empty (C++17) data (C++17)

 

std::insert_iterator

Member functions

insert_iterator::insert_iterator

insert_iterator::operator=

insert_iterator::operator*

insert_iterator::operator++insert_iterator::operator++(int)

 

Defined in header <iterator>
template< class Container > class insert_iterator : public std::iterator< std::output_iterator_tag,                                               void,void,void,void >		(until C++17)
template< class Container > class insert_iterator;		(since C++17)

std::insert_iterator is a LegacyOutputIterator that inserts elements into a container for which it was constructed, at the position pointed to by the supplied iterator. The container's insert() member function is called whenever the iterator (whether dereferenced or not) is assigned to. Incrementing the std::insert_iterator is a no-op.

Member types

Member type	Definition
iterator_category	std::output_iterator_tag
value_type	void
difference_type	void (until C++20) std::ptrdiff_t (since C++20)
pointer	void
reference	void
container_type	Container

Member types iterator_category, value_type, difference_type, pointer and reference are required to be obtained by inheriting from std::iterator<std::output_iterator_tag, void, void, void, void>.

(until C++17)

Member functions

(constructor)	constructs a new insert_iterator (public member function)
operator=	inserts an object into the associated container (public member function)
operator*	no-op (public member function)
operator++operator++(int)	no-op (public member function)

Member objects

Member name	Definition
container (protected member object)	a pointer of type Container*
iter (protected member object)	an iterator of type Container::iterator (until C++20) ranges::iterator_t<Container> (since C++20)

Example

Run this code

#include <vector>
#include <list>
#include <iostream>
#include <iterator>
#include <algorithm>
 
int main()
{
    std::vector<int> v{1,2,3,4,5};
    std::list<int> l{-1,-2,-3};
    std::copy(v.begin(), v.end(), // may be simplified with std::inserter
              std::insert_iterator<std::list<int>>(l, std::next(l.begin()))); 
    for (int n : l)
        std::cout << n << ' ';
    std::cout << '\n';
}

Output:

-1 1 2 3 4 5 -2 -3

See also

inserter	creates a std::insert_iterator of type inferred from the argument (function 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)