Debian Codegraph @

llvm-project/clang-tools-extra/docs/clang-tidy/checks/bugprone/unchecked-optional-access.rst

raw
1 .. title:: clang-tidy - bugprone-unchecked-optional-access
2
3 bugprone-unchecked-optional-access
4 ==================================
5
6 *Note*: This check uses a flow-sensitive static analysis to produce its
7 results. Therefore, it may be more resource intensive (RAM, CPU) than the
8 average clang-tidy check.
9
10 This check identifies unsafe accesses to values contained in
11 ``std::optional<T>``, ``absl::optional<T>``, or ``base::std::optional<T>``
12 objects. Below we will refer to all these types collectively as
13 ``optional<T>``.
14
15 An access to the value of an ``optional<T>`` occurs when one of its
16 ``value``, ``operator*``, or ``operator->`` member functions is invoked.
17 To align with common misconceptions, the check considers these member
18 functions as equivalent, even though there are subtle differences
19 related to exceptions versus undefined behavior. See
20 go/optional-style-recommendations for more information on that topic.
21
22 An access to the value of an ``optional<T>`` is considered safe if and only if
23 code in the local scope (for example, a function body) ensures that the
24 ``optional<T>`` has a value in all possible execution paths that can reach the
25 access. That should happen either through an explicit check, using the
26 ``optional<T>::has_value`` member function, or by constructing the
27 ``optional<T>`` in a way that shows that it unambiguously holds a value (e.g
28 using ``std::make_optional`` which always returns a populated
29 ``std::optional<T>``).
30
31 Below we list some examples, starting with unsafe optional access patterns,
32 followed by safe access patterns.
33
34 Unsafe access patterns
35 ~~~~~~~~~~~~~~~~~~~~~~
36
37 Access the value without checking if it exists
38 ----------------------------------------------
39
40 The check flags accesses to the value that are not locally guarded by
41 existence check:
42
43 .. code-block:: c++
44
45 void f(std::optional<int> opt) {
46 use(*opt); // unsafe: it is unclear whether `opt` has a value.
47 }
48
49 Access the value in the wrong branch
50 ------------------------------------
51
52 The check is aware of the state of an optional object in different
53 branches of the code. For example:
54
55 .. code-block:: c++
56
57 void f(std::optional<int> opt) {
58 if (opt.has_value()) {
59 } else {
60 use(opt.value()); // unsafe: it is clear that `opt` does *not* have a value.
61 }
62 }
63
64 Assume a function result to be stable
65 -------------------------------------
66
67 The check is aware that function results might not be stable. That is,
68 consecutive calls to the same function might return different values.
69 For example:
70
71 .. code-block:: c++
72
73 void f(Foo foo) {
74 if (foo.opt().has_value()) {
75 use(*foo.opt()); // unsafe: it is unclear whether `foo.opt()` has a value.
76 }
77 }
78
79 Rely on invariants of uncommon APIs
80 -----------------------------------
81
82 The check is unaware of invariants of uncommon APIs. For example:
83
84 .. code-block:: c++
85
86 void f(Foo foo) {
87 if (foo.HasProperty("bar")) {
88 use(*foo.GetProperty("bar")); // unsafe: it is unclear whether `foo.GetProperty("bar")` has a value.
89 }
90 }
91
92 Check if a value exists, then pass the optional to another function
93 -------------------------------------------------------------------
94
95 The check relies on local reasoning. The check and value access must
96 both happen in the same function. An access is considered unsafe even if
97 the caller of the function performing the access ensures that the
98 optional has a value. For example:
99
100 .. code-block:: c++
101
102 void g(std::optional<int> opt) {
103 use(*opt); // unsafe: it is unclear whether `opt` has a value.
104 }
105
106 void f(std::optional<int> opt) {
107 if (opt.has_value()) {
108 g(opt);
109 }
110 }
111
112 Safe access patterns
113 ~~~~~~~~~~~~~~~~~~~~
114
115 Check if a value exists, then access the value
116 ----------------------------------------------
117
118 The check recognizes all straightforward ways for checking if a value
119 exists and accessing the value contained in an optional object. For
120 example:
121
122 .. code-block:: c++
123
124 void f(std::optional<int> opt) {
125 if (opt.has_value()) {
126 use(*opt);
127 }
128 }
129
130
131 Check if a value exists, then access the value from a copy
132 ----------------------------------------------------------
133
134 The criteria that the check uses is semantic, not syntactic. It
135 recognizes when a copy of the optional object being accessed is known to
136 have a value. For example:
137
138 .. code-block:: c++
139
140 void f(std::optional<int> opt1) {
141 if (opt1.has_value()) {
142 std::optional<int> opt2 = opt1;
143 use(*opt2);
144 }
145 }
146
147
148 Ensure that a value exists using common macros
149 ----------------------------------------------
150
151 The check is aware of common macros like ``CHECK``, ``DCHECK``, and
152 ``ASSERT_THAT``. Those can be used to ensure that an optional object has
153 a value. For example:
154
155 .. code-block:: c++
156
157 void f(std::optional<int> opt) {
158 DCHECK(opt.has_value());
159 use(*opt);
160 }
161
162 Ensure that a value exists, then access the value in a correlated branch
163 ------------------------------------------------------------------------
164
165 The check is aware of correlated branches in the code and can figure out
166 when an optional object is ensured to have a value on all execution
167 paths that lead to an access. For example:
168
169 .. code-block:: c++
170
171 void f(std::optional<int> opt) {
172 bool safe = false;
173 if (opt.has_value() && SomeOtherCondition()) {
174 safe = true;
175 }
176 // ... more code...
177 if (safe) {
178 use(*opt);
179 }
180 }
181
182 Stabilize function results
183 ~~~~~~~~~~~~~~~~~~~~~~~~~~
184
185 Since function results are not assumed to be stable across calls, it is best to
186 store the result of the function call in a local variable and use that variable
187 to access the value. For example:
188
189 .. code-block:: c++
190
191 void f(Foo foo) {
192 if (const auto& foo_opt = foo.opt(); foo_opt.has_value()) {
193 use(*foo_opt);
194 }
195 }
196
197 Do not rely on uncommon-API invariants
198 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
199
200 When uncommon APIs guarantee that an optional has contents, do not rely on it --
201 instead, check explicitly that the optional object has a value. For example:
202
203 .. code-block:: c++
204
205 void f(Foo foo) {
206 if (const auto& property = foo.GetProperty("bar")) {
207 use(*property);
208 }
209 }
210
211 instead of the `HasProperty`, `GetProperty` pairing we saw above.
212
213 Do not rely on caller-performed checks
214 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
215
216 If you know that all of a function's callers have checked that an optional
217 argument has a value, either change the function to take the value directly or
218 check the optional again in the local scope of the callee. For example:
219
220 .. code-block:: c++
221
222 void g(int val) {
223 use(val);
224 }
225
226 void f(std::optional<int> opt) {
227 if (opt.has_value()) {
228 g(*opt);
229 }
230 }
231
232 and
233
234 .. code-block:: c++
235
236 struct S {
237 std::optional<int> opt;
238 int x;
239 };
240
241 void g(const S &s) {
242 if (s.opt.has_value() && s.x > 10) {
243 use(*s.opt);
244 }
245
246 void f(S s) {
247 if (s.opt.has_value()) {
248 g(s);
249 }
250 }
251
252 Additional notes
253 ~~~~~~~~~~~~~~~~
254
255 Aliases created via ``using`` declarations
256 ------------------------------------------
257
258 The check is aware of aliases of optional types that are created via
259 ``using`` declarations. For example:
260
261 .. code-block:: c++
262
263 using OptionalInt = std::optional<int>;
264
265 void f(OptionalInt opt) {
266 use(opt.value()); // unsafe: it is unclear whether `opt` has a value.
267 }
268
269 Lambdas
270 -------
271
272 The check does not currently report unsafe optional accesses in lambdas.
273 A future version will expand the scope to lambdas, following the rules
274 outlined above. It is best to follow the same principles when using
275 optionals in lambdas.