clang-tools-extra/docs/clang-tidy/checks/modernize/use-emplace.rst

   1 .. title:: clang-tidy - modernize-use-emplace
   2
   3 modernize-use-emplace
   4 =====================
   5
   6 The check flags insertions to an STL-style container done by calling the
   7 ``push_back``, ``push``, or ``push_front`` methods with an
   8 explicitly-constructed temporary of the container element type. In this case,
   9 the corresponding ``emplace`` equivalent methods result in less verbose and
  10 potentially more efficient code.  Right now the check doesn't support
  11 ``insert``. It also doesn't support ``insert`` functions for associative
  12 containers because replacing ``insert`` with ``emplace`` may result in
  13 `speed regression <https://htmlpreview.github.io/?https://github.com/HowardHinnant/papers/blob/master/insert_vs_emplace.html>`_, but it might get support with some addition flag in the future.
  14
  15 The :option:`ContainersWithPushBack`, :option:`ContainersWithPush`, and
  16 :option:`ContainersWithPushFront` options are used to specify the container
  17 types that support the ``push_back``, ``push``, and ``push_front`` operations
  18 respectively. The default values for these options are as follows:
  19
  20 * :option:`ContainersWithPushBack`: ``std::vector``, ``std::deque``, and ``std::list``.
  21 * :option:`ContainersWithPush`: ``std::stack``, ``std::queue``, and ``std::priority_queue``.
  22 * :option:`ContainersWithPushFront`: ``std::forward_list``, ``std::list``, and ``std::deque``.
  23
  24 This check also reports when an ``emplace``-like method is improperly used,
  25 for example using ``emplace_back`` while also calling a constructor. This
  26 creates a temporary that requires at best a move and at worst a copy. Almost all
  27 ``emplace``-like functions in the STL are covered by this, with ``try_emplace``
  28 on ``std::map`` and ``std::unordered_map`` being the exception as it behaves
  29 slightly differently than all the others. More containers can be added with the
  30 :option:`EmplacyFunctions` option, so long as the container defines a
  31 ``value_type`` type, and the ``emplace``-like functions construct a
  32 ``value_type`` object.
  33
  34 Before:
  35
  36 .. code-block:: c++
  37
  38     std::vector<MyClass> v;
  39     v.push_back(MyClass(21, 37));
  40     v.emplace_back(MyClass(21, 37));
  41
  42     std::vector<std::pair<int, int>> w;
  43
  44     w.push_back(std::pair<int, int>(21, 37));
  45     w.push_back(std::make_pair(21L, 37L));
  46     w.emplace_back(std::make_pair(21L, 37L));
  47
  48 After:
  49
  50 .. code-block:: c++
  51
  52     std::vector<MyClass> v;
  53     v.emplace_back(21, 37);
  54     v.emplace_back(21, 37);
  55
  56     std::vector<std::pair<int, int>> w;
  57     w.emplace_back(21, 37);
  58     w.emplace_back(21L, 37L);
  59     w.emplace_back(21L, 37L);
  60
  61 By default, the check is able to remove unnecessary ``std::make_pair`` and
  62 ``std::make_tuple`` calls from ``push_back`` calls on containers of
  63 ``std::pair`` and ``std::tuple``. Custom tuple-like types can be modified by
  64 the :option:`TupleTypes` option; custom make functions can be modified by the
  65 :option:`TupleMakeFunctions` option.
  66
  67 The other situation is when we pass arguments that will be converted to a type
  68 inside a container.
  69
  70 Before:
  71
  72 .. code-block:: c++
  73
  74     std::vector<boost::optional<std::string> > v;
  75     v.push_back("abc");
  76
  77 After:
  78
  79 .. code-block:: c++
  80
  81     std::vector<boost::optional<std::string> > v;
  82     v.emplace_back("abc");
  83
  84
  85 In some cases the transformation would be valid, but the code wouldn't be
  86 exception safe. In this case the calls of ``push_back`` won't be replaced.
  87
  88 .. code-block:: c++
  89
  90     std::vector<std::unique_ptr<int>> v;
  91     v.push_back(std::unique_ptr<int>(new int(0)));
  92     auto *ptr = new int(1);
  93     v.push_back(std::unique_ptr<int>(ptr));
  94
  95 This is because replacing it with ``emplace_back`` could cause a leak of this
  96 pointer if ``emplace_back`` would throw exception before emplacement (e.g. not
  97 enough memory to add a new element).
  98
  99 For more info read item 42 - "Consider emplacement instead of insertion." of
 100 Scott Meyers "Effective Modern C++".
 101
 102 The default smart pointers that are considered are ``std::unique_ptr``,
 103 ``std::shared_ptr``, ``std::auto_ptr``. To specify other smart pointers or
 104 other classes use the :option:`SmartPointers` option.
 105
 106
 107 Check also doesn't fire if any argument of the constructor call would be:
 108
 109   - a bit-field (bit-fields can't bind to rvalue/universal reference)
 110
 111   - a ``new`` expression (to avoid leak)
 112
 113   - if the argument would be converted via derived-to-base cast.
 114
 115 This check requires C++11 or higher to run.
 116
 117 Options
 118 -------
 119
 120 .. option:: ContainersWithPushBack
 121
 122    Semicolon-separated list of class names of custom containers that support
 123    ``push_back``.
 124
 125 .. option:: ContainersWithPush
 126
 127    Semicolon-separated list of class names of custom containers that support
 128    ``push``.
 129
 130 .. option:: ContainersWithPushFront
 131
 132    Semicolon-separated list of class names of custom containers that support
 133    ``push_front``.
 134
 135 .. option:: IgnoreImplicitConstructors
 136
 137     When `true`, the check will ignore implicitly constructed arguments of
 138     ``push_back``, e.g.
 139
 140     .. code-block:: c++
 141
 142         std::vector<std::string> v;
 143         v.push_back("a"); // Ignored when IgnoreImplicitConstructors is `true`.
 144
 145     Default is `false`.
 146
 147 .. option:: SmartPointers
 148
 149    Semicolon-separated list of class names of custom smart pointers.
 150
 151 .. option:: TupleTypes
 152
 153     Semicolon-separated list of ``std::tuple``-like class names.
 154
 155 .. option:: TupleMakeFunctions
 156
 157     Semicolon-separated list of ``std::make_tuple``-like function names. Those
 158     function calls will be removed from ``push_back`` calls and turned into
 159     ``emplace_back``.
 160
 161 .. option:: EmplacyFunctions
 162
 163     Semicolon-separated list of containers without their template parameters
 164     and some ``emplace``-like method of the container. Example:
 165     ``vector::emplace_back``. Those methods will be checked for improper use and
 166     the check will report when a temporary is unnecessarily created.
 167
 168 Example
 169 ^^^^^^^
 170
 171 .. code-block:: c++
 172
 173   std::vector<MyTuple<int, bool, char>> x;
 174   x.push_back(MakeMyTuple(1, false, 'x'));
 175   x.emplace_back(MakeMyTuple(1, false, 'x'));
 176
 177 transforms to:
 178
 179 .. code-block:: c++
 180
 181   std::vector<MyTuple<int, bool, char>> x;
 182   x.emplace_back(1, false, 'x');
 183   x.emplace_back(1, false, 'x');
 184
 185 when :option:`TupleTypes` is set to ``MyTuple``, :option:`TupleMakeFunctions`
 186 is set to ``MakeMyTuple``, and :option:`EmplacyFunctions` is set to
 187 ``vector::emplace_back``.