clang-tools-extra/docs/clang-tidy/checks/bugprone/easily-swappable-parameters.rst

   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() { /* ... */ }