142 lines · plain
1.. title:: clang-tidy - readability-qualified-auto2 3readability-qualified-auto4==========================5 6Adds pointer qualifications to ``auto``-typed variables that are deduced to7pointers.8 9`LLVM Coding Standards <https://llvm.org/docs/CodingStandards.html#beware-unnecessary-copies-with-auto>`_10advises to make it obvious if a ``auto`` typed variable is a pointer. This11check will transform ``auto`` to ``auto *`` when the type is deduced to be a12pointer.13 14.. code-block:: c++15 16 for (auto Data : MutatablePtrContainer) {17 change(*Data);18 }19 for (auto Data : ConstantPtrContainer) {20 observe(*Data);21 }22 23Would be transformed into:24 25.. code-block:: c++26 27 for (auto *Data : MutatablePtrContainer) {28 change(*Data);29 }30 for (const auto *Data : ConstantPtrContainer) {31 observe(*Data);32 }33 34Note ``const`` ``volatile`` qualified types will retain their ``const`` and35``volatile`` qualifiers. Pointers to pointers will not be fully qualified.36 37.. code-block:: c++38 39 const auto Foo = cast<int *>(Baz1);40 const auto Bar = cast<const int *>(Baz2);41 volatile auto FooBar = cast<int *>(Baz3);42 auto BarFoo = cast<int **>(Baz4);43 44Would be transformed into:45 46.. code-block:: c++47 48 auto *const Foo = cast<int *>(Baz1);49 const auto *const Bar = cast<const int *>(Baz2);50 auto *volatile FooBar = cast<int *>(Baz3);51 auto *BarFoo = cast<int **>(Baz4);52 53Options54-------55 56.. option:: AddConstToQualified57 58 When set to `true` the check will add const qualifiers variables defined as59 ``auto *`` or ``auto &`` when applicable.60 Default value is `true`.61 62.. code-block:: c++63 64 auto Foo1 = cast<const int *>(Bar1);65 auto *Foo2 = cast<const int *>(Bar2);66 auto &Foo3 = cast<const int &>(Bar3);67 68If AddConstToQualified is set to `false`, it will be transformed into:69 70.. code-block:: c++71 72 const auto *Foo1 = cast<const int *>(Bar1);73 auto *Foo2 = cast<const int *>(Bar2);74 auto &Foo3 = cast<const int &>(Bar3);75 76Otherwise it will be transformed into:77 78.. code-block:: c++79 80 const auto *Foo1 = cast<const int *>(Bar1);81 const auto *Foo2 = cast<const int *>(Bar2);82 const auto &Foo3 = cast<const int &>(Bar3);83 84Note in the LLVM alias, the default value is `false`.85 86.. option:: AllowedTypes87 88 A semicolon-separated list of names of types to ignore when ``auto`` is89 deduced to that type or a pointer to that type. Note that this distinguishes90 type aliases from the original type, so specifying e.g. ``my_int`` will not91 suppress reports about ``int`` even if it is defined as a ``typedef`` alias92 for ``int``. Regular expressions are accepted, e.g. ``[Rr]ef(erence)?$``93 matches every type with suffix ``Ref``, ``ref``, ``Reference`` and94 ``reference``. If a name in the list contains the sequence `::` it is matched95 against the qualified type name (i.e. ``namespace::Type``), otherwise it is96 matched against only the type name (i.e. ``Type``). E.g. to suppress reports97 for ``std::array`` iterators use `std::array<.*>::(const_)?iterator` string.98 The default is an empty string.99 100.. option:: IgnoreAliasing101 102 If set to `true` the check will use the underlying type to determine the type103 that ``auto`` is deduced to. If set to `false` the check will not look beyond104 the first type alias.105 Default value is `true`.106 107 .. code-block:: c++108 109 using IntPtr = int*;110 IntPtr foo();111 112 auto bar = foo();113 114 If :option:`IgnoreAliasing` is set to `true`, it will be transformed into:115 116 .. code-block:: c++117 118 auto *bar = foo();119 120 Otherwise no changes will occur.121 122 123Limitations124-----------125 126When :option:`IgnoreAliasing` is set to `false`, there are cases where127Clang has not preserved the type alias and the underlying type will be used so128false positives may occur.129 130For example:131 132.. code-block:: c++133 134 using IntPtr = int *;135 136 void loopPtr(const std::vector<IntPtr> &VectorIntPtr) {137 138 // May fail for IgnoreAliasing==false as AST does not have the 'IntPtr'139 for (auto Data : VectorIntPtr) {140 }141 }142