]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | .. Sequences/Intrinsic Metafunctions//insert |
2 | ||
3 | insert | |
4 | ====== | |
5 | ||
6 | Synopsis | |
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 | ||
32 | Description | |
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 | ||
45 | Header | |
46 | ------ | |
47 | ||
48 | .. parsed-literal:: | |
49 | ||
50 | #include <boost/mpl/insert.hpp> | |
51 | ||
52 | ||
53 | Model of | |
54 | -------- | |
55 | ||
56 | |Tag Dispatched Metafunction| | |
57 | ||
58 | ||
59 | Parameters | |
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 | ||
75 | Expression 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 | ||
152 | Complexity | |
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 | ||
165 | Example | |
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 | ||
188 | See also | |
189 | -------- | |
190 | ||
191 | |Extensible Sequence|, |Extensible Associative Sequence|, |insert_range|, |push_front|, |push_back|, |erase| | |
192 | ||
193 | ||
194 |