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