243 lines · plain
1.. title:: clang-tidy - misc-const-correctness2 3misc-const-correctness4======================5 6This check implements detection of local variables which could be declared as7``const`` but are not. Declaring variables as ``const`` is required or8recommended by many coding guidelines, such as:9`ES.25 <https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#es25-declare-an-object-const-or-constexpr-unless-you-want-to-modify-its-value-later-on>`_10from the C++ Core Guidelines.11 12Please note that this check's analysis is type-based only. Variables that are13not modified but used to create a non-const handle that might escape the scope14are not diagnosed as potential ``const``.15 16.. code-block:: c++17 18 // Declare a variable, which is not ``const`` ...19 int i = 42;20 // but use it as read-only. This means that `i` can be declared ``const``.21 int result = i * i; // Before transformation22 int const result = i * i; // After transformation23 24The check can analyze values, pointers and references and pointees:25 26.. code-block:: c++27 28 // Normal values like built-ins or objects.29 int potential_const_int = 42; // Before transformation30 int const potential_const_int = 42; // After transformation31 int copy_of_value = potential_const_int;32 33 MyClass could_be_const; // Before transformation34 MyClass const could_be_const; // After transformation35 could_be_const.const_qualified_method();36 37 // References can be declared const as well.38 int &reference_value = potential_const_int; // Before transformation39 int const& reference_value = potential_const_int; // After transformation40 int another_copy = reference_value;41 42 // The similar semantics of pointers are analyzed.43 int *pointer_variable = &potential_const_int; // Before transformation44 int const*const pointer_variable = &potential_const_int; // After transformation, both pointer itself and pointee are supported.45 int last_copy = *pointer_variable;46 47The automatic code transformation is only applied to variables that are48declared in single declarations. You may want to prepare your code base with49:doc:`readability-isolate-declaration <../readability/isolate-declaration>` first.50 51Note that there is the check52:doc:`cppcoreguidelines-avoid-non-const-global-variables <../cppcoreguidelines/avoid-non-const-global-variables>`53to enforce ``const`` correctness on all globals.54 55 56Limitations57-----------58 59The check does not run on `C` code.60 61The check will not analyze templated variables or variables that are62instantiation dependent. Different instantiations can result in63different ``const`` correctness properties and in general it is not64possible to find all instantiations of a template. The template might65be used differently in an independent translation unit.66 67Options68-------69 70.. option:: AnalyzeValues71 72 Enable or disable the analysis of ordinary value variables, like73 ``int i = 42;``. Default is `true`.74 75 .. code-block:: c++76 77 // Warning78 int i = 42;79 // No warning80 int const i = 42;81 82 // Warning83 int a[] = {42, 42, 42};84 // No warning85 int const a[] = {42, 42, 42};86 87.. option:: AnalyzeReferences88 89 Enable or disable the analysis of reference variables, like90 ``int &ref = i;``. Default is `true`.91 92 .. code-block:: c++93 94 int i = 42;95 // Warning96 int& ref = i;97 // No warning98 int const& ref = i;99 100.. option:: AnalyzePointers101 102 Enable or disable the analysis of pointers variables, like103 ``int *ptr = &i;``. For specific checks, see104 :option:`WarnPointersAsValues` and :option:`WarnPointersAsPointers`.105 Default is `true`.106 107.. option:: WarnPointersAsValues108 109 This option enables the suggestion for ``const`` of the pointer itself.110 Pointer values have two possibilities to be ``const``, the pointer111 and the value pointing to. Default is `false`.112 113 .. code-block:: c++114 115 int value = 42;116 117 // Warning118 const int * pointer_variable = &value;119 // No warning120 const int *const pointer_variable = &value;121 122.. option:: WarnPointersAsPointers123 124 This option enables the suggestion for ``const`` of the value pointing to.125 Default is `true`.126 127 Requires :option:`AnalyzePointers` to be `true`.128 129 .. code-block:: c++130 131 int value = 42;132 133 // No warning134 const int *const pointer_variable = &value;135 // Warning136 int *const pointer_variable = &value;137 138.. option:: TransformValues139 140 Provides fixit-hints for value types that automatically add ``const`` if141 its a single declaration. Default is `true`.142 143 .. code-block:: c++144 145 // Before146 int value = 42;147 // After148 int const value = 42;149 150 // Before151 int a[] = {42, 42, 42};152 // After153 int const a[] = {42, 42, 42};154 155 // Result is modified later in its life-time. No diagnostic and fixit hint will be emitted.156 int result = value * 3;157 result -= 10;158 159.. option:: TransformReferences160 161 Provides fixit-hints for reference types that automatically add ``const`` if162 its a single declaration. Default is `true`.163 164 .. code-block:: c++165 166 // This variable could still be a constant. But because there is a non-const reference to167 // it, it can not be transformed (yet).168 int value = 42;169 // The reference 'ref_value' is not modified and can be made 'const int &ref_value = value;'170 // Before171 int &ref_value = value;172 // After173 int const &ref_value = value;174 175 // Result is modified later in its life-time. No diagnostic and fixit hint will be emitted.176 int result = ref_value * 3;177 result -= 10;178 179.. option:: TransformPointersAsValues180 181 Provides fixit-hints for pointers if their pointee is not changed. This does182 not analyze if the value-pointed-to is unchanged! Default is `false`.183 184 Requires 'WarnPointersAsValues' to be 'true'.185 186 .. code-block:: c++187 188 int value = 42;189 190 // Before191 const int * pointer_variable = &value;192 // After193 const int *const pointer_variable = &value;194 195 // Before196 const int * a[] = {&value, &value};197 // After198 const int *const a[] = {&value, &value};199 200 // Before201 int *ptr_value = &value;202 // After203 int *const ptr_value = &value;204 205 int result = 100 * (*ptr_value); // Does not modify the pointer itself.206 // This modification of the pointee is still allowed and not diagnosed.207 *ptr_value = 0;208 209 // The following pointer may not become a 'int *const'.210 int *changing_pointee = &value;211 changing_pointee = &result;212 213.. option:: TransformPointersAsPointers214 215 Provides fix-it hints for pointers if the value it pointing to is not changed.216 Default is `false`.217 218 Requires :option:`WarnPointersAsPointers` to be `true`.219 220 .. code-block:: c++221 222 int value = 42;223 224 // Before225 int * pointer_variable = &value;226 // After227 const int * pointer_variable = &value;228 229 // Before230 int * a[] = {&value, &value};231 // After232 const int * a[] = {&value, &value};233 234.. option:: AllowedTypes235 236 A semicolon-separated list of names of types that will be excluded from237 const-correctness checking. Regular expressions are accepted, e.g.238 ``[Rr]ef(erence)?$`` matches every type with suffix ``Ref``, ``ref``,239 ``Reference`` and ``reference``. If a name in the list contains the sequence240 `::`, it is matched against the qualified type name241 (i.e. ``namespace::Type``), otherwise it is matched against only the type242 name (i.e. ``Type``). Default is empty string.243