OLD | NEW |
| (Empty) |
1 /* | |
2 ******************************************************************************* | |
3 * | |
4 * Copyright (C) 2009-2010, International Business Machines | |
5 * Corporation and others. All Rights Reserved. | |
6 * | |
7 ******************************************************************************* | |
8 * file name: localpointer.h | |
9 * encoding: US-ASCII | |
10 * tab size: 8 (not used) | |
11 * indentation:4 | |
12 * | |
13 * created on: 2009nov13 | |
14 * created by: Markus W. Scherer | |
15 */ | |
16 | |
17 #ifndef __LOCALPOINTER_H__ | |
18 #define __LOCALPOINTER_H__ | |
19 | |
20 /** | |
21 * \file | |
22 * \brief C++ API: "Smart pointers" for use with and in ICU4C C++ code. | |
23 * | |
24 * These classes are inspired by | |
25 * - std::auto_ptr | |
26 * - boost::scoped_ptr & boost::scoped_array | |
27 * - Taligent Safe Pointers (TOnlyPointerTo) | |
28 * | |
29 * but none of those provide for all of the goals for ICU smart pointers: | |
30 * - Smart pointer owns the object and releases it when it goes out of scope. | |
31 * - No transfer of ownership via copy/assignment to reduce misuse. Simpler & mo
re robust. | |
32 * - ICU-compatible: No exceptions. | |
33 * - Need to be able to orphan/release the pointer and its ownership. | |
34 * - Need variants for normal C++ object pointers, C++ arrays, and ICU C service
objects. | |
35 * | |
36 * For details see http://site.icu-project.org/design/cpp/scoped_ptr | |
37 */ | |
38 | |
39 #include "unicode/utypes.h" | |
40 | |
41 #if U_SHOW_CPLUSPLUS_API | |
42 | |
43 U_NAMESPACE_BEGIN | |
44 | |
45 /** | |
46 * "Smart pointer" base class; do not use directly: use LocalPointer etc. | |
47 * | |
48 * Base class for smart pointer classes that do not throw exceptions. | |
49 * | |
50 * Do not use this base class directly, since it does not delete its pointer. | |
51 * A subclass must implement methods that delete the pointer: | |
52 * Destructor and adoptInstead(). | |
53 * | |
54 * There is no operator T *() provided because the programmer must decide | |
55 * whether to use getAlias() (without transfer of ownership) or orpan() | |
56 * (with transfer of ownership and NULLing of the pointer). | |
57 * | |
58 * @see LocalPointer | |
59 * @see LocalArray | |
60 * @see U_DEFINE_LOCAL_OPEN_POINTER | |
61 * @stable ICU 4.4 | |
62 */ | |
63 template<typename T> | |
64 class LocalPointerBase { | |
65 public: | |
66 /** | |
67 * Constructor takes ownership. | |
68 * @param p simple pointer to an object that is adopted | |
69 * @stable ICU 4.4 | |
70 */ | |
71 explicit LocalPointerBase(T *p=NULL) : ptr(p) {} | |
72 /** | |
73 * Destructor deletes the object it owns. | |
74 * Subclass must override: Base class does nothing. | |
75 * @stable ICU 4.4 | |
76 */ | |
77 ~LocalPointerBase() { /* delete ptr; */ } | |
78 /** | |
79 * NULL check. | |
80 * @return TRUE if ==NULL | |
81 * @stable ICU 4.4 | |
82 */ | |
83 UBool isNull() const { return ptr==NULL; } | |
84 /** | |
85 * NULL check. | |
86 * @return TRUE if !=NULL | |
87 * @stable ICU 4.4 | |
88 */ | |
89 UBool isValid() const { return ptr!=NULL; } | |
90 /** | |
91 * Comparison with a simple pointer, so that existing code | |
92 * with ==NULL need not be changed. | |
93 * @param other simple pointer for comparison | |
94 * @return true if this pointer value equals other | |
95 * @stable ICU 4.4 | |
96 */ | |
97 bool operator==(const T *other) const { return ptr==other; } | |
98 /** | |
99 * Comparison with a simple pointer, so that existing code | |
100 * with !=NULL need not be changed. | |
101 * @param other simple pointer for comparison | |
102 * @return true if this pointer value differs from other | |
103 * @stable ICU 4.4 | |
104 */ | |
105 bool operator!=(const T *other) const { return ptr!=other; } | |
106 /** | |
107 * Access without ownership change. | |
108 * @return the pointer value | |
109 * @stable ICU 4.4 | |
110 */ | |
111 T *getAlias() const { return ptr; } | |
112 /** | |
113 * Access without ownership change. | |
114 * @return the pointer value as a reference | |
115 * @stable ICU 4.4 | |
116 */ | |
117 T &operator*() const { return *ptr; } | |
118 /** | |
119 * Access without ownership change. | |
120 * @return the pointer value | |
121 * @stable ICU 4.4 | |
122 */ | |
123 T *operator->() const { return ptr; } | |
124 /** | |
125 * Gives up ownership; the internal pointer becomes NULL. | |
126 * @return the pointer value; | |
127 * caller becomes responsible for deleting the object | |
128 * @stable ICU 4.4 | |
129 */ | |
130 T *orphan() { | |
131 T *p=ptr; | |
132 ptr=NULL; | |
133 return p; | |
134 } | |
135 /** | |
136 * Deletes the object it owns, | |
137 * and adopts (takes ownership of) the one passed in. | |
138 * Subclass must override: Base class does not delete the object. | |
139 * @param p simple pointer to an object that is adopted | |
140 * @stable ICU 4.4 | |
141 */ | |
142 void adoptInstead(T *p) { | |
143 // delete ptr; | |
144 ptr=p; | |
145 } | |
146 protected: | |
147 T *ptr; | |
148 private: | |
149 // No comparison operators with other LocalPointerBases. | |
150 bool operator==(const LocalPointerBase &other); | |
151 bool operator!=(const LocalPointerBase &other); | |
152 // No ownership transfer: No copy constructor, no assignment operator. | |
153 LocalPointerBase(const LocalPointerBase &other); | |
154 void operator=(const LocalPointerBase &other); | |
155 // No heap allocation. Use only on the stack. | |
156 static void * U_EXPORT2 operator new(size_t size); | |
157 static void * U_EXPORT2 operator new[](size_t size); | |
158 #if U_HAVE_PLACEMENT_NEW | |
159 static void * U_EXPORT2 operator new(size_t, void *ptr); | |
160 #endif | |
161 }; | |
162 | |
163 /** | |
164 * "Smart pointer" class, deletes objects via the standard C++ delete operator. | |
165 * For most methods see the LocalPointerBase base class. | |
166 * | |
167 * Usage example: | |
168 * \code | |
169 * LocalPointer<UnicodeString> s(new UnicodeString((UChar32)0x50005)); | |
170 * int32_t length=s->length(); // 2 | |
171 * UChar lead=s->charAt(0); // 0xd900 | |
172 * if(some condition) { return; } // no need to explicitly delete the pointer | |
173 * s.adoptInstead(new UnicodeString((UChar)0xfffc)); | |
174 * length=s->length(); // 1 | |
175 * // no need to explicitly delete the pointer | |
176 * \endcode | |
177 * | |
178 * @see LocalPointerBase | |
179 * @stable ICU 4.4 | |
180 */ | |
181 template<typename T> | |
182 class LocalPointer : public LocalPointerBase<T> { | |
183 public: | |
184 /** | |
185 * Constructor takes ownership. | |
186 * @param p simple pointer to an object that is adopted | |
187 * @stable ICU 4.4 | |
188 */ | |
189 explicit LocalPointer(T *p=NULL) : LocalPointerBase<T>(p) {} | |
190 /** | |
191 * Destructor deletes the object it owns. | |
192 * @stable ICU 4.4 | |
193 */ | |
194 ~LocalPointer() { | |
195 delete LocalPointerBase<T>::ptr; | |
196 } | |
197 /** | |
198 * Deletes the object it owns, | |
199 * and adopts (takes ownership of) the one passed in. | |
200 * @param p simple pointer to an object that is adopted | |
201 * @stable ICU 4.4 | |
202 */ | |
203 void adoptInstead(T *p) { | |
204 delete LocalPointerBase<T>::ptr; | |
205 LocalPointerBase<T>::ptr=p; | |
206 } | |
207 }; | |
208 | |
209 /** | |
210 * "Smart pointer" class, deletes objects via the C++ array delete[] operator. | |
211 * For most methods see the LocalPointerBase base class. | |
212 * Adds operator[] for array item access. | |
213 * | |
214 * Usage example: | |
215 * \code | |
216 * LocalArray<UnicodeString> a(new UnicodeString[2]); | |
217 * a[0].append((UChar)0x61); | |
218 * if(some condition) { return; } // no need to explicitly delete the array | |
219 * a.adoptInstead(new UnicodeString[4]); | |
220 * a[3].append((UChar)0x62).append((UChar)0x63).reverse(); | |
221 * // no need to explicitly delete the array | |
222 * \endcode | |
223 * | |
224 * @see LocalPointerBase | |
225 * @stable ICU 4.4 | |
226 */ | |
227 template<typename T> | |
228 class LocalArray : public LocalPointerBase<T> { | |
229 public: | |
230 /** | |
231 * Constructor takes ownership. | |
232 * @param p simple pointer to an array of T objects that is adopted | |
233 * @stable ICU 4.4 | |
234 */ | |
235 explicit LocalArray(T *p=NULL) : LocalPointerBase<T>(p) {} | |
236 /** | |
237 * Destructor deletes the array it owns. | |
238 * @stable ICU 4.4 | |
239 */ | |
240 ~LocalArray() { | |
241 delete[] LocalPointerBase<T>::ptr; | |
242 } | |
243 /** | |
244 * Deletes the array it owns, | |
245 * and adopts (takes ownership of) the one passed in. | |
246 * @param p simple pointer to an array of T objects that is adopted | |
247 * @stable ICU 4.4 | |
248 */ | |
249 void adoptInstead(T *p) { | |
250 delete[] LocalPointerBase<T>::ptr; | |
251 LocalPointerBase<T>::ptr=p; | |
252 } | |
253 /** | |
254 * Array item access (writable). | |
255 * No index bounds check. | |
256 * @param i array index | |
257 * @return reference to the array item | |
258 * @stable ICU 4.4 | |
259 */ | |
260 T &operator[](ptrdiff_t i) const { return LocalPointerBase<T>::ptr[i]; } | |
261 }; | |
262 | |
263 /** | |
264 * \def U_DEFINE_LOCAL_OPEN_POINTER | |
265 * "Smart pointer" definition macro, deletes objects via the closeFunction. | |
266 * Defines a subclass of LocalPointerBase which works just | |
267 * like LocalPointer<Type> except that this subclass will use the closeFunction | |
268 * rather than the C++ delete operator. | |
269 * | |
270 * Requirement: The closeFunction must tolerate a NULL pointer. | |
271 * (We could add a NULL check here but it is normally redundant.) | |
272 * | |
273 * Usage example: | |
274 * \code | |
275 * LocalUCaseMapPointer csm(ucasemap_open(localeID, options, &errorCode)); | |
276 * utf8OutLength=ucasemap_utf8ToLower(csm.getAlias(), | |
277 * utf8Out, (int32_t)sizeof(utf8Out), | |
278 * utf8In, utf8InLength, &errorCode); | |
279 * if(U_FAILURE(errorCode)) { return; } // no need to explicitly delete the UCa
seMap | |
280 * \endcode | |
281 * | |
282 * @see LocalPointerBase | |
283 * @see LocalPointer | |
284 * @stable ICU 4.4 | |
285 */ | |
286 #define U_DEFINE_LOCAL_OPEN_POINTER(LocalPointerClassName, Type, closeFunction)
\ | |
287 class LocalPointerClassName : public LocalPointerBase<Type> { \ | |
288 public: \ | |
289 explicit LocalPointerClassName(Type *p=NULL) : LocalPointerBase<Type>(p)
{} \ | |
290 ~LocalPointerClassName() { closeFunction(ptr); } \ | |
291 void adoptInstead(Type *p) { \ | |
292 closeFunction(ptr); \ | |
293 ptr=p; \ | |
294 } \ | |
295 } | |
296 | |
297 U_NAMESPACE_END | |
298 | |
299 #endif /* U_SHOW_CPLUSPLUS_API */ | |
300 #endif /* __LOCALPOINTER_H__ */ | |
OLD | NEW |