.\" ident @(#)insert_iterator.3 .\" Standard Template Library .\" $$RW_INSERT_HEADER "slyrs.man" .TH insert_iterator 3C++ "02 Apr 1998" "Rogue Wave Software" "-" .ce2 Standard C++ Library Copyright 1998, Rogue Wave Software, Inc. .SH NAME \f2insert_iterator\fP, \f2inserter\fP \ - An insert iterator used to insert items into a collection rather than overwrite the collection. .SH SYNOPSIS .RE .RS 0 #include .br template .br class insert_iterator; .SH 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 \f2inserter\fP 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. .SH INTERFACE .br template .br class insert_iterator : public .RE .RS 5 iterator ; { .RE .RS 0 protected: .RE .RS 2 Container* container; .RE .RS 0 public: .RE .RS 2 typedef Container container_type; .br insert_iterator (Container&, typename Container::iterator); .br insert_iterator& .RE .RS 3 operator= (const typename Container::value_type&); .RE .RS 2 insert_iterator& operator* (); .br insert_iterator& operator++ (); .br insert_iterator& operator++ (int); .RE .RS 0 }; .br .br template .br insert_iterator inserter (Container&, Iterator) .SH TYPES .br container_type .RE .RS 3 The type of container acted on by the iterator. .RE .SH CONSTRUCTORS .br insert_iterator(Container& x, .RE .RS 17 typename Container::iterator i); .RE .RS 3 Creates an instance of an insert_iterator associated with container \f2x\fP and iterator \f2i.\fP .RE .SH OPERATORS .RE .RS 0 insert_iterator& .br operator=(const typename Container::value_type& value); .RE .RS 3 Inserts a copy of \f2value\fP into the container at the location specified by the \f2insert_iterator\fP, increments the iterator, and returns \f2*this\fP. .RE .br insert_iterator& .br operator*(); .RE .RS 3 Returns \f2*this\fP (the input iterator itself). .RE .br insert_iterator& .br operator++(); .br insert_iterator& .br operator++(int); .RE .RS 3 Increments the insert iterator and returns \f2*this\fP. .RE .SH NON-MEMBER FUNCTIONS .br template .br insert_iterator .br inserter(Container& x, Iterator i); .RE .RS 3 Returns an insert_iterator that inserts elements into container \f2x\fP at location \f2i\fP. This function allows you to create insert iterators inline. .RE .SH EXAMPLE .RE .RS 1 #include .br #include .br #include .RE .RS 0 using namespace std; .br int main() .RE .RS 1 { .RE .RS 3 //Initialize a vector using an array .RE .RS 2 int arr[4] = {3,4,7,8}; .br vector v(arr,arr+4); .RE .RS 3 //Output the original vector .RE .RS 2 cout << "Start with a vector: " << endl << " "; .br copy(v.begin(),v.end(), .RE .RS 7 ostream_iterator(cout," ")); .RE .RS 3 //Insert into the middle .br insert_iterator > ins(v, v.begin()+2); .br *ins = 5; .br *ins = 6; .br //Output the new vector .RE .RS 2 cout << endl << endl; .br cout << "Use an insert_iterator: " << endl << " "; .br copy(v.begin(),v.end(), .RE .RS 7 ostream_iterator(cout," ")); .RE .RS 2 return 0; .RE .RS 1 } .SH WARNINGS If your compiler does not support default template parameters, then you always need to supply the \f2Allocator\fP template argument. For instance, you have to write: \f2vector >\fP instead of: \f2vector\fP If your compiler does not support namespaces, then you do not need the using declaration for \f2std\fP. .SH SEE ALSO back_insert_iterator, front_insert_iterator, Insert_Iterators