]> git.saurik.com Git - wxWidgets.git/blob - interface/ptr_scpd.h
use wx-style header and commets; fix indentation to be 4 spaces; move Doxygen comment...
[wxWidgets.git] / interface / ptr_scpd.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: ptr_scpd.h
3 // Purpose: interface of wxScopedPtr
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
8
9 /**
10 @class wxScopedPtr
11 @wxheader{ptr_scpd.h}
12
13 This is a simple scoped smart pointer implementation that is similar to
14 the Boost smart pointers but rewritten to
15 use macros instead.
16
17 Since wxWidgets 2.9.0 there is also a templated version of this class
18 with the same name. See wxScopedPtrT().
19
20 A smart pointer holds a pointer to an object. The memory used by the object is
21 deleted when the smart pointer goes out of scope. This class is different from
22 the @c std::auto_ptr in so far as it doesn't provide copy constructor
23 nor assignment operator. This limits what you can do with it but is much less
24 surprizing than the "destructive copy'' behaviour of the standard class.
25
26 @library{wxbase}
27 @category{FIXME}
28
29 @see wxScopedArray
30 */
31 class wxScopedPtr
32 {
33 public:
34 /**
35 Creates the smart pointer with the given pointer or none if @NULL. On
36 compilers that support it, this uses the explicit keyword.
37 */
38 explicit wxScopedPtr(type T = NULL);
39
40 /**
41 Destructor frees the pointer help by this object if it is not @NULL.
42 */
43 ~wxScopedPtr();
44
45 /**
46 This operator gets the pointer stored in the smart pointer or returns @NULL if
47 there is none.
48 */
49 const T* get();
50
51 /**
52 This operator works like the standard C++ pointer operator to return the object
53 being pointed to by the pointer. If the pointer is @NULL or invalid this will
54 crash.
55 */
56 const T operator *();
57
58 /**
59 This operator works like the standard C++ pointer operator to return the pointer
60 in the smart pointer or @NULL if it is empty.
61 */
62 const T* operator -();
63
64 /**
65 Returns the currently hold pointer and resets the smart pointer object to
66 @NULL. After a call to this function the caller is responsible for
67 deleting the pointer.
68 */
69 T* release();
70
71 /**
72 Deletes the currently held pointer and sets it to @a p or to @NULL if no
73 arguments are specified. This function does check to make sure that the
74 pointer you are assigning is not the same pointer that is already stored.
75 */
76 reset(T p = NULL);
77
78 /**
79 Swap the pointer inside the smart pointer with @e other. The pointer being
80 swapped must be of the same type (hence the same class name).
81 */
82 swap(wxScopedPtr amp; other);
83 };
84
85
86
87 /**
88 @class wxScopedArray
89 @wxheader{ptr_scpd.h}
90
91 This is a simple scoped smart pointer array implementation that is similar to
92 the Boost smart pointers but rewritten to
93 use macros instead.
94
95 @library{wxbase}
96 @category{FIXME}
97
98 @see wxScopedPtr
99 */
100 class wxScopedArray
101 {
102 public:
103 /**
104 Creates the smart pointer with the given pointer or none if @NULL. On
105 compilers that support it, this uses the explicit keyword.
106 */
107 wxScopedArray(type T = NULL);
108
109 /**
110 This operator gets the pointer stored in the smart pointer or returns @NULL if
111 there is none.
112 */
113 const T* get();
114
115 /**
116 This operator acts like the standard [] indexing operator for C++ arrays. The
117 function does not do bounds checking.
118 */
119 const T operator [](long int i);
120
121 /**
122 Deletes the currently held pointer and sets it to 'p' or to @NULL if no
123 arguments are specified. This function does check to make sure that the
124 pointer you are assigning is not the same pointer that is already stored.
125 */
126 reset(T p = NULL);
127
128 /**
129 Swap the pointer inside the smart pointer with 'ot'. The pointer being swapped
130 must be of the same type (hence the same class name).
131 */
132 swap(wxScopedPtr amp; ot);
133 };
134
135
136
137 /**
138 @class wxScopedTiedPtr
139 @wxheader{ptr_scpd.h}
140
141 This is a variation on the topic of wxScopedPtr. This
142 class is also a smart pointer but in addition it "ties'' the pointer value to
143 another variable. In other words, during the life time of this class the value
144 of that variable is set to be the same as the value of the pointer itself and
145 it is reset to its old value when the object is destroyed. This class is
146 especially useful when converting the existing code (which may already store
147 the pointers value in some variable) to the smart pointers.
148
149 @library{wxbase}
150 @category{FIXME}
151 */
152 class wxScopedTiedPtr
153 {
154 public:
155 /**
156 Constructor creates a smart pointer initialized with @a ptr and stores
157 @a ptr in the location specified by @a ppTie which must not be
158 @NULL.
159 */
160 wxScopedTiedPtr(T** ppTie, T* ptr);
161
162 /**
163 Destructor frees the pointer help by this object and restores the value stored
164 at the tied location (as specified in the @ref ctor() constructor)
165 to the old value.
166 Warning: this location may now contain an uninitialized value if it hadn't been
167 initialized previously, in particular don't count on it magically being
168 @NULL!
169 */
170 ~wxScopedTiedPtr();
171 };
172
173
174
175 /**
176 @class wxScopedPtrT
177 @wxheader{ptr_scpd.h}
178
179 A scoped pointer template class. It is the template version of
180 the old-style @ref overview_wxscopedptr "scoped pointer macros".
181
182 @library{wxbase}
183 @category{FIXME}
184
185 @see wxSharedPtr, wxWeakRef
186 */
187 class wxScopedPtr<T>
188 {
189 public:
190 /**
191 Constructor.
192 */
193 wxScopedPtrT(T* ptr = NULL);
194
195 /**
196 Destructor.
197 */
198 ~wxScopedPtrT();
199
200 /**
201 Returns pointer to object or @NULL.
202 */
203 T* get() const;
204
205 /**
206 Conversion to a boolean expression (in a variant which is not
207 convertable to anything but a boolean expression). If this class
208 contains a valid pointer it will return @e @true, if it contains
209 a @NULL pointer it will return @e @false.
210 */
211 operator unspecified_bool_type() const;
212
213 /**
214 Returns a reference to the object. If the internal pointer is @NULL
215 this method will cause an assert in debug mode.
216 */
217 T operator*() const;
218
219 /**
220 Returns pointer to object. If the pointer is @NULL this method will
221 cause an assert in debug mode.
222 */
223 T* operator-() const;
224
225 /**
226 Releases the current pointer and returns it.
227 Afterwards the caller is responsible for deleting
228 the data contained in the scoped pointer before.
229 */
230 T* release();
231
232 /**
233 Reset pointer to the value of @e ptr. The
234 previous pointer will be deleted.
235 */
236 void reset(T* ptr = NULL);
237
238 /**
239 Swaps pointers.
240 */
241 void swap(wxScopedPtr<T>& ot);
242 };
243