1/*
2*******************************************************************************
3*
4* Copyright (C) 2009-2014, 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 & more 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
43U_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 */
63template<typename T>
64class LocalPointerBase {
65public:
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 }
146protected:
147 /**
148 * Actual pointer.
149 * @internal
150 */
151 T *ptr;
152private:
153 // No comparison operators with other LocalPointerBases.
154 bool operator==(const LocalPointerBase &other);
155 bool operator!=(const LocalPointerBase &other);
156 // No ownership transfer: No copy constructor, no assignment operator.
157 LocalPointerBase(const LocalPointerBase &other);
158 void operator=(const LocalPointerBase &other);
159 // No heap allocation. Use only on the stack.
160 static void * U_EXPORT2 operator new(size_t size);
161 static void * U_EXPORT2 operator new[](size_t size);
162#if U_HAVE_PLACEMENT_NEW
163 static void * U_EXPORT2 operator new(size_t, void *ptr);
164#endif
165};
166
167/**
168 * "Smart pointer" class, deletes objects via the standard C++ delete operator.
169 * For most methods see the LocalPointerBase base class.
170 *
171 * Usage example:
172 * \code
173 * LocalPointer<UnicodeString> s(new UnicodeString((UChar32)0x50005));
174 * int32_t length=s->length(); // 2
175 * UChar lead=s->charAt(0); // 0xd900
176 * if(some condition) { return; } // no need to explicitly delete the pointer
177 * s.adoptInstead(new UnicodeString((UChar)0xfffc));
178 * length=s->length(); // 1
179 * // no need to explicitly delete the pointer
180 * \endcode
181 *
182 * @see LocalPointerBase
183 * @stable ICU 4.4
184 */
185template<typename T>
186class LocalPointer : public LocalPointerBase<T> {
187public:
188 /**
189 * Constructor takes ownership.
190 * @param p simple pointer to an object that is adopted
191 * @stable ICU 4.4
192 */
193 explicit LocalPointer(T *p=NULL) : LocalPointerBase<T>(p) {}
194#ifndef U_HIDE_DRAFT_API
195 /**
196 * Constructor takes ownership and reports an error if NULL.
197 *
198 * This constructor is intended to be used with other-class constructors
199 * that may report a failure UErrorCode,
200 * so that callers need to check only for U_FAILURE(errorCode)
201 * and not also separately for isNull().
202 *
203 * @param p simple pointer to an object that is adopted
204 * @param errorCode in/out UErrorCode, set to U_MEMORY_ALLOCATION_ERROR
205 * if p==NULL and no other failure code had been set
206 * @draft ICU 55
207 */
208 LocalPointer(T *p, UErrorCode &errorCode) : LocalPointerBase<T>(p) {
209 if(p==NULL && U_SUCCESS(errorCode)) {
210 errorCode=U_MEMORY_ALLOCATION_ERROR;
211 }
212 }
213#endif /* U_HIDE_DRAFT_API */
214 /**
215 * Destructor deletes the object it owns.
216 * @stable ICU 4.4
217 */
218 ~LocalPointer() {
219 delete LocalPointerBase<T>::ptr;
220 }
221 /**
222 * Deletes the object it owns,
223 * and adopts (takes ownership of) the one passed in.
224 * @param p simple pointer to an object that is adopted
225 * @stable ICU 4.4
226 */
227 void adoptInstead(T *p) {
228 delete LocalPointerBase<T>::ptr;
229 LocalPointerBase<T>::ptr=p;
230 }
231#ifndef U_HIDE_DRAFT_API
232 /**
233 * Deletes the object it owns,
234 * and adopts (takes ownership of) the one passed in.
235 *
236 * If U_FAILURE(errorCode), then the current object is retained and the new one deleted.
237 *
238 * If U_SUCCESS(errorCode) but the input pointer is NULL,
239 * then U_MEMORY_ALLOCATION_ERROR is set,
240 * the current object is deleted, and NULL is set.
241 *
242 * @param p simple pointer to an object that is adopted
243 * @param errorCode in/out UErrorCode, set to U_MEMORY_ALLOCATION_ERROR
244 * if p==NULL and no other failure code had been set
245 * @draft ICU 55
246 */
247 void adoptInsteadAndCheckErrorCode(T *p, UErrorCode &errorCode) {
248 if(U_SUCCESS(errorCode)) {
249 delete LocalPointerBase<T>::ptr;
250 LocalPointerBase<T>::ptr=p;
251 if(p==NULL) {
252 errorCode=U_MEMORY_ALLOCATION_ERROR;
253 }
254 } else {
255 delete p;
256 }
257 }
258#endif /* U_HIDE_DRAFT_API */
259};
260
261/**
262 * "Smart pointer" class, deletes objects via the C++ array delete[] operator.
263 * For most methods see the LocalPointerBase base class.
264 * Adds operator[] for array item access.
265 *
266 * Usage example:
267 * \code
268 * LocalArray<UnicodeString> a(new UnicodeString[2]);
269 * a[0].append((UChar)0x61);
270 * if(some condition) { return; } // no need to explicitly delete the array
271 * a.adoptInstead(new UnicodeString[4]);
272 * a[3].append((UChar)0x62).append((UChar)0x63).reverse();
273 * // no need to explicitly delete the array
274 * \endcode
275 *
276 * @see LocalPointerBase
277 * @stable ICU 4.4
278 */
279template<typename T>
280class LocalArray : public LocalPointerBase<T> {
281public:
282 /**
283 * Constructor takes ownership.
284 * @param p simple pointer to an array of T objects that is adopted
285 * @stable ICU 4.4
286 */
287 explicit LocalArray(T *p=NULL) : LocalPointerBase<T>(p) {}
288 /**
289 * Constructor takes ownership and reports an error if NULL.
290 *
291 * This constructor is intended to be used with other-class constructors
292 * that may report a failure UErrorCode,
293 * so that callers need to check only for U_FAILURE(errorCode)
294 * and not also separately for isNull().
295 *
296 * @param p simple pointer to an array of T objects that is adopted
297 * @param errorCode in/out UErrorCode, set to U_MEMORY_ALLOCATION_ERROR
298 * if p==NULL and no other failure code had been set
299 * @stable ICU 56
300 */
301 LocalArray(T *p, UErrorCode &errorCode) : LocalPointerBase<T>(p) {
302 if(p==NULL && U_SUCCESS(errorCode)) {
303 errorCode=U_MEMORY_ALLOCATION_ERROR;
304 }
305 }
306 /**
307 * Destructor deletes the array it owns.
308 * @stable ICU 4.4
309 */
310 ~LocalArray() {
311 delete[] LocalPointerBase<T>::ptr;
312 }
313 /**
314 * Deletes the array it owns,
315 * and adopts (takes ownership of) the one passed in.
316 * @param p simple pointer to an array of T objects that is adopted
317 * @stable ICU 4.4
318 */
319 void adoptInstead(T *p) {
320 delete[] LocalPointerBase<T>::ptr;
321 LocalPointerBase<T>::ptr=p;
322 }
323 /**
324 * Array item access (writable).
325 * No index bounds check.
326 * @param i array index
327 * @return reference to the array item
328 * @stable ICU 4.4
329 */
330 T &operator[](ptrdiff_t i) const { return LocalPointerBase<T>::ptr[i]; }
331};
332
333/**
334 * \def U_DEFINE_LOCAL_OPEN_POINTER
335 * "Smart pointer" definition macro, deletes objects via the closeFunction.
336 * Defines a subclass of LocalPointerBase which works just
337 * like LocalPointer<Type> except that this subclass will use the closeFunction
338 * rather than the C++ delete operator.
339 *
340 * Requirement: The closeFunction must tolerate a NULL pointer.
341 * (We could add a NULL check here but it is normally redundant.)
342 *
343 * Usage example:
344 * \code
345 * LocalUCaseMapPointer csm(ucasemap_open(localeID, options, &errorCode));
346 * utf8OutLength=ucasemap_utf8ToLower(csm.getAlias(),
347 * utf8Out, (int32_t)sizeof(utf8Out),
348 * utf8In, utf8InLength, &errorCode);
349 * if(U_FAILURE(errorCode)) { return; } // no need to explicitly delete the UCaseMap
350 * \endcode
351 *
352 * @see LocalPointerBase
353 * @see LocalPointer
354 * @stable ICU 4.4
355 */
356#define U_DEFINE_LOCAL_OPEN_POINTER(LocalPointerClassName, Type, closeFunction) \
357 class LocalPointerClassName : public LocalPointerBase<Type> { \
358 public: \
359 explicit LocalPointerClassName(Type *p=NULL) : LocalPointerBase<Type>(p) {} \
360 ~LocalPointerClassName() { closeFunction(ptr); } \
361 void adoptInstead(Type *p) { \
362 closeFunction(ptr); \
363 ptr=p; \
364 } \
365 }
366
367U_NAMESPACE_END
368
369#endif /* U_SHOW_CPLUSPLUS_API */
370#endif /* __LOCALPOINTER_H__ */
371