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