Insert Iterators

Library:  Iterators

insert_iterator  iterator

• Local Index
• Summary
• Synopsis
• Description
• Interface
• See Also
• Standards Conformance

An iterator adaptor that allows an iterator to insert into a container rather than overwrite elements in the container

#include <iterator>

namespace std {
  template <class Container>
  class insert_iterator;

  template <class Container>
  class back_insert_iterator;

  template <class Container>
  class front_insert_iterator;
}

Insert iterators are iterator adaptors that let an iterator insert new elements into a collection rather than overwrite existing elements when copying to a container. There are several types of insert iterator classes.

• The class back_insert_iterator is used to insert items at the end of a collection. The function back_inserter() can be used with an iterator inline, to create an instance of a back_insert_iterator for a particular collection type.

• The class front_insert_iterator is used to insert items at the start of a collection. The function front_inserter() creates an instance of a front_insert_iterator for a particular collection type.

• An insert_iterator inserts new items into a collection at a location defined by an iterator supplied to the constructor. Like the other insert iterators, insert_iterator has a helper function called inserter(), which takes a collection and an iterator into that collection, and creates an instance of the insert_iterator.

namespace std{ 

  template <class Container>
  class insert_iterator : public
       iterator<output_iterator_tag,void,void,void,void>; {

    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 back_insert_iterator : public
         iterator<output_iterator_tag,void,void,void,void> ; {

    public:
      typedef Container container_type;
      explicit back_insert_iterator(Container&);
      back_insert_iterator<Container>&
      operator=(const typename Container::value_type&);
      back_insert_iterator<Container>& operator*();
      back_insert_iterator<Container>& operator++();
      back_insert_iterator<Container> operator++(int);
    };

  template <class Container>
  class front_insert_iterator : public
        iterator<output_iterator_tag,void,void,void,void>;
  {

    public:
      typedef Container container_type;
      explicit front_insert_iterator(Container&);
      front_insert_iterator<Container>&
      operator=(const typename Container::value_type&);
      front_insert_iterator<Container>& operator*();
      front_insert_iterator<Container>& operator++();
      front_insert_iterator<Container> operator++(int);
  };

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

  template <class Container>
  front_insert_iterator<Container> 
                        front_inserter(Container&);
}

back_insert_iterator, front_insert_iterator, insert_iterator

ISO/IEC 14882:1998 -- International Standard for Information Systems -- Programming Language C++, Section 24.4.2