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