Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
qscopedpointer.qdoc
Go to the documentation of this file.
1// Copyright (C) 2016 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
3
4/*!
5 \class QScopedPointer
6 \inmodule QtCore
7 \brief The QScopedPointer class stores a pointer to a dynamically allocated object, and deletes it upon destruction.
8 \since 4.6
9 \reentrant
10 \ingroup misc
11
12 Managing heap allocated objects manually is hard and error prone, with the
13 common result that code leaks memory and is hard to maintain.
14 QScopedPointer is a small utility class that heavily simplifies this by
15 assigning stack-based memory ownership to heap allocations, more generally
16 called resource acquisition is initialization(RAII). The template parameter
17 \a T specifies the type of the pointer being managed.
18
19 QScopedPointer guarantees that the object pointed to will get deleted when
20 the current scope disappears.
21
22 Consider this function which does heap allocations, and has various exit points:
23
24 \snippet code/src_corelib_tools_qscopedpointer.cpp 0
25
26 It's encumbered by the manual delete calls. With QScopedPointer, the code
27 can be simplified to:
28
29 \snippet code/src_corelib_tools_qscopedpointer.cpp 1
30
31 The code the compiler generates for QScopedPointer is the same as when
32 writing it manually. Code that makes use of \c delete are candidates for
33 QScopedPointer usage (and if not, possibly another type of smart pointer
34 such as QSharedPointer). QScopedPointer intentionally has no copy
35 constructor or assignment operator, such that ownership and lifetime is
36 clearly communicated.
37
38 The const qualification on a regular C++ pointer can also be expressed with
39 a QScopedPointer:
40
41 \snippet code/src_corelib_tools_qscopedpointer.cpp 2.0
42 \snippet code/src_corelib_tools_qscopedpointer.cpp 2.1
43 \snippet code/src_corelib_tools_qscopedpointer.cpp 2.2
44
45 \section1 Custom Cleanup Handlers
46
47 Arrays as well as pointers that have been allocated with \c malloc must
48 not be deleted using \c delete. The \a Cleanup template parameter specifies
49 the cleanup handler to use when the scoped pointer is destroyed;
50 QScopedPointerDeleter is used by default.
51
52 The following custom cleanup handlers exist:
53
54 \list
55 \li QScopedPointerDeleter - the default, deletes the pointer using \c delete
56 \li QScopedPointerArrayDeleter - deletes the pointer using \c{delete []}. Use
57 this handler for pointers that were allocated with \c{new []}.
58 \li QScopedPointerPodDeleter - deletes the pointer using \c{free()}. Use this
59 handler for pointers that were allocated with \c{malloc()}.
60 \li QScopedPointerDeleteLater - deletes a pointer by calling \c{deleteLater()}
61 on it. Use this handler for pointers to QObject's that are actively
62 participating in a QEventLoop.
63 \endlist
64
65 You can pass your own classes as handlers, provided that they have a public
66 static function \c{void cleanup(T *pointer)}.
67
68 \snippet code/src_corelib_tools_qscopedpointer.cpp 5
69
70 \section1 Forward Declared Pointers
71
72 Classes that are forward declared can be used within QScopedPointer, as
73 long as the destructor of the forward declared class is available whenever
74 a QScopedPointer needs to clean up.
75
76 Concretely, this means that all classes containing a QScopedPointer that
77 points to a forward declared class must have non-inline constructors,
78 destructors and assignment operators:
79
80 \snippet code/src_corelib_tools_qscopedpointer.cpp 4
81
82 Otherwise, the compiler outputs a warning about not being able to destruct
83 \c MyPrivateClass.
84
85 \sa QSharedPointer
86*/
87
88/*! \typedef QScopedPointer::pointer
89 \internal
90 */
91
92/*!
93 \fn template <typename T, typename Cleanup> QScopedPointer<T, Cleanup>::QScopedPointer(T *p = nullptr)
94
95 Constructs this QScopedPointer instance and sets its pointer to \a p.
96*/
97
98/*!
99 \fn template <typename T, typename Cleanup> QScopedPointer<T, Cleanup>::~QScopedPointer()
100
101 Destroys this QScopedPointer object. Delete the object its pointer points
102 to.
103*/
104
105/*!
106 \fn template <typename T, typename Cleanup> T *QScopedPointer<T, Cleanup>::data() const
107
108 Returns the value of the pointer referenced by this object. QScopedPointer
109 still owns the object pointed to.
110*/
111
112/*!
113 \fn template <typename T, typename Cleanup> T *QScopedPointer<T, Cleanup>::get() const
114 \since 5.11
115
116 Same as data().
117*/
118
119/*!
120 \fn template <typename T, typename Cleanup> T &QScopedPointer<T, Cleanup>::operator*() const
121
122 Provides access to the scoped pointer's object.
123
124 If the contained pointer is \nullptr, behavior is undefined.
125 \sa isNull()
126*/
127
128/*!
129 \fn template <typename T, typename Cleanup> T *QScopedPointer<T, Cleanup>::operator->() const
130
131 Provides access to the scoped pointer's object.
132
133 If the contained pointer is \nullptr, behavior is undefined.
134
135 \sa isNull()
136*/
137
138/*!
139 \fn template <typename T, typename Cleanup> QScopedPointer<T, Cleanup>::operator bool() const
140
141 Returns \c true if the contained pointer is not \nullptr.
142 This function is suitable for use in \tt if-constructs, like:
143
144 \snippet code/src_corelib_tools_qscopedpointer.cpp 3
145
146 \sa isNull()
147*/
148
149/*!
150 \fn template <typename T, typename Cleanup> bool QScopedPointer<T, Cleanup>::operator==(const QScopedPointer<T, Cleanup> &lhs, const QScopedPointer<T, Cleanup> &rhs)
151
152 Returns \c true if \a lhs and \a rhs refer to the same pointer.
153*/
154
155
156/*!
157 \fn template <typename T, typename Cleanup> bool QScopedPointer<T, Cleanup>::operator!=(const QScopedPointer<T, Cleanup> &lhs, const QScopedPointer<T, Cleanup> &rhs)
158
159 Returns \c true if \a lhs and \a rhs refer to distinct pointers.
160*/
161
162/*!
163 \fn template <typename T, typename Cleanup> bool QScopedPointer<T, Cleanup>::operator==(const QScopedPointer<T, Cleanup> &lhs, std::nullptr_t)
164 \since 5.8
165
166 Returns \c true if \a lhs refers to \nullptr.
167
168 \sa QScopedPointer::isNull()
169*/
170
171/*!
172 \fn template <typename T, typename Cleanup> bool QScopedPointer<T, Cleanup>::operator==(std::nullptr_t, const QScopedPointer<T, Cleanup> &rhs)
173 \since 5.8
174
175 Returns \c true if \a rhs refers to \nullptr.
176
177 \sa QScopedPointer::isNull()
178*/
179
180/*!
181 \fn template <typename T, typename Cleanup> bool QScopedPointer<T, Cleanup>::operator!=(const QScopedPointer<T, Cleanup> &lhs, std::nullptr_t)
182 \since 5.8
183
184 Returns \c true if \a lhs refers to a valid (i.e. non-null) pointer.
185
186 \sa QScopedPointer::isNull()
187*/
188
189/*!
190 \fn template <typename T, typename Cleanup> bool QScopedPointer<T, Cleanup>::operator!=(std::nullptr_t, const QScopedPointer<T, Cleanup> &rhs)
191 \since 5.8
192
193 Returns \c true if \a rhs refers to a valid (i.e. non-null) pointer.
194
195 \sa QScopedPointer::isNull()
196*/
197
198/*!
199 \fn template <typename T, typename Cleanup> bool QScopedPointer<T, Cleanup>::isNull() const
200
201 Returns \c true if this object refers to \nullptr.
202*/
203
204/*!
205 \fn template <typename T, typename Cleanup> void QScopedPointer<T, Cleanup>::reset(T *other = nullptr)
206
207 Deletes the existing object it is pointing to (if any), and sets its pointer to
208 \a other. QScopedPointer now owns \a other and will delete it in its
209 destructor.
210*/
211
212/*!
213 \fn template <typename T, typename Cleanup> T *QScopedPointer<T, Cleanup>::take()
214
215 \deprecated [6.1] Use \c std::unique_ptr and \c release() instead.
216
217 Returns the value of the pointer referenced by this object. The pointer of this
218 QScopedPointer object will be reset to \nullptr.
219
220 Callers of this function take ownership of the pointer.
221*/
222
223/*! \fn template <typename T, typename Cleanup> bool QScopedPointer<T, Cleanup>::operator!() const
224
225 Returns \c true if this object refers to \nullptr.
226
227 \sa isNull()
228*/
229
230/*!
231 \fn template <typename T, typename Cleanup> void QScopedPointer<T, Cleanup>::swap(QScopedPointer &other)
232
233 \deprecated [6.2] Use \c std::unique_ptr instead; this function may let a pointer
234 escape its scope.
235
236 \memberswap{scoped pointer}
237*/
238
239/*! \fn template <typename T, typename Cleanup> void QScopedPointer<T, Cleanup>::swap(QScopedPointer<T, Cleanup> &lhs, QScopedPointer<T, Cleanup> &rhs)
240
241 \deprecated [6.2] Use \c std::unique_ptr instead; this function may let a pointer
242 escape its scope.
243
244 Swaps \a lhs with \a rhs.
245 */
246
247/*!
248 \class QScopedArrayPointer
249 \inmodule QtCore
250
251 \brief The QScopedArrayPointer class stores a pointer to a
252 dynamically allocated array of objects, and deletes it upon
253 destruction.
254
255 \since 4.6
256 \reentrant
257 \ingroup misc
258
259 A QScopedArrayPointer is a QScopedPointer that defaults to
260 deleting the object it is pointing to with the delete[] operator.
261 The template parameter \a T specifies the type of the array elements,
262 and the optional \a Cleanup parameter specifies the cleanup handler.
263 It also features operator[] for convenience, so we can write:
264
265 \code
266 void foo()
267 {
268 QScopedArrayPointer<int> i(new int[10]);
269 i[2] = 42;
270 ...
271 return; // our integer array is now deleted using delete[]
272 }
273 \endcode
274*/
275
276/*!
277 \fn template <typename T, typename Cleanup> QScopedArrayPointer<T, Cleanup>::QScopedArrayPointer()
278
279 Constructs a QScopedArrayPointer instance.
280*/
281
282/*!
283 \fn template <typename T, typename Cleanup> template <typename D, QScopedArrayPointer<T, Cleanup>::if_same_type<D> = true> QScopedArrayPointer<T, Cleanup>::QScopedArrayPointer(D * p)
284
285 Constructs a QScopedArrayPointer and stores the array of objects
286 pointed to by \a p.
287*/
288
289/*!
290 \fn template <typename T, typename Cleanup> T *QScopedArrayPointer<T, Cleanup>::operator[](qsizetype i)
291
292 Provides access to entry \a i of the scoped pointer's array of
293 objects.
294
295 If the contained pointer is \nullptr, behavior is undefined.
296
297 \note In Qt versions prior to 6.5, \a i was of type \c{int}, not
298 \c{qsizetype}, possibly causing truncation on 64-bit platforms.
299
300 \sa isNull()
301*/
302
303/*!
304 \fn template <typename T, typename Cleanup> T *QScopedArrayPointer<T, Cleanup>::operator[](qsizetype i) const
305
306 Provides access to entry \a i of the scoped pointer's array of
307 objects.
308
309 If the contained pointer is \nullptr behavior is undefined.
310
311 \note In Qt versions prior to 6.5, \a i was of type \c{int}, not
312 \c{qsizetype}, possibly causing truncation on 64-bit platforms.
313
314 \sa isNull()
315*/
316
317/*! \fn template <typename T, typename Cleanup> void QScopedArrayPointer<T, Cleanup>::swap(QScopedArrayPointer<T, Cleanup> &other)
318
319 \deprecated [6.2] Use \c std::unique_ptr instead; this function may let a pointer
320 escape its scope.
321
322 \memberswap{pointer}.
323 */