| 1 |
.. title:: clang-tidy - modernize-pass-by-value |
| 2 |
|
| 3 |
modernize-pass-by-value |
| 4 |
======================= |
| 5 |
|
| 6 |
With move semantics added to the language and the standard library updated with |
| 7 |
move constructors added for many types it is now interesting to take an |
| 8 |
argument directly by value, instead of by const-reference, and then copy. This |
| 9 |
check allows the compiler to take care of choosing the best way to construct |
| 10 |
the copy. |
| 11 |
|
| 12 |
The transformation is usually beneficial when the calling code passes an |
| 13 |
*rvalue* and assumes the move construction is a cheap operation. This short |
| 14 |
example illustrates how the construction of the value happens: |
| 15 |
|
| 16 |
.. code-block:: c++ |
| 17 |
|
| 18 |
void foo(std::string s); |
| 19 |
std::string get_str(); |
| 20 |
|
| 21 |
void f(const std::string &str) { |
| 22 |
foo(str); // lvalue -> copy construction |
| 23 |
foo(get_str()); // prvalue -> move construction |
| 24 |
} |
| 25 |
|
| 26 |
.. note:: |
| 27 |
|
| 28 |
Currently, only constructors are transformed to make use of pass-by-value. |
| 29 |
Contributions that handle other situations are welcome! |
| 30 |
|
| 31 |
|
| 32 |
Pass-by-value in constructors |
| 33 |
----------------------------- |
| 34 |
|
| 35 |
Replaces the uses of const-references constructor parameters that are copied |
| 36 |
into class fields. The parameter is then moved with `std::move()`. |
| 37 |
|
| 38 |
Since ``std::move()`` is a library function declared in `<utility>` it may be |
| 39 |
necessary to add this include. The check will add the include directive when |
| 40 |
necessary. |
| 41 |
|
| 42 |
.. code-block:: c++ |
| 43 |
|
| 44 |
#include <string> |
| 45 |
|
| 46 |
class Foo { |
| 47 |
public: |
| 48 |
- Foo(const std::string &Copied, const std::string &ReadOnly) |
| 49 |
- : Copied(Copied), ReadOnly(ReadOnly) |
| 50 |
+ Foo(std::string Copied, const std::string &ReadOnly) |
| 51 |
+ : Copied(std::move(Copied)), ReadOnly(ReadOnly) |
| 52 |
{} |
| 53 |
|
| 54 |
private: |
| 55 |
std::string Copied; |
| 56 |
const std::string &ReadOnly; |
| 57 |
}; |
| 58 |
|
| 59 |
std::string get_cwd(); |
| 60 |
|
| 61 |
void f(const std::string &Path) { |
| 62 |
// The parameter corresponding to 'get_cwd()' is move-constructed. By |
| 63 |
// using pass-by-value in the Foo constructor we managed to avoid a |
| 64 |
// copy-construction. |
| 65 |
Foo foo(get_cwd(), Path); |
| 66 |
} |
| 67 |
|
| 68 |
|
| 69 |
If the parameter is used more than once no transformation is performed since |
| 70 |
moved objects have an undefined state. It means the following code will be left |
| 71 |
untouched: |
| 72 |
|
| 73 |
.. code-block:: c++ |
| 74 |
|
| 75 |
#include <string> |
| 76 |
|
| 77 |
void pass(const std::string &S); |
| 78 |
|
| 79 |
struct Foo { |
| 80 |
Foo(const std::string &S) : Str(S) { |
| 81 |
pass(S); |
| 82 |
} |
| 83 |
|
| 84 |
std::string Str; |
| 85 |
}; |
| 86 |
|
| 87 |
|
| 88 |
Known limitations |
| 89 |
^^^^^^^^^^^^^^^^^ |
| 90 |
|
| 91 |
A situation where the generated code can be wrong is when the object referenced |
| 92 |
is modified before the assignment in the init-list through a "hidden" reference. |
| 93 |
|
| 94 |
Example: |
| 95 |
|
| 96 |
.. code-block:: c++ |
| 97 |
|
| 98 |
std::string s("foo"); |
| 99 |
|
| 100 |
struct Base { |
| 101 |
Base() { |
| 102 |
s = "bar"; |
| 103 |
} |
| 104 |
}; |
| 105 |
|
| 106 |
struct Derived : Base { |
| 107 |
- Derived(const std::string &S) : Field(S) |
| 108 |
+ Derived(std::string S) : Field(std::move(S)) |
| 109 |
{ } |
| 110 |
|
| 111 |
std::string Field; |
| 112 |
}; |
| 113 |
|
| 114 |
void f() { |
| 115 |
- Derived d(s); // d.Field holds "bar" |
| 116 |
+ Derived d(s); // d.Field holds "foo" |
| 117 |
} |
| 118 |
|
| 119 |
|
| 120 |
Note about delayed template parsing |
| 121 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 122 |
|
| 123 |
When delayed template parsing is enabled, constructors part of templated |
| 124 |
contexts; templated constructors, constructors in class templates, constructors |
| 125 |
of inner classes of template classes, etc., are not transformed. Delayed |
| 126 |
template parsing is enabled by default on Windows as a Microsoft extension: |
| 127 |
`Clang Compiler User's Manual - Microsoft extensions`_. |
| 128 |
|
| 129 |
Delayed template parsing can be enabled using the `-fdelayed-template-parsing` |
| 130 |
flag and disabled using `-fno-delayed-template-parsing`. |
| 131 |
|
| 132 |
Example: |
| 133 |
|
| 134 |
.. code-block:: c++ |
| 135 |
|
| 136 |
template <typename T> class C { |
| 137 |
std::string S; |
| 138 |
|
| 139 |
public: |
| 140 |
= // using -fdelayed-template-parsing (default on Windows) |
| 141 |
= C(const std::string &S) : S(S) {} |
| 142 |
|
| 143 |
+ // using -fno-delayed-template-parsing (default on non-Windows systems) |
| 144 |
+ C(std::string S) : S(std::move(S)) {} |
| 145 |
}; |
| 146 |
|
| 147 |
.. _Clang Compiler User's Manual - Microsoft extensions: https://clang.llvm.org/docs/UsersManual.html#microsoft-extensions |
| 148 |
|
| 149 |
.. seealso:: |
| 150 |
|
| 151 |
For more information about the pass-by-value idiom, read: `Want Speed? Pass by Value`_. |
| 152 |
|
| 153 |
.. _Want Speed? Pass by Value: https://web.archive.org/web/20140205194657/http://cpp-next.com/archive/2009/08/want-speed-pass-by-value/ |
| 154 |
|
| 155 |
Options |
| 156 |
------- |
| 157 |
|
| 158 |
.. option:: IncludeStyle |
| 159 |
|
| 160 |
A string specifying which include-style is used, `llvm` or `google`. Default |
| 161 |
is `llvm`. |
| 162 |
|
| 163 |
.. option:: ValuesOnly |
| 164 |
|
| 165 |
When `true`, the check only warns about copied parameters that are already |
| 166 |
passed by value. Default is `false`. |