inserter (3C++std) - Tru64 UNIX
Standard C++ LibraryCopyright 1996, 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 : public output_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 output_iterator {
public:
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)
CONSTRUCTOR
insert_iterator(Container& x, typename Container::iterator i);
Constructor. 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);
Assignment operator. 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 FUNCTION
template <class Container, class Iterator>
insert_iterator<Container>
inserter(Container& x, Iterator i);
Returns an insert_iterator that will insert elements into container x at
location i. This function allows you to create insert iterators inline.
EXAMPLE
#include <iterator>
#include <vector>
#include <iostream.h>
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(),ostream_iterator<int,char>(cout," "));
return 0;
}
WARNINGS
If your compiler does not support default template parameters, then you
need to always supply the Allocator template argument. For instance,
you'll have to write:
vector<int, allocator<int> >
instead of:
vector<int>
SEE ALSO
back_insert_iterator, front_insert_iterator, Insert Iterators
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
privacy and legal statement