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