• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1.. Sequences/Intrinsic Metafunctions//insert
2
3insert
4======
5
6Synopsis
7--------
8
9.. parsed-literal::
10
11    template<
12          typename Sequence
13        , typename Pos
14        , typename T
15        >
16    struct insert
17    {
18        typedef |unspecified| type;
19    };
20
21
22    template<
23          typename Sequence
24        , typename T
25        >
26    struct insert
27    {
28        typedef |unspecified| type;
29    };
30
31
32Description
33-----------
34
35``insert`` is an |overloaded name|:
36
37* ``insert<Sequence,Pos,T>`` performs an insertion of
38  type ``T`` at an arbitrary position ``Pos`` in ``Sequence``. ``Pos`` is ignored is
39  ``Sequence`` is a model of |Extensible Associative Sequence|.
40
41* ``insert<Sequence,T>`` is a shortcut notation for ``insert<Sequence,Pos,T>`` for the
42  case when ``Sequence`` is a model of |Extensible Associative Sequence|.
43
44
45Header
46------
47
48.. parsed-literal::
49
50    #include <boost/mpl/insert.hpp>
51
52
53Model of
54--------
55
56|Tag Dispatched Metafunction|
57
58
59Parameters
60----------
61
62+---------------+-----------------------------------+-----------------------------------------------+
63| Parameter     | Requirement                       | Description                                   |
64+===============+===================================+===============================================+
65| ``Sequence``  | |Extensible Sequence| or          | A sequence to insert into.                    |
66|               | |Extensible Associative Sequence| |                                               |
67+---------------+-----------------------------------+-----------------------------------------------+
68| ``Pos``       | |Forward Iterator|                | An iterator in ``Sequence`` specifying the    |
69|               |                                   | insertion position.                           |
70+---------------+-----------------------------------+-----------------------------------------------+
71| ``T``         | Any type                          | The element to be inserted.                   |
72+---------------+-----------------------------------+-----------------------------------------------+
73
74
75Expression semantics
76--------------------
77
78.. compound::
79    :class: expression-semantics
80
81    For any |Extensible Sequence| ``s``, iterator ``pos`` in ``s``, and arbitrary type ``x``:
82
83    .. parsed-literal::
84
85        typedef insert<s,pos,x>::type r;
86
87    :Return type:
88        |Extensible Sequence|
89
90    :Precondition:
91        ``pos`` is an iterator in ``s``.
92
93    :Semantics:
94        ``r`` is a sequence, |concept-identical| to ``s``, of the following elements:
95        [``begin<s>::type``, ``pos``), ``x``, [``pos``, ``end<s>::type``).
96
97    :Postcondition:
98        The relative order of the elements in ``r`` is the same as in ``s``.
99
100        .. parsed-literal::
101
102           at< r, distance< begin<s>::type,pos >::type >::type
103
104        is identical to ``x``;
105
106        .. parsed-literal::
107
108           size<r>::value == size<s>::value + 1;
109
110
111
112.. compound::
113    :class: expression-semantics
114
115
116    For any |Extensible Associative Sequence| ``s``, iterator ``pos`` in ``s``,
117    and arbitrary type ``x``:
118
119
120    .. parsed-literal::
121
122        typedef insert<s,x>::type r;
123
124    :Return type:
125        |Extensible Associative Sequence|
126
127    :Semantics:
128        ``r`` is |concept-identical| and equivalent to ``s``, except that
129        ``at< r, key_type<s,x>::type >::type`` is identical to ``value_type<s,x>::type``.
130
131    :Postcondition:
132        ``size<r>::value == size<s>::value + 1``.
133
134
135    .. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
136
137    .. parsed-literal::
138
139        typedef insert<s,pos,x>::type r;
140
141    :Return type:
142        |Extensible Associative Sequence|
143
144    :Precondition:
145        ``pos`` is an iterator in ``s``.
146
147    :Semantics:
148        Equivalent to ``typedef insert<s,x>::type r``; ``pos`` is ignored.
149
150
151
152Complexity
153----------
154
155+---------------------------------------+-----------------------------------------------+
156| Sequence archetype                    | Complexity                                    |
157+=======================================+===============================================+
158| |Extensible Associative Sequence|     | Amortized constant time.                      |
159+---------------------------------------+-----------------------------------------------+
160| |Extensible Sequence|                 | Linear in the worst case, or amortized        |
161|                                       | constant time.                                |
162+---------------------------------------+-----------------------------------------------+
163
164
165Example
166-------
167
168.. parsed-literal::
169
170    typedef vector_c<int,0,1,3,4,5,6,7,8,9> numbers;
171    typedef find< numbers,integral_c<int,3> >::type pos;
172    typedef insert< numbers,pos,integral_c<int,2> >::type range;
173
174    BOOST_MPL_ASSERT_RELATION( size<range>::value, ==, 10 );
175    BOOST_MPL_ASSERT(( equal< range,range_c<int,0,10> > ));
176
177
178.. parsed-literal::
179
180    typedef map< mpl::pair<int,unsigned> > m;
181    typedef insert<m,mpl::pair<char,long> >::type m1;
182
183    BOOST_MPL_ASSERT_RELATION( size<m1>::value, ==, 2 );
184    BOOST_MPL_ASSERT(( is_same< at<m1,int>::type,unsigned > ));
185    BOOST_MPL_ASSERT(( is_same< at<m1,char>::type,long > ));
186
187
188See also
189--------
190
191|Extensible Sequence|, |Extensible Associative Sequence|, |insert_range|, |push_front|, |push_back|, |erase|
192
193
194.. copyright:: Copyright �  2001-2009 Aleksey Gurtovoy and David Abrahams
195   Distributed under the Boost Software License, Version 1.0. (See accompanying
196   file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
197