Apache C++ Standard Library Reference Guide

## Insert Iterators

Library: Iterators

    insert_iterator  iterator

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

### Local Index

No Entries

### Summary

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

### Synopsis

    #include <iterator>

    namespace std {
      template <class Container>
      class insert_iterator;

      template <class Container>
      class back_insert_iterator;

      template <class Container>
      class front_insert_iterator;
    }

### Description

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.

### Interface

    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&);
    }

### See Also

back_insert_iterator, front_insert_iterator, insert_iterator

### Standards Conformance

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