Debian Codegraph @

clang-tools-extra/docs/clang-tidy/checks/modernize/replace-auto-ptr.rst

raw
1 .. title:: clang-tidy - modernize-replace-auto-ptr
2
3 modernize-replace-auto-ptr
4 ==========================
5
6 This check replaces the uses of the deprecated class ``std::auto_ptr`` by
7 ``std::unique_ptr`` (introduced in C++11). The transfer of ownership, done
8 by the copy-constructor and the assignment operator, is changed to match
9 ``std::unique_ptr`` usage by using explicit calls to ``std::move()``.
10
11 Migration example:
12
13 .. code-block:: c++
14
15 -void take_ownership_fn(std::auto_ptr<int> int_ptr);
16 +void take_ownership_fn(std::unique_ptr<int> int_ptr);
17
18 void f(int x) {
19 - std::auto_ptr<int> a(new int(x));
20 - std::auto_ptr<int> b;
21 + std::unique_ptr<int> a(new int(x));
22 + std::unique_ptr<int> b;
23
24 - b = a;
25 - take_ownership_fn(b);
26 + b = std::move(a);
27 + take_ownership_fn(std::move(b));
28 }
29
30 Since ``std::move()`` is a library function declared in ``<utility>`` it may be
31 necessary to add this include. The check will add the include directive when
32 necessary.
33
34 Known Limitations
35 -----------------
36 * If headers modification is not activated or if a header is not allowed to be
37 changed this check will produce broken code (compilation error), where the
38 headers' code will stay unchanged while the code using them will be changed.
39
40 * Client code that declares a reference to an ``std::auto_ptr`` coming from
41 code that can't be migrated (such as a header coming from a 3\ :sup:`rd`
42 party library) will produce a compilation error after migration. This is
43 because the type of the reference will be changed to ``std::unique_ptr`` but
44 the type returned by the library won't change, binding a reference to
45 ``std::unique_ptr`` from an ``std::auto_ptr``. This pattern doesn't make much
46 sense and usually ``std::auto_ptr`` are stored by value (otherwise what is
47 the point in using them instead of a reference or a pointer?).
48
49 .. code-block:: c++
50
51 // <3rd-party header...>
52 std::auto_ptr<int> get_value();
53 const std::auto_ptr<int> & get_ref();
54
55 // <calling code (with migration)...>
56 -std::auto_ptr<int> a(get_value());
57 +std::unique_ptr<int> a(get_value()); // ok, unique_ptr constructed from auto_ptr
58
59 -const std::auto_ptr<int> & p = get_ptr();
60 +const std::unique_ptr<int> & p = get_ptr(); // won't compile
61
62 * Non-instantiated templates aren't modified.
63
64 .. code-block:: c++
65
66 template <typename X>
67 void f() {
68 std::auto_ptr<X> p;
69 }
70
71 // only 'f<int>()' (or similar) will trigger the replacement.
72
73 Options
74 -------
75
76 .. option:: IncludeStyle
77
78 A string specifying which include-style is used, `llvm` or `google`. Default
79 is `llvm`.