std::insert_iterator

C++

Language

Headers

Freestanding and hosted implementations

Named requirements

Language support library

Concepts library (C++20)

Diagnostics library

Utilities library

Strings library

Containers library

Algorithms library

Iterators library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

Filesystem library (C++17)

Technical Specifications

Iterator library

Iterator primitives
iterator_traits
input_iterator_tagoutput_iterator_tagforward_iterator_tagbidirectional_iterator_tagrandom_access_iterator_tag
iterator
Iterator adaptors
reverse_iterator move_iterator (C++11) back_insert_iterator front_insert_iterator insert_iterator	make_reverse_iterator (C++14) make_move_iterator (C++11) back_inserter front_inserter inserter
Stream iterators
istream_iterator
ostream_iterator
istreambuf_iterator
ostreambuf_iterator
Iterator operations
advance
distance
prev (C++11)
next (C++11)
Range access
begincbegin (C++11)(C++14)
endcend (C++11)(C++14)
rbegincrbegin (C++14)(C++14)
rendcrend (C++14)(C++14)
Container access
size (C++17)
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 an OutputIterator 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
container_type	Container

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)	a pointer of type Container*
iter (protected)	an iterator of type Container::iterator

Member types

Member type	Definition
value_type	void
difference_type	void
pointer	void
reference	void
iterator_category	std::output_iterator_tag

These member types are required to be obtained by inheriting from std::iterator<std::output_iterator_tag,void,void,void,void>.

(until C++17)

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)