insert_iterator, inserter()

Module:  Standard C++ Library   Library:  Iterators

insert_iterator  iterator

• Local Index
• Summary
• Synopsis
• Description
• Interface
• Member Types
• Constructors
• Operators
• Nonmember Functions
• Example
• See Also
• Standards Conformance

Members

container_type insert_iterator()

operator*() operator++()

operator=()

Non-Members

inserter()

insert_iterator is an insert iterator used to insert items into a collection rather than overwrite the collection

#include <iterator>

namespace std {
  template <class Container>
  class insert_iterator;
}

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.

namespace std{ 

  template <class Container>
  class insert_iterator : public
        iterator<output_iterator_tag,void,void,void,void>;  {
  
  protected:
    Container* container;
  
  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 Iterator>
  insert_iterator<Container> inserter(Container&, Iterator)
}

container_type

The type of container acted on by the iterator.

insert_iterator(Container& x, 
                  typename Container::iterator i);

Creates an instance of an insert_iterator associated with container x and iterator i.

insert_iterator<Container>&
operator=(const typename Container::value_type& value);

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.

template <class Container, class Iterator>
insert_iterator<Container> 
inserter(Container& x, Iterator i);

Returns an insert_iterator that inserts elements into container x at location i. This function allows you to create insert iterators inline.

//
//  ins_itr.cpp
//

#include <algorithm>   // for copy
#include <iostream>    // for cout, endl
#include <iterator>    // for ostream_iterator, xxx_inserter
#include <deque>       // for deque

int main ()
{
    // Typedefs for convenience.
    typedef std::deque<int, std::allocator<int> >   Deque;
    typedef std::ostream_iterator<int, char, 
                           std::char_traits<char> > os_iter;

    // Initialize a deque using an array.
    Deque::value_type arr[] = { 3, 4, 7, 8 };
    Deque d (arr, arr + sizeof arr / sizeof *arr);

    // Output the original deque.
    std::cout << "Start with a deque: \n     ";
    std::copy (d.begin (), d.end (), os_iter (std::cout, " "));

    // Insert into the middle.
    std::insert_iterator<Deque> ins (d, d.begin () + 2);
    *ins = 5;
    *ins = 6;

    // Output the new deque.
    std::cout << "\n\nUse an insert_iterator: \n     ";
    std::copy (d.begin (), d.end (), os_iter (std::cout, " "));

    // A deque of four 1s.
    Deque d2 (4, 1);

    // Insert d2 at front of d.
    std::copy (d2.begin (), d2.end (), 
               std::front_inserter (d));

    // Output the new deque.
    std::cout << "\n\nUse a front_inserter: \n     ";
    std::copy (d.begin (), d.end (), os_iter (std::cout, " "));

    // Insert d2 at back of d.
    std::copy (d2.begin (), d2.end (), std::back_inserter (d));

    // Output the new deque.
    std::cout << "\n\nUse a back_inserter: \n     ";
    std::copy (d.begin (), d.end (), os_iter (std::cout, " "));

    std::cout << std::endl;
   
    return 0;
}


Program Output:

Start with a deque: 
     3 4 7 8 

Use an insert_iterator: 
     3 4 5 6 7 8 

Use a front_inserter: 
     1 1 1 1 3 4 5 6 7 8 

Use a back_inserter: 
     1 1 1 1 3 4 5 6 7 8 1 1 1 1 

back_insert_iterator, front_insert_iterator, Insert Iterators

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

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).