ceph/src/boost/libs/mpl/doc/src/refmanual/insert.rst

   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 .. 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)