insert_iterator<Sequence>



Categories: iterators, adaptors	Component type: type

Description

Insert_iterator is an iterator adaptor that functions as an Output Iterator: assignment through an insert_iterator inserts an object into a Sequence. [1]

Example

list<int> L;
L.push_front(3);
insert_iterator<list<int> > ii(L, L.begin());
*ii++ = 0;
*ii++ = 1;
*ii++ = 2;
copy(L.begin(), L.end(), ostream_iterator<int>(cout, " "));
// The values that are printed are 0 1 2 3.

Definition

Defined in iterator.h.

Template parameters

Parameter	Description	Default
`Sequence`	The type of Sequence into which values will be inserted.

Model of

Output Iterator. An insert iterator's set of value types (as defined in the Output Iterator requirements) consists of a single type: Sequence::value_type.

Type requirements

The template parameter Sequence must be a Sequence.

Public base classes

None.

Members

Member	Where defined	Description
`insert_iterator(Sequence&, Sequence::iterator)`	`insert_iterator`	See below.
`insert_iterator(const insert_iterator&)`	Trivial Iterator	The copy constructor
`insert_iterator& operator=(const insert_iterator&)`	Trivial Iterator	The assignment operator
`insert_iterator& operator*()`	Output Iterator	Used to implement the output iterator expression `*i = x`. [2]
`insert_iterator& operator=(const Sequence::value_type&)`	Output Iterator	Used to implement the output iterator expression `*i = x`. [2]
`insert_iterator& operator++()`	Output Iterator	Preincrement.
`insert_iterator& operator++(int)`	Output Iterator	Postincrement.
`output_iterator_tag iterator_category(const insert_iterator&)`	iterator tags	Returns the iterator's category. This is a global function, not a member.
template<class Sequence, class Iter) insert_iterator<Sequence> inserter(Sequence& S, Iter i);	`insert_iterator`	See below.

New members

These members are not defined in the Output Iterator requirements, but are specific to insert_iterator.

Member	Description
`insert_iterator(Sequence& S, Sequence::iterator i)`	Constructs an `insert_iterator` that inserts objects in `S` just before the element pointed to by `i`. The iterator `i` must be a dereferenceable or past-the-end iterator in `S`.
template<class Sequence, class Iter) insert_iterator<Sequence> inserter(Sequence& S, Iter i);	Equivalent to `insert_iterator<Sequence>(S, i)`. [2] This is a global function, not a member function.

Notes

[1] Note the difference between assignment through a Sequence::iterator and assignment through an insert_iterator<Sequence>. If i is a valid Sequence::iterator, then it points to some particular element in the sequence; the expression *i = t replaces that element with t, and does not change the total number of elements in the sequence. If ii is a valid insert_iterator<Sequence>, however, then the expression *ii = t is equivalent, for some Sequence seq and some valid Sequence::iterator j, to the expression seq.insert(j, t). That is, it does not overwrite any of seq's elements and it does change seq's size.

[2] Note how assignment through an insert_iterator is implemented. In general, unary operator* must be defined so that it returns a proxy object, where the proxy object defines operator= to perform the insert operation. In this case, for the sake of simplicity, the proxy object is the insert_iterator itself. That is, *i simply returns i, and *i = t is equivalent to i = t. You should not, however, rely on this behavior. It is an implementation detail, and it is not guaranteed to remain the same in future versions.

[3] This function exists solely for the sake of convenience: since it is a non-member function, the template parameters may be inferred and the type of the insert_iterator need not be declared explicitly. One easy way to reverse a range and insert it into a Sequence S, for example, is reverse_copy(first, last, inserter(S, S.begin())).