Apache C++ Standard Library Reference Guide

## front_insert_iterator, front_inserter()

Library: Iterators

    Function

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

### Local Index

#### Members

container_type front_insert_iterator() | operator*() operator++() | operator=()

#### Non-Members

front_inserter() |

### Summary

An output iterator used to insert items at the beginning of a collection

### Synopsis

    #include <iterator>

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

### 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 template front_insert_iterator is used to insert items at the beginning of a collection. The convenience function template `front_inserter()` creates an instance of a front_insert_iterator for a particular collection type. A front_insert_iterator can be used with any container that defines the `push_front()` member function, specifically the sequences deque and list, but not with associative containers (e.g., map or set).

Note that a front_insert_iterator makes each element that it inserts the new front of the container. This has the effect of reversing the order of the inserted elements. For example, if you use a front_insert_iterator to insert "1" then "2" then "3" onto the front of container `exmpl`, you find, after the three insertions, that the first three elements of `exmpl` are "3 2 1".

### Interface

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

      protected:
         Container* container;
      public:
         typedef Container container_type;
         explicit front_insert_iterator(container_tyep&);
         front_insert_iterator&
         operator=(typename container_type::const_reference&);
         front_insert_iterator& operator*();
         front_insert_iterator& operator++();
         front_insert_iterator operator++(int);
      };

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

### Member Types

    container_type

The type of container acted on by this iterator.

### Constructors

    explicit
    front_insert_iterator(container_type& x);

Creates an instance of a front_insert_iterator associated with container `x.`

### Operators

    front_insert_iterator<Container>&
    operator=(typename container_type::constant_reference &value);

Inserts a copy of `value` at the front of the container by calling `container->push_front (value)`, and returns `*this`.

    front_insert_iterator&
    operator*();

Returns `*this` (the iterator itself).

    front_insert_iterator&
    operator++();
    front_insert_iterator
    operator++(int);

Increments the insert iterator and returns `*this`.

### Nonmember Functions

    template <class Container>
    front_insert_iterator<Container>
    front_inserter(Container& x)

Returns a front_insert_iterator that inserts elements at the beginning of container `x`.

### Example

    //
    //  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

### See Also

Insert Iterators

### Standards Conformance

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