Debian Codegraph @

llvm-project/clang-tools-extra/docs/clang-tidy/checks/modernize/loop-convert.rst

raw
1 .. title:: clang-tidy - modernize-loop-convert
2
3 modernize-loop-convert
4 ======================
5
6 This check converts ``for(...; ...; ...)`` loops to use the new range-based
7 loops in C++11.
8
9 Three kinds of loops can be converted:
10
11 - Loops over statically allocated arrays.
12 - Loops over containers, using iterators.
13 - Loops over array-like containers, using ``operator[]`` and ``at()``.
14
15 MinConfidence option
16 --------------------
17
18 risky
19 ^^^^^
20
21 In loops where the container expression is more complex than just a
22 reference to a declared expression (a variable, function, enum, etc.),
23 and some part of it appears elsewhere in the loop, we lower our confidence
24 in the transformation due to the increased risk of changing semantics.
25 Transformations for these loops are marked as `risky`, and thus will only
26 be converted if the minimum required confidence level is set to `risky`.
27
28 .. code-block:: c++
29
30 int arr[10][20];
31 int l = 5;
32
33 for (int j = 0; j < 20; ++j)
34 int k = arr[l][j] + l; // using l outside arr[l] is considered risky
35
36 for (int i = 0; i < obj.getVector().size(); ++i)
37 obj.foo(10); // using 'obj' is considered risky
38
39 See
40 :ref:`Range-based loops evaluate end() only once<IncorrectRiskyTransformation>`
41 for an example of an incorrect transformation when the minimum required confidence
42 level is set to `risky`.
43
44 reasonable (Default)
45 ^^^^^^^^^^^^^^^^^^^^
46
47 If a loop calls ``.end()`` or ``.size()`` after each iteration, the
48 transformation for that loop is marked as `reasonable`, and thus will
49 be converted if the required confidence level is set to `reasonable`
50 (default) or lower.
51
52 .. code-block:: c++
53
54 // using size() is considered reasonable
55 for (int i = 0; i < container.size(); ++i)
56 cout << container[i];
57
58 safe
59 ^^^^
60
61 Any other loops that do not match the above criteria to be marked as
62 `risky` or `reasonable` are marked `safe`, and thus will be converted
63 if the required confidence level is set to `safe` or lower.
64
65 .. code-block:: c++
66
67 int arr[] = {1,2,3};
68
69 for (int i = 0; i < 3; ++i)
70 cout << arr[i];
71
72 Example
73 -------
74
75 Original:
76
77 .. code-block:: c++
78
79 const int N = 5;
80 int arr[] = {1,2,3,4,5};
81 vector<int> v;
82 v.push_back(1);
83 v.push_back(2);
84 v.push_back(3);
85
86 // safe conversion
87 for (int i = 0; i < N; ++i)
88 cout << arr[i];
89
90 // reasonable conversion
91 for (vector<int>::iterator it = v.begin(); it != v.end(); ++it)
92 cout << *it;
93
94 // reasonable conversion
95 for (int i = 0; i < v.size(); ++i)
96 cout << v[i];
97
98 After applying the check with minimum confidence level set to `reasonable` (default):
99
100 .. code-block:: c++
101
102 const int N = 5;
103 int arr[] = {1,2,3,4,5};
104 vector<int> v;
105 v.push_back(1);
106 v.push_back(2);
107 v.push_back(3);
108
109 // safe conversion
110 for (auto & elem : arr)
111 cout << elem;
112
113 // reasonable conversion
114 for (auto & elem : v)
115 cout << elem;
116
117 // reasonable conversion
118 for (auto & elem : v)
119 cout << elem;
120
121 Reverse Iterator Support
122 ------------------------
123
124 The converter is also capable of transforming iterator loops which use
125 ``rbegin`` and ``rend`` for looping backwards over a container. Out of the box
126 this will automatically happen in C++20 mode using the ``ranges`` library,
127 however the check can be configured to work without C++20 by specifying a
128 function to reverse a range and optionally the header file where that function
129 lives.
130
131 .. option:: UseCxx20ReverseRanges
132
133 When set to true convert loops when in C++20 or later mode using
134 ``std::ranges::reverse_view``.
135 Default value is ``true``.
136
137 .. option:: MakeReverseRangeFunction
138
139 Specify the function used to reverse an iterator pair, the function should
140 accept a class with ``rbegin`` and ``rend`` methods and return a
141 class with ``begin`` and ``end`` methods that call the ``rbegin`` and
142 ``rend`` methods respectively. Common examples are ``ranges::reverse_view``
143 and ``llvm::reverse``.
144 Default value is an empty string.
145
146 .. option:: MakeReverseRangeHeader
147
148 Specifies the header file where :option:`MakeReverseRangeFunction` is
149 declared. For the previous examples this option would be set to
150 ``range/v3/view/reverse.hpp`` and ``llvm/ADT/STLExtras.h`` respectively.
151 If this is an empty string and :option:`MakeReverseRangeFunction` is set,
152 the check will proceed on the assumption that the function is already
153 available in the translation unit.
154 This can be wrapped in angle brackets to signify to add the include as a
155 system include.
156 Default value is an empty string.
157
158 .. option:: IncludeStyle
159
160 A string specifying which include-style is used, `llvm` or `google`. Default
161 is `llvm`.
162
163 Limitations
164 -----------
165
166 There are certain situations where the tool may erroneously perform
167 transformations that remove information and change semantics. Users of the tool
168 should be aware of the behavior and limitations of the check outlined by
169 the cases below.
170
171 Comments inside loop headers
172 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
173
174 Comments inside the original loop header are ignored and deleted when
175 transformed.
176
177 .. code-block:: c++
178
179 for (int i = 0; i < N; /* This will be deleted */ ++i) { }
180
181 Range-based loops evaluate end() only once
182 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
183
184 The C++11 range-based for loop calls ``.end()`` only once during the
185 initialization of the loop. If in the original loop ``.end()`` is called after
186 each iteration the semantics of the transformed loop may differ.
187
188 .. code-block:: c++
189
190 // The following is semantically equivalent to the C++11 range-based for loop,
191 // therefore the semantics of the header will not change.
192 for (iterator it = container.begin(), e = container.end(); it != e; ++it) { }
193
194 // Instead of calling .end() after each iteration, this loop will be
195 // transformed to call .end() only once during the initialization of the loop,
196 // which may affect semantics.
197 for (iterator it = container.begin(); it != container.end(); ++it) { }
198
199 .. _IncorrectRiskyTransformation:
200
201 As explained above, calling member functions of the container in the body
202 of the loop is considered `risky`. If the called member function modifies the
203 container the semantics of the converted loop will differ due to ``.end()``
204 being called only once.
205
206 .. code-block:: c++
207
208 bool flag = false;
209 for (vector<T>::iterator it = vec.begin(); it != vec.end(); ++it) {
210 // Add a copy of the first element to the end of the vector.
211 if (!flag) {
212 // This line makes this transformation 'risky'.
213 vec.push_back(*it);
214 flag = true;
215 }
216 cout << *it;
217 }
218
219 The original code above prints out the contents of the container including the
220 newly added element while the converted loop, shown below, will only print the
221 original contents and not the newly added element.
222
223 .. code-block:: c++
224
225 bool flag = false;
226 for (auto & elem : vec) {
227 // Add a copy of the first element to the end of the vector.
228 if (!flag) {
229 // This line makes this transformation 'risky'
230 vec.push_back(elem);
231 flag = true;
232 }
233 cout << elem;
234 }
235
236 Semantics will also be affected if ``.end()`` has side effects. For example, in
237 the case where calls to ``.end()`` are logged the semantics will change in the
238 transformed loop if ``.end()`` was originally called after each iteration.
239
240 .. code-block:: c++
241
242 iterator end() {
243 num_of_end_calls++;
244 return container.end();
245 }
246
247 Overloaded operator->() with side effects
248 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
249
250 Similarly, if ``operator->()`` was overloaded to have side effects, such as
251 logging, the semantics will change. If the iterator's ``operator->()`` was used
252 in the original loop it will be replaced with ``<container element>.<member>``
253 instead due to the implicit dereference as part of the range-based for loop.
254 Therefore any side effect of the overloaded ``operator->()`` will no longer be
255 performed.
256
257 .. code-block:: c++
258
259 for (iterator it = c.begin(); it != c.end(); ++it) {
260 it->func(); // Using operator->()
261 }
262 // Will be transformed to:
263 for (auto & elem : c) {
264 elem.func(); // No longer using operator->()
265 }
266
267 Pointers and references to containers
268 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
269
270 While most of the check's risk analysis is dedicated to determining whether
271 the iterator or container was modified within the loop, it is possible to
272 circumvent the analysis by accessing and modifying the container through a
273 pointer or reference.
274
275 If the container were directly used instead of using the pointer or reference
276 the following transformation would have only been applied at the `risky`
277 level since calling a member function of the container is considered `risky`.
278 The check cannot identify expressions associated with the container that are
279 different than the one used in the loop header, therefore the transformation
280 below ends up being performed at the `safe` level.
281
282 .. code-block:: c++
283
284 vector<int> vec;
285
286 vector<int> *ptr = &vec;
287 vector<int> &ref = vec;
288
289 for (vector<int>::iterator it = vec.begin(), e = vec.end(); it != e; ++it) {
290 if (!flag) {
291 // Accessing and modifying the container is considered risky, but the risk
292 // level is not raised here.
293 ptr->push_back(*it);
294 ref.push_back(*it);
295 flag = true;
296 }
297 }
298
299 OpenMP
300 ^^^^^^
301
302 As range-based for loops are only available since OpenMP 5, this check should
303 not be used on code with a compatibility requirement of OpenMP prior to
304 version 5. It is **intentional** that this check does not make any attempts to
305 exclude incorrect diagnostics on OpenMP for loops prior to OpenMP 5.
306
307 To prevent this check to be applied (and to break) OpenMP for loops but still be
308 applied to non-OpenMP for loops the usage of ``NOLINT`` (see
309 :ref:`clang-tidy-nolint`) on the specific for loops is recommended.