1.. title:: clang-tidy - misc-const-correctness 2 3misc-const-correctness 4====================== 5 6This check implements detection of local variables which could be declared as 7``const`` but are not. Declaring variables as ``const`` is required or recommended by many 8coding 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 are not modified 13but used to create a non-const handle that might escape the scope are not diagnosed 14as 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 transformation 22 int const result = i * i; // After transformation 23 24The check can analyze values, pointers and references but not (yet) pointees: 25 26.. code-block:: c++ 27 28 // Normal values like built-ins or objects. 29 int potential_const_int = 42; // Before transformation 30 int const potential_const_int = 42; // After transformation 31 int copy_of_value = potential_const_int; 32 33 MyClass could_be_const; // Before transformation 34 MyClass const could_be_const; // After transformation 35 could_be_const.const_qualified_method(); 36 37 // References can be declared const as well. 38 int &reference_value = potential_const_int; // Before transformation 39 int const& reference_value = potential_const_int; // After transformation 40 int another_copy = reference_value; 41 42 // The similar semantics of pointers are not (yet) analyzed. 43 int *pointer_variable = &potential_const_int; // _NO_ 'const int *pointer_variable' suggestion. 44 int last_copy = *pointer_variable; 45 46The automatic code transformation is only applied to variables that are declared in single 47declarations. You may want to prepare your code base with 48:doc:`readability-isolate-declaration <../readability/isolate-declaration>` first. 49 50Note that there is the check 51:doc:`cppcoreguidelines-avoid-non-const-global-variables <../cppcoreguidelines/avoid-non-const-global-variables>` 52to enforce ``const`` correctness on all globals. 53 54Known Limitations 55----------------- 56 57The check does not run on `C` code. 58 59The check will not analyze templated variables or variables that are instantiation dependent. 60Different instantiations can result in different ``const`` correctness properties and in general it 61is not possible to find all instantiations of a template. The template might be used differently in 62an independent translation unit. 63 64Pointees can not be analyzed for constness yet. The following code shows this limitation. 65 66.. code-block:: c++ 67 68 // Declare a variable that will not be modified. 69 int constant_value = 42; 70 71 // Declare a pointer to that variable, that does not modify either, but misses 'const'. 72 // Could be 'const int *pointer_to_constant = &constant_value;' 73 int *pointer_to_constant = &constant_value; 74 75 // Usage: 76 int result = 520 * 120 * (*pointer_to_constant); 77 78This limitation affects the capability to add ``const`` to methods which is not possible, too. 79 80Options 81------- 82 83.. option:: AnalyzeValues (default = true) 84 85 Enable or disable the analysis of ordinary value variables, like ``int i = 42;`` 86 87 .. code-block:: c++ 88 89 // Warning 90 int i = 42; 91 // No warning 92 int const i = 42; 93 94 // Warning 95 int a[] = {42, 42, 42}; 96 // No warning 97 int const a[] = {42, 42, 42}; 98 99.. option:: AnalyzeReferences (default = true) 100 101 Enable or disable the analysis of reference variables, like ``int &ref = i;`` 102 103 .. code-block:: c++ 104 105 int i = 42; 106 // Warning 107 int& ref = i; 108 // No warning 109 int const& ref = i; 110 111.. option:: WarnPointersAsValues (default = false) 112 113 This option enables the suggestion for ``const`` of the pointer itself. 114 Pointer values have two possibilities to be ``const``, the pointer 115 and the value pointing to. 116 117 .. code-block:: c++ 118 119 int value = 42; 120 121 // Warning 122 const int * pointer_variable = &value; 123 // No warning 124 const int *const pointer_variable = &value; 125 126.. option:: TransformValues (default = true) 127 128 Provides fixit-hints for value types that automatically add ``const`` if its a single declaration. 129 130 .. code-block:: c++ 131 132 // Before 133 int value = 42; 134 // After 135 int const value = 42; 136 137 // Before 138 int a[] = {42, 42, 42}; 139 // After 140 int const a[] = {42, 42, 42}; 141 142 // Result is modified later in its life-time. No diagnostic and fixit hint will be emitted. 143 int result = value * 3; 144 result -= 10; 145 146.. option:: TransformReferences (default = true) 147 148 Provides fixit-hints for reference types that automatically add ``const`` if its a single 149 declaration. 150 151 .. code-block:: c++ 152 153 // This variable could still be a constant. But because there is a non-const reference to 154 // it, it can not be transformed (yet). 155 int value = 42; 156 // The reference 'ref_value' is not modified and can be made 'const int &ref_value = value;' 157 // Before 158 int &ref_value = value; 159 // After 160 int const &ref_value = value; 161 162 // Result is modified later in its life-time. No diagnostic and fixit hint will be emitted. 163 int result = ref_value * 3; 164 result -= 10; 165 166.. option:: TransformPointersAsValues (default = false) 167 168 Provides fixit-hints for pointers if their pointee is not changed. This does not analyze if the 169 value-pointed-to is unchanged! 170 171 Requires 'WarnPointersAsValues' to be 'true'. 172 173 .. code-block:: c++ 174 175 int value = 42; 176 177 // Before 178 const int * pointer_variable = &value; 179 // After 180 const int *const pointer_variable = &value; 181 182 // Before 183 const int * a[] = {&value, &value}; 184 // After 185 const int *const a[] = {&value, &value}; 186 187 // Before 188 int *ptr_value = &value; 189 // After 190 int *const ptr_value = &value; 191 192 int result = 100 * (*ptr_value); // Does not modify the pointer itself. 193 // This modification of the pointee is still allowed and not diagnosed. 194 *ptr_value = 0; 195 196 // The following pointer may not become a 'int *const'. 197 int *changing_pointee = &value; 198 changing_pointee = &result; 199