Insert Iterators

Module:  Standard C++ Library   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

Copyright (c) 1994-2006 Rogue Wave Software, a Quovadx Division.
Licensed under the Apache License, Version 2.0.
Contact Rogue Wave about documentation or support issues. You can also seek help from other developers through the Apache stdcxx community (see below).