Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of Boost. Click here to view this page for the latest version.
Front Page / Sequences / Intrinsic Metafunctions / insert

insert

Synopsis

template< 
      typename Sequence
    , typename Pos
    , typename T 
    >
struct insert
{
    typedef unspecified type;
};


template< 
      typename Sequence
    , typename T 
    >
struct insert
{
    typedef unspecified type;
};

Description

insert is an overloaded name:

Header

#include <boost/mpl/insert.hpp>

Model of

Tag Dispatched Metafunction

Parameters

Parameter Requirement Description
Sequence Extensible Sequence or Extensible Associative Sequence A sequence to insert into.
Pos Forward Iterator An iterator in Sequence specifying the insertion position.
T Any type The element to be inserted.

Expression semantics

For any Extensible Sequence s, iterator pos in s, and arbitrary type x:

typedef insert<s,pos,x>::type r; 
Return type:Extensible Sequence
Precondition:pos is an iterator in s.
Semantics:r is a sequence, concept-identical to s, of the following elements: [begin<s>::type, pos), x, [pos, end<s>::type).
Postcondition:

The relative order of the elements in r is the same as in s.

at< r, distance< begin<s>::type,pos >::type >::type

is identical to x;

size<r>::value == size<s>::value + 1;        

For any Extensible Associative Sequence s, iterator pos in s, and arbitrary type x:

typedef insert<s,x>::type r; 
Return type:Extensible Associative Sequence
Semantics:r is concept-identical and equivalent to s, except that at< r, key_type<s,x>::type >::type is identical to value_type<s,x>::type.
Postcondition:size<r>::value == size<s>::value + 1.
typedef insert<s,pos,x>::type r; 
Return type:Extensible Associative Sequence
Precondition:pos is an iterator in s.
Semantics:Equivalent to typedef insert<s,x>::type r; pos is ignored.

Complexity

Sequence archetype Complexity
Extensible Associative Sequence Amortized constant time.
Extensible Sequence Linear in the worst case, or amortized constant time.

Example

typedef vector_c<int,0,1,3,4,5,6,7,8,9> numbers;
typedef find< numbers,integral_c<int,3> >::type pos;
typedef insert< numbers,pos,integral_c<int,2> >::type range;

BOOST_MPL_ASSERT_RELATION( size<range>::value, ==, 10 );
BOOST_MPL_ASSERT(( equal< range,range_c<int,0,10> > ));
typedef map< mpl::pair<int,unsigned> > m;
typedef insert<m,mpl::pair<char,long> >::type m1;

BOOST_MPL_ASSERT_RELATION( size<m1>::value, ==, 2 );
BOOST_MPL_ASSERT(( is_same< at<m1,int>::type,unsigned > ));
BOOST_MPL_ASSERT(( is_same< at<m1,char>::type,long > ));

See also

Extensible Sequence, Extensible Associative Sequence, insert_range, push_front, push_back, erase