| 1 |
.. title:: clang-tidy - bugprone-easily-swappable-parameters |
| 2 |
|
| 3 |
bugprone-easily-swappable-parameters |
| 4 |
==================================== |
| 5 |
|
| 6 |
Finds function definitions where parameters of convertible types follow each |
| 7 |
other directly, making call sites prone to calling the function with |
| 8 |
swapped (or badly ordered) arguments. |
| 9 |
|
| 10 |
.. code-block:: c++ |
| 11 |
|
| 12 |
void drawPoint(int X, int Y) { /* ... */ } |
| 13 |
FILE *open(const char *Dir, const char *Name, Flags Mode) { /* ... */ } |
| 14 |
|
| 15 |
A potential call like ``drawPoint(-2, 5)`` or ``openPath("a.txt", "tmp", Read)`` |
| 16 |
is perfectly legal from the language's perspective, but might not be what the |
| 17 |
developer of the function intended. |
| 18 |
|
| 19 |
More elaborate and type-safe constructs, such as opaque typedefs or strong |
| 20 |
types should be used instead, to prevent a mistaken order of arguments. |
| 21 |
|
| 22 |
.. code-block:: c++ |
| 23 |
|
| 24 |
struct Coord2D { int X; int Y; }; |
| 25 |
void drawPoint(const Coord2D Pos) { /* ... */ } |
| 26 |
|
| 27 |
FILE *open(const Path &Dir, const Filename &Name, Flags Mode) { /* ... */ } |
| 28 |
|
| 29 |
Due to the potentially elaborate refactoring and API-breaking that is necessary |
| 30 |
to strengthen the type safety of a project, no automatic fix-its are offered. |
| 31 |
|
| 32 |
Options |
| 33 |
------- |
| 34 |
|
| 35 |
Extension/relaxation options |
| 36 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 37 |
|
| 38 |
Relaxation (or extension) options can be used to broaden the scope of the |
| 39 |
analysis and fine-tune the enabling of more mixes between types. |
| 40 |
Some mixes may depend on coding style or preference specific to a project, |
| 41 |
however, it should be noted that enabling *all* of these relaxations model the |
| 42 |
way of mixing at call sites the most. |
| 43 |
These options are expected to make the check report for more functions, and |
| 44 |
report longer mixable ranges. |
| 45 |
|
| 46 |
.. option:: QualifiersMix |
| 47 |
|
| 48 |
Whether to consider parameters of some *cvr-qualified* ``T`` and a |
| 49 |
differently *cvr-qualified* ``T`` (i.e. ``T`` and ``const T``, ``const T`` |
| 50 |
and ``volatile T``, etc.) mixable between one another. |
| 51 |
If `false`, the check will consider differently qualified types unmixable. |
| 52 |
`True` turns the warnings on. |
| 53 |
Defaults to `false`. |
| 54 |
|
| 55 |
The following example produces a diagnostic only if `QualifiersMix` is |
| 56 |
enabled: |
| 57 |
|
| 58 |
.. code-block:: c++ |
| 59 |
|
| 60 |
void *memcpy(const void *Destination, void *Source, std::size_t N) { /* ... */ } |
| 61 |
|
| 62 |
.. option:: ModelImplicitConversions |
| 63 |
|
| 64 |
Whether to consider parameters of type ``T`` and ``U`` mixable if there |
| 65 |
exists an implicit conversion from ``T`` to ``U`` and ``U`` to ``T``. |
| 66 |
If `false`, the check will not consider implicitly convertible types for |
| 67 |
mixability. |
| 68 |
`True` turns warnings for implicit conversions on. |
| 69 |
Defaults to `true`. |
| 70 |
|
| 71 |
The following examples produce a diagnostic only if |
| 72 |
`ModelImplicitConversions` is enabled: |
| 73 |
|
| 74 |
.. code-block:: c++ |
| 75 |
|
| 76 |
void fun(int Int, double Double) { /* ... */ } |
| 77 |
void compare(const char *CharBuf, std::string String) { /* ... */ } |
| 78 |
|
| 79 |
.. note:: |
| 80 |
|
| 81 |
Changing the qualifiers of an expression's type (e.g. from ``int`` to |
| 82 |
``const int``) is defined as an *implicit conversion* in the C++ |
| 83 |
Standard. |
| 84 |
However, the check separates this decision-making on the mixability of |
| 85 |
differently qualified types based on whether `QualifiersMix` was |
| 86 |
enabled. |
| 87 |
|
| 88 |
For example, the following code snippet will only produce a diagnostic |
| 89 |
if **both** `QualifiersMix` and `ModelImplicitConversions` are enabled: |
| 90 |
|
| 91 |
.. code-block:: c++ |
| 92 |
|
| 93 |
void fun2(int Int, const double Double) { /* ... */ } |
| 94 |
|
| 95 |
Filtering options |
| 96 |
^^^^^^^^^^^^^^^^^ |
| 97 |
|
| 98 |
Filtering options can be used to lessen the size of the diagnostics emitted by |
| 99 |
the checker, whether the aim is to ignore certain constructs or dampen the |
| 100 |
noisiness. |
| 101 |
|
| 102 |
.. option:: MinimumLength |
| 103 |
|
| 104 |
The minimum length required from an adjacent parameter sequence to be |
| 105 |
diagnosed. |
| 106 |
Defaults to `2`. |
| 107 |
Might be any positive integer greater or equal to `2`. |
| 108 |
If `0` or `1` is given, the default value `2` will be used instead. |
| 109 |
|
| 110 |
For example, if `3` is specified, the examples above will not be matched. |
| 111 |
|
| 112 |
.. option:: IgnoredParameterNames |
| 113 |
|
| 114 |
The list of parameter **names** that should never be considered part of a |
| 115 |
swappable adjacent parameter sequence. |
| 116 |
The value is a `;`-separated list of names. |
| 117 |
To ignore unnamed parameters, add `""` to the list verbatim (not the |
| 118 |
empty string, but the two quotes, potentially escaped!). |
| 119 |
**This option is case-sensitive!** |
| 120 |
|
| 121 |
By default, the following parameter names, and their Uppercase-initial |
| 122 |
variants are ignored: |
| 123 |
`""` (unnamed parameters), `iterator`, `begin`, `end`, `first`, `last`, |
| 124 |
`lhs`, `rhs`. |
| 125 |
|
| 126 |
.. option:: IgnoredParameterTypeSuffixes |
| 127 |
|
| 128 |
The list of parameter **type name suffixes** that should never be |
| 129 |
considered part of a swappable adjacent parameter sequence. |
| 130 |
Parameters which type, as written in the source code, end with an element |
| 131 |
of this option will be ignored. |
| 132 |
The value is a `;`-separated list of names. |
| 133 |
**This option is case-sensitive!** |
| 134 |
|
| 135 |
By default, the following, and their lowercase-initial variants are ignored: |
| 136 |
`bool`, `It`, `Iterator`, `InputIt`, `ForwardIt`, `BidirIt`, `RandomIt`, |
| 137 |
`random_iterator`, `ReverseIt`, `reverse_iterator`, |
| 138 |
`reverse_const_iterator`, `RandomIt`, `random_iterator`, `ReverseIt`, |
| 139 |
`reverse_iterator`, `reverse_const_iterator`, `Const_Iterator`, |
| 140 |
`ConstIterator`, `const_reverse_iterator`, `ConstReverseIterator`. |
| 141 |
In addition, `_Bool` (but not `_bool`) is also part of the default value. |
| 142 |
|
| 143 |
.. option:: SuppressParametersUsedTogether |
| 144 |
|
| 145 |
Suppresses diagnostics about parameters that are used together or in a |
| 146 |
similar fashion inside the function's body. |
| 147 |
Defaults to `true`. |
| 148 |
Specifying `false` will turn off the heuristics. |
| 149 |
|
| 150 |
Currently, the following heuristics are implemented which will suppress the |
| 151 |
warning about the parameter pair involved: |
| 152 |
|
| 153 |
* The parameters are used in the same expression, e.g. ``f(a, b)`` or |
| 154 |
``a < b``. |
| 155 |
* The parameters are further passed to the same function to the same |
| 156 |
parameter of that function, of the same overload. |
| 157 |
E.g. ``f(a, 1)`` and ``f(b, 2)`` to some ``f(T, int)``. |
| 158 |
|
| 159 |
.. note:: |
| 160 |
|
| 161 |
The check does not perform path-sensitive analysis, and as such, |
| 162 |
"same function" in this context means the same function declaration. |
| 163 |
If the same member function of a type on two distinct instances are |
| 164 |
called with the parameters, it will still be regarded as |
| 165 |
"same function". |
| 166 |
|
| 167 |
* The same member field is accessed, or member method is called of the |
| 168 |
two parameters, e.g. ``a.foo()`` and ``b.foo()``. |
| 169 |
* Separate ``return`` statements return either of the parameters on |
| 170 |
different code paths. |
| 171 |
|
| 172 |
.. option:: NamePrefixSuffixSilenceDissimilarityTreshold |
| 173 |
|
| 174 |
The number of characters two parameter names might be different on *either* |
| 175 |
the head or the tail end with the rest of the name the same so that the |
| 176 |
warning about the two parameters are silenced. |
| 177 |
Defaults to `1`. |
| 178 |
Might be any positive integer. |
| 179 |
If `0`, the filtering heuristic based on the parameters' names is turned |
| 180 |
off. |
| 181 |
|
| 182 |
This option can be used to silence warnings about parameters where the |
| 183 |
naming scheme indicates that the order of those parameters do not matter. |
| 184 |
|
| 185 |
For example, the parameters ``LHS`` and ``RHS`` are 1-dissimilar suffixes |
| 186 |
of each other: ``L`` and ``R`` is the different character, while ``HS`` |
| 187 |
is the common suffix. |
| 188 |
Similarly, parameters ``text1, text2, text3`` are 1-dissimilar prefixes |
| 189 |
of each other, with the numbers at the end being the dissimilar part. |
| 190 |
If the value is at least `1`, such cases will not be reported. |
| 191 |
|
| 192 |
|
| 193 |
Limitations |
| 194 |
----------- |
| 195 |
|
| 196 |
**This check is designed to check function signatures!** |
| 197 |
|
| 198 |
The check does not investigate functions that are generated by the compiler |
| 199 |
in a context that is only determined from a call site. |
| 200 |
These cases include variadic functions, functions in C code that do not have |
| 201 |
an argument list, and C++ template instantiations. |
| 202 |
Most of these cases, which are otherwise swappable from a caller's standpoint, |
| 203 |
have no way of getting "fixed" at the definition point. |
| 204 |
In the case of C++ templates, only primary template definitions and explicit |
| 205 |
specializations are matched and analyzed. |
| 206 |
|
| 207 |
None of the following cases produce a diagnostic: |
| 208 |
|
| 209 |
.. code-block:: c++ |
| 210 |
|
| 211 |
int printf(const char *Format, ...) { /* ... */ } |
| 212 |
int someOldCFunction() { /* ... */ } |
| 213 |
|
| 214 |
template <typename T, typename U> |
| 215 |
int add(T X, U Y) { return X + Y }; |
| 216 |
|
| 217 |
void theseAreNotWarnedAbout() { |
| 218 |
printf("%d %d\n", 1, 2); // Two ints passed, they could be swapped. |
| 219 |
someOldCFunction(1, 2, 3); // Similarly, multiple ints passed. |
| 220 |
|
| 221 |
add(1, 2); // Instantiates 'add<int, int>', but that's not a user-defined function. |
| 222 |
} |
| 223 |
|
| 224 |
Due to the limitation above, parameters which type are further dependent upon |
| 225 |
template instantiations to *prove* that they mix with another parameter's is |
| 226 |
not diagnosed. |
| 227 |
|
| 228 |
.. code-block:: c++ |
| 229 |
|
| 230 |
template <typename T> |
| 231 |
struct Vector { |
| 232 |
typedef T element_type; |
| 233 |
}; |
| 234 |
|
| 235 |
// Diagnosed: Explicit instantiation was done by the user, we can prove it |
| 236 |
// is the same type. |
| 237 |
void instantiated(int A, Vector<int>::element_type B) { /* ... */ } |
| 238 |
|
| 239 |
// Diagnosed: The two parameter types are exactly the same. |
| 240 |
template <typename T> |
| 241 |
void exact(typename Vector<T>::element_type A, |
| 242 |
typename Vector<T>::element_type B) { /* ... */ } |
| 243 |
|
| 244 |
// Skipped: The two parameters are both 'T' but we cannot prove this |
| 245 |
// without actually instantiating. |
| 246 |
template <typename T> |
| 247 |
void falseNegative(T A, typename Vector<T>::element_type B) { /* ... */ } |
| 248 |
|
| 249 |
In the context of *implicit conversions* (when `ModelImplicitConversions` is |
| 250 |
enabled), the modelling performed by the check |
| 251 |
warns if the parameters are swappable and the swapped order matches implicit |
| 252 |
conversions. |
| 253 |
It does not model whether there exists an unrelated third type from which |
| 254 |
*both* parameters can be given in a function call. |
| 255 |
This means that in the following example, even while ``strs()`` clearly carries |
| 256 |
the possibility to be called with swapped arguments (as long as the arguments |
| 257 |
are string literals), will not be warned about. |
| 258 |
|
| 259 |
.. code-block:: c++ |
| 260 |
|
| 261 |
struct String { |
| 262 |
String(const char *Buf); |
| 263 |
}; |
| 264 |
|
| 265 |
struct StringView { |
| 266 |
StringView(const char *Buf); |
| 267 |
operator const char *() const; |
| 268 |
}; |
| 269 |
|
| 270 |
// Skipped: Directly swapping expressions of the two type cannot mix. |
| 271 |
// (Note: StringView -> const char * -> String would be **two** |
| 272 |
// user-defined conversions, which is disallowed by the language.) |
| 273 |
void strs(String Str, StringView SV) { /* ... */ } |
| 274 |
|
| 275 |
// Diagnosed: StringView implicitly converts to and from a buffer. |
| 276 |
void cStr(StringView SV, const char *Buf() { /* ... */ } |