Debian Codegraph @

llvm-project/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 `CppCoreGuidelines ES.25 <https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#es25-declare-an-object-const-or-constexpr-unless-you-want-to-modify-its-value-later-on>`_
10 and `AUTOSAR C++14 Rule A7-1-1 (6.7.1 Specifiers) <https://www.autosar.org/fileadmin/user_upload/standards/adaptive/17-03/AUTOSAR_RS_CPP14Guidelines.pdf>`_.
11
12 Please note that this check's analysis is type-based only. Variables that are not modified
13 but used to create a non-const handle that might escape the scope are not diagnosed
14 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 transformation
22 int const result = i * i; // After transformation
23
24 The 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
46 The automatic code transformation is only applied to variables that are declared in single
47 declarations. You may want to prepare your code base with
48 `readability-isolate-declaration <../readability/isolate-declaration.html>`_ first.
49
50 Note that there is the check
51 `cppcoreguidelines-avoid-non-const-global-variables <../cppcoreguidelines/avoid-non-const-global-variables.html>`_
52 to enforce ``const`` correctness on all globals.
53
54 Known Limitations
55 -----------------
56
57 The check does not run on `C` code.
58
59 The check will not analyze templated variables or variables that are instantiation dependent.
60 Different instantiations can result in different ``const`` correctness properties and in general it
61 is not possible to find all instantiations of a template. The template might be used differently in
62 an independent translation unit.
63
64 Pointees 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
78 This limitation affects the capability to add ``const`` to methods which is not possible, too.
79
80 Options
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;