1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
|
/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** Contact: Qt Software Information (qt-info@nokia.com)
**
** This file is part of the $MODULE$ of the Qt Toolkit.
**
** $TROLLTECH_DUAL_LICENSE$
**
****************************************************************************/
/*!
\class QScopedPointer
\brief The QScopedPointer class stores a pointer to a dynamically allocated object, and deletes it upon destruction.
\since 4.6
\reentrant
\ingroup misc
Managing heap allocated objects manually is hard and error prone, with the
common result that code leaks memory and is hard to maintain.
QScopedPointer is a small utility class that heavily simplifies this by
assigning stack-based memory ownership to heap allocations, more generally
called resource acquisition is initialization(RAII).
QScopedPointer guarantees that the object pointed to will get deleted when
the current scope dissapears, and it also has no way of releasing
ownership, hence clearly communicating the lifetime and ownership of the
object. These guarantees are convenient when reading the code.
Consider this function which does heap allocations, and have various exit points:
\snippet doc/src/snippets/code/src_corelib_tools_qscopedpointer.cpp 0
It's encumbered by the manual delete calls. With QScopedPointer, the code
can be simplified to:
\snippet doc/src/snippets/code/src_corelib_tools_qscopedpointer.cpp 1
The code the compiler generates for QScopedPointer is the same as when
writing it manually. Code that makes use of \a delete are candidates for
QScopedPointer usage(and if not, possibly another type of smart pointer
such as QSharedPointer). QScopedPointer intentionally has no copy
constructor or assignment operator, such that ownership and lifetime is
clearly communicated.
The const qualification on a regular C++ pointer can also be expressed with
a QScopedPointer:
\snippet doc/src/snippets/code/src_corelib_tools_qscopedpointer.cpp 2
\note QScopedPointer does not work with arrays.
\sa QSharedPointer
*/
/*!
\fn QScopedPointer::QScopedPointer(T *p = 0)
Constructs this QScopedPointer instance and sets its pointer to \a p.
*/
/*!
\fn QScopedPointer::~QScopedPointer()
Destroys this QScopedPointer object. Delete the object its pointer points
to.
*/
/*!
\fn T *QScopedPointer::data() const
Returns the value of the pointer referenced by this object. QScopedPointer
still owns the object pointed to.
*/
/*!
\fn T &QScopedPointer::operator*() const
Provides access to the scoped pointer's object.
If the contained pointer is \c null, behavior is undefined.
\sa isNull()
*/
/*!
\fn T *QScopedPointer::operator->() const
Provides access to the scoped pointer's object.
If the contained pointer is \c null, behavior is undefined.
\sa isNull()
*/
/*!
\fn QScopedPointer::operator bool() const
Returns \c true if this object is not \c null. This function is suitable
for use in \tt if-constructs, like:
\snippet doc/src/snippets/code/src_corelib_tools_qscopedpointer.cpp 3
\sa isNull()
*/
/*!
\fn bool QScopedPointer::isNull() const
Returns \c true if this object is holding a pointer that is \c null.
*/
/*!
\fn void QScopedPointer::reset(T *other = 0)
Deletes the existing object its pointing to if any, and sets its pointer to
\a other. QScopedPointer now owns \a other and will delete it in its
destructor.
If \a other is equal to the value returned by data(), behavior is
undefined.
*/
/*!
\fn T *QScopedPointer::take()
Returns the value of the pointer referenced by this object. The pointer of this
QScopedPointer object will be reset to \c null.
*/
QT_END_NAMESPACE
#endif
|
