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
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
|
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en_US" lang="en_US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- qscopedpointer.cpp -->
<title>Qt 4.8: QScopedPointer Class Reference</title>
<link rel="stylesheet" type="text/css" href="style/offline.css" />
</head>
<body>
<div class="header" id="qtdocheader">
<div class="content">
<a href="index.html" class="qtref"><span>Qt Reference Documentation</span></a>
</div>
<div class="breadcrumb toolblock">
<ul>
<li class="first"><a href="index.html">Home</a></li>
<!-- Breadcrumbs go here -->
<li><a href="modules.html">Modules</a></li>
<li><a href="qtcore.html">QtCore</a></li>
<li>QScopedPointer</li>
</ul>
</div>
</div>
<div class="content mainContent">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#public-functions">Public Functions</a></li>
<li class="level1"><a href="#details">Detailed Description</a></li>
<li class="level2"><a href="#custom-cleanup-handlers">Custom cleanup handlers</a></li>
<li class="level2"><a href="#forward-declared-pointers">Forward Declared Pointers</a></li>
</ul>
</div>
<h1 class="title">QScopedPointer Class Reference</h1>
<!-- $$$QScopedPointer-brief -->
<p>The QScopedPointer class stores a pointer to a dynamically allocated object, and deletes it upon destruction. <a href="#details">More...</a></p>
<!-- @@@QScopedPointer -->
<pre class="cpp"> <span class="preprocessor">#include <QScopedPointer></span></pre><p><b>Inherited by: </b><a href="qscopedarraypointer.html">QScopedArrayPointer</a>.</p>
<p><b>Note:</b> All functions in this class are <a href="threads-reentrancy.html#reentrant">reentrant</a>.</p>
<p>This class was introduced in Qt 4.6.</p>
<ul>
<li><a href="qscopedpointer-members.html">List of all members, including inherited members</a></li>
</ul>
<a name="public-functions"></a>
<h2>Public Functions</h2>
<table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> </td><td class="memItemRight bottomAlign"><b><a href="qscopedpointer.html#QScopedPointer">QScopedPointer</a></b> ( T * <i>p</i> = 0 )</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> </td><td class="memItemRight bottomAlign"><b><a href="qscopedpointer.html#dtor.QScopedPointer">~QScopedPointer</a></b> ()</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> T * </td><td class="memItemRight bottomAlign"><b><a href="qscopedpointer.html#data">data</a></b> () const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> bool </td><td class="memItemRight bottomAlign"><b><a href="qscopedpointer.html#isNull">isNull</a></b> () const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qscopedpointer.html#reset">reset</a></b> ( T * <i>other</i> = 0 )</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qscopedpointer.html#swap">swap</a></b> ( QScopedPointer<T, Cleanup> & <i>other</i> )</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> T * </td><td class="memItemRight bottomAlign"><b><a href="qscopedpointer.html#take">take</a></b> ()</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> </td><td class="memItemRight bottomAlign"><b><a href="qscopedpointer.html#operator-bool">operator bool</a></b> () const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> bool </td><td class="memItemRight bottomAlign"><b><a href="qscopedpointer.html#operator-not">operator!</a></b> () const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> T & </td><td class="memItemRight bottomAlign"><b><a href="qscopedpointer.html#operator-2a">operator*</a></b> () const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> T * </td><td class="memItemRight bottomAlign"><b><a href="qscopedpointer.html#operator--gt">operator-></a></b> () const</td></tr>
</table>
<a name="details"></a>
<!-- $$$QScopedPointer-description -->
<div class="descr">
<h2>Detailed Description</h2>
<p>The QScopedPointer class stores a pointer to a dynamically allocated object, and deletes it upon destruction.</p>
<p>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).</p>
<p>QScopedPointer guarantees that the object pointed to will get deleted when the current scope disappears.</p>
<p>Consider this function which does heap allocations, and have various exit points:</p>
<pre class="cpp"> <span class="type">void</span> myFunction(<span class="type">bool</span> useSubClass)
{
MyClass <span class="operator">*</span>p <span class="operator">=</span> useSubClass <span class="operator">?</span> <span class="keyword">new</span> MyClass() : <span class="keyword">new</span> MySubClass;
<span class="type"><a href="qiodevice.html">QIODevice</a></span> <span class="operator">*</span>device <span class="operator">=</span> handsOverOwnership();
<span class="keyword">if</span> (m_value <span class="operator">></span> <span class="number">3</span>) {
<span class="keyword">delete</span> p;
<span class="keyword">delete</span> device;
<span class="keyword">return</span>;
}
<span class="keyword">try</span> {
process(device);
}
<span class="keyword">catch</span> (<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>) {
<span class="keyword">delete</span> p;
<span class="keyword">delete</span> device;
<span class="keyword">throw</span>;
}
<span class="keyword">delete</span> p;
<span class="keyword">delete</span> device;
}</pre>
<p>It's encumbered by the manual delete calls. With QScopedPointer, the code can be simplified to:</p>
<pre class="cpp"> <span class="type">void</span> myFunction(<span class="type">bool</span> useSubClass)
{
<span class="comment">// assuming that MyClass has a virtual destructor</span>
<span class="type">QScopedPointer</span><span class="operator"><</span>MyClass<span class="operator">></span> p(useSubClass <span class="operator">?</span> <span class="keyword">new</span> MyClass() : <span class="keyword">new</span> MySubClass);
<span class="type">QScopedPointer</span><span class="operator"><</span><span class="type"><a href="qiodevice.html">QIODevice</a></span><span class="operator">></span> device(handsOverOwnership());
<span class="keyword">if</span> (m_value <span class="operator">></span> <span class="number">3</span>)
<span class="keyword">return</span>;
process(device);
}</pre>
<p>The code the compiler generates for QScopedPointer is the same as when writing it manually. Code that makes use of <i>delete</i> are candidates for QScopedPointer usage (and if not, possibly another type of smart pointer such as <a href="qsharedpointer.html">QSharedPointer</a>). QScopedPointer intentionally has no copy constructor or assignment operator, such that ownership and lifetime is clearly communicated.</p>
<p>The const qualification on a regular C++ pointer can also be expressed with a QScopedPointer:</p>
<pre class="cpp"> <span class="keyword">const</span> <span class="type"><a href="qwidget.html">QWidget</a></span> <span class="operator">*</span><span class="keyword">const</span> p <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qwidget.html">QWidget</a></span>();
<span class="comment">// is equivalent to:</span>
<span class="keyword">const</span> <span class="type">QScopedPointer</span><span class="operator"><</span><span class="keyword">const</span> <span class="type"><a href="qwidget.html">QWidget</a></span><span class="operator">></span> p(<span class="keyword">new</span> <span class="type"><a href="qwidget.html">QWidget</a></span>());
<span class="type"><a href="qwidget.html">QWidget</a></span> <span class="operator">*</span><span class="keyword">const</span> p <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qwidget.html">QWidget</a></span>();
<span class="comment">// is equivalent to:</span>
<span class="keyword">const</span> <span class="type">QScopedPointer</span><span class="operator"><</span><span class="type"><a href="qwidget.html">QWidget</a></span><span class="operator">></span> p(<span class="keyword">new</span> <span class="type"><a href="qwidget.html">QWidget</a></span>());
<span class="keyword">const</span> <span class="type"><a href="qwidget.html">QWidget</a></span> <span class="operator">*</span>p <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qwidget.html">QWidget</a></span>();
<span class="comment">// is equivalent to:</span>
<span class="type">QScopedPointer</span><span class="operator"><</span><span class="keyword">const</span> <span class="type"><a href="qwidget.html">QWidget</a></span><span class="operator">></span> p(<span class="keyword">new</span> <span class="type"><a href="qwidget.html">QWidget</a></span>());</pre>
<a name="custom-cleanup-handlers"></a>
<h3>Custom cleanup handlers</h3>
<p>Arrays as well as pointers that have been allocated with <tt>malloc</tt> must not be deleted using <tt>delete</tt>. QScopedPointer's second template parameter can be used for custom cleanup handlers.</p>
<p>The following custom cleanup handlers exist:</p>
<ul>
<li>QScopedPointerDeleter - the default, deletes the pointer using <tt>delete</tt></li>
<li>QScopedPointerArrayDeleter - deletes the pointer using <tt>delete []</tt>. Use this handler for pointers that were allocated with <tt>new []</tt>.</li>
<li>QScopedPointerPodDeleter - deletes the pointer using <tt>free()</tt>. Use this handler for pointers that were allocated with <tt>malloc()</tt>.</li>
</ul>
<p>You can pass your own classes as handlers, provided that they have a public static function <tt>void cleanup(T *pointer)</tt>.</p>
<pre class="cpp"> <span class="comment">// this QScopedPointer deletes its data using the delete[] operator:</span>
<span class="type">QScopedPointer</span><span class="operator"><</span><span class="type">int</span><span class="operator">,</span> <span class="type">QScopedPointerArrayDeleter</span><span class="operator"><</span><span class="type">int</span><span class="operator">></span> <span class="operator">></span> arrayPointer(<span class="keyword">new</span> <span class="type">int</span><span class="operator">[</span><span class="number">42</span><span class="operator">]</span>);
<span class="comment">// this QScopedPointer frees its data using free():</span>
<span class="type">QScopedPointer</span><span class="operator"><</span><span class="type">int</span><span class="operator">,</span> <span class="type">QScopedPointerPodDeleter</span><span class="operator">></span> podPointer(<span class="keyword">reinterpret_cast</span><span class="operator"><</span><span class="type">int</span> <span class="operator">*</span><span class="operator">></span>(malloc(<span class="number">42</span>)));
<span class="comment">// this struct calls "myCustomDeallocator" to delete the pointer</span>
<span class="keyword">struct</span> ScopedPointerCustomDeleter
{
<span class="keyword">static</span> <span class="keyword">inline</span> <span class="type">void</span> cleanup(MyCustomClass <span class="operator">*</span>pointer)
{
myCustomDeallocator(pointer);
}
};
<span class="comment">// QScopedPointer using a custom deleter:</span>
<span class="type">QScopedPointer</span><span class="operator"><</span>MyCustomClass<span class="operator">,</span> ScopedPointerCustomDeleter<span class="operator">></span> customPointer(<span class="keyword">new</span> MyCustomClass);</pre>
<a name="forward-declared-pointers"></a>
<h3>Forward Declared Pointers</h3>
<p>Classes that are forward declared can be used within QScopedPointer, as long as the destructor of the forward declared class is available whenever a QScopedPointer needs to clean up.</p>
<p>Concretely, this means that all classes containing a QScopedPointer that points to a forward declared class must have non-inline constructors, destructors and assignment operators:</p>
<pre class="cpp"> <span class="keyword">class</span> MyPrivateClass; <span class="comment">// forward declare MyPrivateClass</span>
<span class="keyword">class</span> MyClass
{
<span class="keyword">private</span>:
<span class="type">QScopedPointer</span><span class="operator"><</span>MyPrivateClass<span class="operator">></span> privatePtr; <span class="comment">// QScopedPointer to forward declared class</span>
<span class="keyword">public</span>:
MyClass(); <span class="comment">// OK</span>
<span class="keyword">inline</span> <span class="operator">~</span>MyClass() {} <span class="comment">// VIOLATION - Destructor must not be inline</span>
<span class="keyword">private</span>:
Q_DISABLE_COPY(MyClass) <span class="comment">// OK - copy constructor and assignment operators</span>
<span class="comment">// are now disabled, so the compiler won't implicitely</span>
<span class="comment">// generate them.</span>
};</pre>
<p>Otherwise, the compiler output a warning about not being able to destruct <tt>MyPrivateClass</tt>.</p>
</div>
<p><b>See also </b><a href="qsharedpointer.html">QSharedPointer</a>.</p>
<!-- @@@QScopedPointer -->
<div class="func">
<h2>Member Function Documentation</h2>
<!-- $$$QScopedPointer[overload1]$$$QScopedPointerT* -->
<h3 class="fn"><a name="QScopedPointer"></a>QScopedPointer::<span class="name">QScopedPointer</span> ( <span class="type">T</span> * <i>p</i> = 0 )</h3>
<p>Constructs this <a href="qscopedpointer.html">QScopedPointer</a> instance and sets its pointer to <i>p</i>.</p>
<!-- @@@QScopedPointer -->
<!-- $$$~QScopedPointer[overload1]$$$~QScopedPointer -->
<h3 class="fn"><a name="dtor.QScopedPointer"></a>QScopedPointer::<span class="name">~QScopedPointer</span> ()</h3>
<p>Destroys this <a href="qscopedpointer.html">QScopedPointer</a> object. Delete the object its pointer points to.</p>
<!-- @@@~QScopedPointer -->
<!-- $$$data[overload1]$$$data -->
<h3 class="fn"><a name="data"></a><span class="type">T</span> * QScopedPointer::<span class="name">data</span> () const</h3>
<p>Returns the value of the pointer referenced by this object. <a href="qscopedpointer.html">QScopedPointer</a> still owns the object pointed to.</p>
<!-- @@@data -->
<!-- $$$isNull[overload1]$$$isNull -->
<h3 class="fn"><a name="isNull"></a><span class="type">bool</span> QScopedPointer::<span class="name">isNull</span> () const</h3>
<p>Returns <tt>true</tt> if this object is holding a pointer that is <tt>null</tt>.</p>
<!-- @@@isNull -->
<!-- $$$reset[overload1]$$$resetT* -->
<h3 class="fn"><a name="reset"></a><span class="type">void</span> QScopedPointer::<span class="name">reset</span> ( <span class="type">T</span> * <i>other</i> = 0 )</h3>
<p>Deletes the existing object it is pointing to if any, and sets its pointer to <i>other</i>. <a href="qscopedpointer.html">QScopedPointer</a> now owns <i>other</i> and will delete it in its destructor.</p>
<!-- @@@reset -->
<!-- $$$swap[overload1]$$$swapQScopedPointer<T,Cleanup>& -->
<h3 class="fn"><a name="swap"></a><span class="type">void</span> QScopedPointer::<span class="name">swap</span> ( <span class="type">QScopedPointer</span><<span class="type">T</span>, <span class="type">Cleanup</span>> & <i>other</i> )</h3>
<p>Swap this pointer with <i>other</i>.</p>
<!-- @@@swap -->
<!-- $$$take[overload1]$$$take -->
<h3 class="fn"><a name="take"></a><span class="type">T</span> * QScopedPointer::<span class="name">take</span> ()</h3>
<p>Returns the value of the pointer referenced by this object. The pointer of this <a href="qscopedpointer.html">QScopedPointer</a> object will be reset to <tt>null</tt>.</p>
<p>Callers of this function take ownership of the pointer.</p>
<!-- @@@take -->
<!-- $$$operator bool[overload1]$$$operator bool -->
<h3 class="fn"><a name="operator-bool"></a>QScopedPointer::<span class="name">operator bool</span> () const</h3>
<p>Returns <tt>true</tt> if this object is not <tt>null</tt>. This function is suitable for use in <tt>if-constructs</tt>, like:</p>
<pre class="cpp"> <span class="keyword">if</span> (scopedPointer) {
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
}</pre>
<p><b>See also </b><a href="qscopedpointer.html#isNull">isNull</a>().</p>
<!-- @@@operator bool -->
<!-- $$$operator![overload1]$$$operator! -->
<h3 class="fn"><a name="operator-not"></a><span class="type">bool</span> QScopedPointer::<span class="name">operator!</span> () const</h3>
<p>Returns <tt>true</tt> if the pointer referenced by this object is <tt>null</tt>, otherwise returns <tt>false</tt>.</p>
<p><b>See also </b><a href="qscopedpointer.html#isNull">isNull</a>().</p>
<!-- @@@operator! -->
<!-- $$$operator*[overload1]$$$operator* -->
<h3 class="fn"><a name="operator-2a"></a><span class="type">T</span> & QScopedPointer::<span class="name">operator*</span> () const</h3>
<p>Provides access to the scoped pointer's object.</p>
<p>If the contained pointer is <tt>null</tt>, behavior is undefined.</p>
<p><b>See also </b><a href="qscopedpointer.html#isNull">isNull</a>().</p>
<!-- @@@operator* -->
<!-- $$$operator->[overload1]$$$operator-> -->
<h3 class="fn"><a name="operator--gt"></a><span class="type">T</span> * QScopedPointer::<span class="name">operator-></span> () const</h3>
<p>Provides access to the scoped pointer's object.</p>
<p>If the contained pointer is <tt>null</tt>, behavior is undefined.</p>
<p><b>See also </b><a href="qscopedpointer.html#isNull">isNull</a>().</p>
<!-- @@@operator-> -->
</div>
<div class="ft">
<span></span>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2012 Nokia Corporation and/or its
subsidiaries. Documentation contributions included herein are the copyrights of
their respective owners.</p>
<br />
<p>
The documentation provided herein is licensed under the terms of the
<a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation
License version 1.3</a> as published by the Free Software Foundation.</p>
<p>
Documentation sources may be obtained from <a href="http://www.qt-project.org">
www.qt-project.org</a>.</p>
<br />
<p>
Nokia, Qt and their respective logos are trademarks of Nokia Corporation
in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. <a title="Privacy Policy"
href="http://en.gitorious.org/privacy_policy/">Privacy Policy</a></p>
</div>
</body>
</html>
|
