Debian Codegraph @

clang-tools-extra/docs/clang-tidy/checks/misc/const-correctness.rst

raw
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;