insert_iterator<Container>

The insert_iterator is an iterator adapter that acts as an output iterator, but which converts expressions of the form *itr = value into calls to insert on an STL container. The insert_iterator constructor takes in a reference to another STL container class that should have insert invoked on it, as well as an iterator indicating where to begin insertion. All STL container class (except for the container adapters and bitset) support insert, so this iterator class can be used on both vectors and sets.

Because insert's behavior varies from container to container, this iterator class may or may not be appropriate for the task at hand. For vector, deque, and list, insert places the new element at the spot specified by the iterator. The insert_iterator then advances the iterator forward one step. Consequently, if an insert_iterator is used to add the values (0, 1, 2, 3) into an STL vector containing (100, 101, 102, 103 at the spot directly following 101, the result will be (100, 101, 0, 1, 2, 3, 102, 103). For associative containers like map and set, insert will automatically insert the element at the correct location, so an insert_iterator will correctly place the elements inside the container.

When using an insert_iterator, be sure that you are aware of the time costs of insertions into the specified container. For vector, insertions anywhere other than at the end of the vector are O(n) in the size of the vector and it may be preferrable to use a back_insert_iterator instead. Similarly, deque insert operations anywhere except at the beginning or end of the container are O(n), so you may want to use a back_insert_iterator or front_insert_iterator instead. For the list class and the associative containers like map and set, insertions are quite fast and an insert_iterator may be ideal for the job.

insert_iterator is a template type whose argument is the type of container to which the insert_iterator should forward its requests. For example, to invoke insert on a container of type set<int>, you would use an insert_iterator<set<int> >. Remember to include the extra space between the closing angle brackets or you will get a compile-time error!

Since the above syntax can get a bit clunky, the STL provides a utility function, inserter, which creates insert_iterators.

insert_iterator<Container> Utility Functions

insert_iterator<Container> back_inserter(Container &toWrap, Container::iterator start);

Constructs a insert_iterator at the specified location.

copy(v.begin(), v.end(), inserter(out, out.begin())); // Copy from container v into container out, starting at the first element.

Constructs a new insert_iterator that calls insert on the element specified as the parameter when dereferenced. It is preferable to create insert_iterators using inserter rather than through a constructor call, since the compiler will figure out the correct type of insert_iterator to create. Since in most cases you will create insert_iterators as parameters to functions, this function also lets you avoid writing out the type of the insert_iterator longhand.

insert_iterator<Container> Member Functions

insert_iterator<Container>(Container &target, Container::iterator start)

Constructs a insert_iterator on the specified element at the specified position.

insert_iterator<set<int> > itr(mySet, mySet.begin()); // Constructs an insert_iterator that inserts into a set.

insert_iterator<vector<int> > itr(myVector, myVector.begin() + 3); // Constructs an insert_iterator that inserts into a vector, beginning at position 3.

Constructs a new insert_iterator that calls insert} on the element specified as the parameter when dereferenced. The start parameter indicates where to begin inserting; its meaning changes based on the container. See the above section for more information.