1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: Nokia Corporation (qt-info@nokia.com)
7 ** This file is part of the QtCore module of the Qt Toolkit.
9 ** $QT_BEGIN_LICENSE:LGPL$
10 ** GNU Lesser General Public License Usage
11 ** This file may be used under the terms of the GNU Lesser General Public
12 ** License version 2.1 as published by the Free Software Foundation and
13 ** appearing in the file LICENSE.LGPL included in the packaging of this
14 ** file. Please review the following information to ensure the GNU Lesser
15 ** General Public License version 2.1 requirements will be met:
16 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
18 ** In addition, as a special exception, Nokia gives you certain additional
19 ** rights. These rights are described in the Nokia Qt LGPL Exception
20 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
22 ** GNU General Public License Usage
23 ** Alternatively, this file may be used under the terms of the GNU General
24 ** Public License version 3.0 as published by the Free Software Foundation
25 ** and appearing in the file LICENSE.GPL included in the packaging of this
26 ** file. Please review the following information to ensure the GNU General
27 ** Public License version 3.0 requirements will be met:
28 ** http://www.gnu.org/copyleft/gpl.html.
31 ** Alternatively, this file may be used in accordance with the terms and
32 ** conditions contained in a signed written agreement between you and Nokia.
40 ****************************************************************************/
42 #include "qscopedpointer.h"
48 \brief The QScopedPointer class stores a pointer to a dynamically allocated object, and deletes it upon destruction.
53 Managing heap allocated objects manually is hard and error prone, with the
54 common result that code leaks memory and is hard to maintain.
55 QScopedPointer is a small utility class that heavily simplifies this by
56 assigning stack-based memory ownership to heap allocations, more generally
57 called resource acquisition is initialization(RAII).
59 QScopedPointer guarantees that the object pointed to will get deleted when
60 the current scope disappears.
62 Consider this function which does heap allocations, and have various exit points:
64 \snippet doc/src/snippets/code/src_corelib_tools_qscopedpointer.cpp 0
66 It's encumbered by the manual delete calls. With QScopedPointer, the code
69 \snippet doc/src/snippets/code/src_corelib_tools_qscopedpointer.cpp 1
71 The code the compiler generates for QScopedPointer is the same as when
72 writing it manually. Code that makes use of \a delete are candidates for
73 QScopedPointer usage (and if not, possibly another type of smart pointer
74 such as QSharedPointer). QScopedPointer intentionally has no copy
75 constructor or assignment operator, such that ownership and lifetime is
78 The const qualification on a regular C++ pointer can also be expressed with
81 \snippet doc/src/snippets/code/src_corelib_tools_qscopedpointer.cpp 2
83 \section1 Custom cleanup handlers
85 Arrays as well as pointers that have been allocated with \c malloc must
86 not be deleted using \c delete. QScopedPointer's second template parameter
87 can be used for custom cleanup handlers.
89 The following custom cleanup handlers exist:
92 \i QScopedPointerDeleter - the default, deletes the pointer using \c delete
93 \i QScopedPointerArrayDeleter - deletes the pointer using \c{delete []}. Use
94 this handler for pointers that were allocated with \c{new []}.
95 \i QScopedPointerPodDeleter - deletes the pointer using \c{free()}. Use this
96 handler for pointers that were allocated with \c{malloc()}.
99 You can pass your own classes as handlers, provided that they have a public
100 static function \c{void cleanup(T *pointer)}.
102 \snippet doc/src/snippets/code/src_corelib_tools_qscopedpointer.cpp 5
104 \section1 Forward Declared Pointers
106 Classes that are forward declared can be used within QScopedPointer, as
107 long as the destructor of the forward declared class is available whenever
108 a QScopedPointer needs to clean up.
110 Concretely, this means that all classes containing a QScopedPointer that
111 points to a forward declared class must have non-inline constructors,
112 destructors and assignment operators:
114 \snippet doc/src/snippets/code/src_corelib_tools_qscopedpointer.cpp 4
116 Otherwise, the compiler output a warning about not being able to destruct
122 /*! \typedef QScopedPointer::pointer
127 \fn QScopedPointer::QScopedPointer(T *p = 0)
129 Constructs this QScopedPointer instance and sets its pointer to \a p.
133 \fn QScopedPointer::~QScopedPointer()
135 Destroys this QScopedPointer object. Delete the object its pointer points
140 \fn T *QScopedPointer::data() const
142 Returns the value of the pointer referenced by this object. QScopedPointer
143 still owns the object pointed to.
147 \fn T &QScopedPointer::operator*() const
149 Provides access to the scoped pointer's object.
151 If the contained pointer is \c null, behavior is undefined.
156 \fn T *QScopedPointer::operator->() const
158 Provides access to the scoped pointer's object.
160 If the contained pointer is \c null, behavior is undefined.
166 \fn QScopedPointer::operator bool() const
168 Returns \c true if this object is not \c null. This function is suitable
169 for use in \tt if-constructs, like:
171 \snippet doc/src/snippets/code/src_corelib_tools_qscopedpointer.cpp 3
177 \fn bool operator==(const QScopedPointer<T, Cleanup> &lhs, const QScopedPointer<T, Cleanup> &rhs)
179 Equality operator. Returns true if the scoped pointers
180 \a lhs and \a rhs are pointing to the same object.
181 Otherwise returns false.
186 \fn bool operator!=(const QScopedPointer<T, Cleanup> &lhs, const QScopedPointer<T, Cleanup> &rhs)
188 Inequality operator. Returns true if the scoped pointers
189 \a lhs and \a rhs are \e not pointing to the same object.
190 Otherwise returns false.
194 \fn bool QScopedPointer::isNull() const
196 Returns \c true if this object is holding a pointer that is \c null.
200 \fn void QScopedPointer::reset(T *other = 0)
202 Deletes the existing object it is pointing to if any, and sets its pointer to
203 \a other. QScopedPointer now owns \a other and will delete it in its
208 \fn T *QScopedPointer::take()
210 Returns the value of the pointer referenced by this object. The pointer of this
211 QScopedPointer object will be reset to \c null.
213 Callers of this function take ownership of the pointer.
216 /*! \fn bool QScopedPointer::operator!() const
218 Returns \c true if the pointer referenced by this object is \c null, otherwise
224 /*! \fn void QScopedPointer::swap(QScopedPointer<T, Cleanup> &other)
225 Swap this pointer with \a other.
229 \class QScopedArrayPointer
231 \brief The QScopedArrayPointer class stores a pointer to a
232 dynamically allocated array of objects, and deletes it upon
239 A QScopedArrayPointer is a QScopedPointer that defaults to
240 deleting the object it is pointing to with the delete[] operator. It
241 also features operator[] for convenience, so we can write:
246 QScopedArrayPointer<int> i(new int[10]);
249 return; // our integer array is now deleted using delete[]
255 \fn QScopedArrayPointer::QScopedArrayPointer()
257 Constructs a QScopedArrayPointer instance.
261 \fn T *QScopedArrayPointer::operator[](int i)
263 Provides access to entry \a i of the scoped pointer's array of
266 If the contained pointer is \c null, behavior is undefined.
272 \fn T *QScopedArrayPointer::operator[](int i) const
274 Provides access to entry \a i of the scoped pointer's array of
277 If the contained pointer is \c null, behavior is undefined.