insert_iterator(3C++)

Standard C++ Library
Copyright 1998, Rogue Wave Software, Inc.

NAME

insert_iterator, inserter

- An insert iterator used to insert items into a collection rather than overwrite the collection.

SYNOPSIS

#include <iterator>
template <class Container>
class insert_iterator;

DESCRIPTION

Insert iterators let you insert new elements into a collection rather than copy a new element’s value over the value of an existing element. The class_insert_iterator is used to insert items into a specified location of a collection. The function inserter creates an instance of an_insert_iterator given a particular collection type and iterator. An insert_iterator can be used with vectors, deques, lists, maps and sets.

INTERFACE

template <class Container>
class insert_iterator : public

iterator<output_iterator_tag,void,void,void,void> ; {

protected:

Container∗ container;

public:

typedef Container container_type;
insert_iterator (Container&, typename Container::iterator);
insert_iterator<Container>&

operator= (const typename Container::value_type&);

insert_iterator<Container>& operator∗ ();
insert_iterator<Container>& operator++ ();
insert_iterator<Container>& operator++ (int);

};

template <class Container, class Iterator>
insert_iterator<Container> inserter (Container&, Iterator)

TYPES

container_type

The type of container acted on by the iterator.

CONSTRUCTORS

insert_iterator(Container& x,

typename Container::iterator i);

Creates an instance of an insert_iterator associated with container x and iterator i.

OPERATORS

insert_iterator<Container>&
operator=(const typename Container::value_type& value);

Inserts a copy of value into the container at the location specified by the insert_iterator, increments the iterator, and returns ∗this.

insert_iterator<Container>&
operator∗();

Returns ∗this (the input iterator itself).

insert_iterator<Container>&
operator++();
insert_iterator<Container>&
operator++(int);

Increments the insert iterator and returns ∗this.

NON-MEMBER FUNCTIONS

template <class Container, class Iterator>
insert_iterator<Container>
inserter(Container& x, Iterator i);

Returns an insert_iterator that inserts elements into container x at location i. This function allows you to create insert iterators inline.

EXAMPLE

#include <iterator>
#include <vector>
#include <iostream>

using namespace std;
int main()

{

//Initialize a vector using an array

int arr[4] = {3,4,7,8};
vector<int> v(arr,arr+4);

//Output the original vector

cout << "Start with a vector: " << endl << " ";
copy(v.begin(),v.end(),

ostream_iterator<int,char>(cout," "));

//Insert into the middle
insert_iterator<vector<int> > ins(v, v.begin()+2);
∗ins = 5;
∗ins = 6;
//Output the new vector

cout << endl << endl;
cout << "Use an insert_iterator: " << endl << " ";
copy(v.begin(),v.end(),