Line data Source code
1 : // © 2016 and later: Unicode, Inc. and others.
2 : // License & terms of use: http://www.unicode.org/copyright.html
3 : /*
4 : *******************************************************************************
5 : *
6 : * Copyright (C) 2009-2016, International Business Machines
7 : * Corporation and others. All Rights Reserved.
8 : *
9 : *******************************************************************************
10 : * file name: localpointer.h
11 : * encoding: UTF-8
12 : * tab size: 8 (not used)
13 : * indentation:4
14 : *
15 : * created on: 2009nov13
16 : * created by: Markus W. Scherer
17 : */
18 :
19 : #ifndef __LOCALPOINTER_H__
20 : #define __LOCALPOINTER_H__
21 :
22 : /**
23 : * \file
24 : * \brief C++ API: "Smart pointers" for use with and in ICU4C C++ code.
25 : *
26 : * These classes are inspired by
27 : * - std::auto_ptr
28 : * - boost::scoped_ptr & boost::scoped_array
29 : * - Taligent Safe Pointers (TOnlyPointerTo)
30 : *
31 : * but none of those provide for all of the goals for ICU smart pointers:
32 : * - Smart pointer owns the object and releases it when it goes out of scope.
33 : * - No transfer of ownership via copy/assignment to reduce misuse. Simpler & more robust.
34 : * - ICU-compatible: No exceptions.
35 : * - Need to be able to orphan/release the pointer and its ownership.
36 : * - Need variants for normal C++ object pointers, C++ arrays, and ICU C service objects.
37 : *
38 : * For details see http://site.icu-project.org/design/cpp/scoped_ptr
39 : */
40 :
41 : #include "unicode/utypes.h"
42 :
43 : #if U_SHOW_CPLUSPLUS_API
44 :
45 : U_NAMESPACE_BEGIN
46 :
47 : /**
48 : * "Smart pointer" base class; do not use directly: use LocalPointer etc.
49 : *
50 : * Base class for smart pointer classes that do not throw exceptions.
51 : *
52 : * Do not use this base class directly, since it does not delete its pointer.
53 : * A subclass must implement methods that delete the pointer:
54 : * Destructor and adoptInstead().
55 : *
56 : * There is no operator T *() provided because the programmer must decide
57 : * whether to use getAlias() (without transfer of ownership) or orphan()
58 : * (with transfer of ownership and NULLing of the pointer).
59 : *
60 : * @see LocalPointer
61 : * @see LocalArray
62 : * @see U_DEFINE_LOCAL_OPEN_POINTER
63 : * @stable ICU 4.4
64 : */
65 : template<typename T>
66 : class LocalPointerBase {
67 : public:
68 : /**
69 : * Constructor takes ownership.
70 : * @param p simple pointer to an object that is adopted
71 : * @stable ICU 4.4
72 : */
73 3 : explicit LocalPointerBase(T *p=NULL) : ptr(p) {}
74 : /**
75 : * Destructor deletes the object it owns.
76 : * Subclass must override: Base class does nothing.
77 : * @stable ICU 4.4
78 : */
79 3 : ~LocalPointerBase() { /* delete ptr; */ }
80 : /**
81 : * NULL check.
82 : * @return TRUE if ==NULL
83 : * @stable ICU 4.4
84 : */
85 0 : UBool isNull() const { return ptr==NULL; }
86 : /**
87 : * NULL check.
88 : * @return TRUE if !=NULL
89 : * @stable ICU 4.4
90 : */
91 0 : UBool isValid() const { return ptr!=NULL; }
92 : /**
93 : * Comparison with a simple pointer, so that existing code
94 : * with ==NULL need not be changed.
95 : * @param other simple pointer for comparison
96 : * @return true if this pointer value equals other
97 : * @stable ICU 4.4
98 : */
99 : bool operator==(const T *other) const { return ptr==other; }
100 : /**
101 : * Comparison with a simple pointer, so that existing code
102 : * with !=NULL need not be changed.
103 : * @param other simple pointer for comparison
104 : * @return true if this pointer value differs from other
105 : * @stable ICU 4.4
106 : */
107 : bool operator!=(const T *other) const { return ptr!=other; }
108 : /**
109 : * Access without ownership change.
110 : * @return the pointer value
111 : * @stable ICU 4.4
112 : */
113 3 : T *getAlias() const { return ptr; }
114 : /**
115 : * Access without ownership change.
116 : * @return the pointer value as a reference
117 : * @stable ICU 4.4
118 : */
119 0 : T &operator*() const { return *ptr; }
120 : /**
121 : * Access without ownership change.
122 : * @return the pointer value
123 : * @stable ICU 4.4
124 : */
125 0 : T *operator->() const { return ptr; }
126 : /**
127 : * Gives up ownership; the internal pointer becomes NULL.
128 : * @return the pointer value;
129 : * caller becomes responsible for deleting the object
130 : * @stable ICU 4.4
131 : */
132 3 : T *orphan() {
133 3 : T *p=ptr;
134 3 : ptr=NULL;
135 3 : return p;
136 : }
137 : /**
138 : * Deletes the object it owns,
139 : * and adopts (takes ownership of) the one passed in.
140 : * Subclass must override: Base class does not delete the object.
141 : * @param p simple pointer to an object that is adopted
142 : * @stable ICU 4.4
143 : */
144 : void adoptInstead(T *p) {
145 : // delete ptr;
146 : ptr=p;
147 : }
148 : protected:
149 : /**
150 : * Actual pointer.
151 : * @internal
152 : */
153 : T *ptr;
154 : private:
155 : // No comparison operators with other LocalPointerBases.
156 : bool operator==(const LocalPointerBase<T> &other);
157 : bool operator!=(const LocalPointerBase<T> &other);
158 : // No ownership sharing: No copy constructor, no assignment operator.
159 : LocalPointerBase(const LocalPointerBase<T> &other);
160 : void operator=(const LocalPointerBase<T> &other);
161 : // No heap allocation. Use only on the stack.
162 : static void * U_EXPORT2 operator new(size_t size);
163 : static void * U_EXPORT2 operator new[](size_t size);
164 : #if U_HAVE_PLACEMENT_NEW
165 : static void * U_EXPORT2 operator new(size_t, void *ptr);
166 : #endif
167 : };
168 :
169 : /**
170 : * "Smart pointer" class, deletes objects via the standard C++ delete operator.
171 : * For most methods see the LocalPointerBase base class.
172 : *
173 : * Usage example:
174 : * \code
175 : * LocalPointer<UnicodeString> s(new UnicodeString((UChar32)0x50005));
176 : * int32_t length=s->length(); // 2
177 : * char16_t lead=s->charAt(0); // 0xd900
178 : * if(some condition) { return; } // no need to explicitly delete the pointer
179 : * s.adoptInstead(new UnicodeString((char16_t)0xfffc));
180 : * length=s->length(); // 1
181 : * // no need to explicitly delete the pointer
182 : * \endcode
183 : *
184 : * @see LocalPointerBase
185 : * @stable ICU 4.4
186 : */
187 : template<typename T>
188 : class LocalPointer : public LocalPointerBase<T> {
189 : public:
190 : using LocalPointerBase<T>::operator*;
191 : using LocalPointerBase<T>::operator->;
192 : /**
193 : * Constructor takes ownership.
194 : * @param p simple pointer to an object that is adopted
195 : * @stable ICU 4.4
196 : */
197 3 : explicit LocalPointer(T *p=NULL) : LocalPointerBase<T>(p) {}
198 : /**
199 : * Constructor takes ownership and reports an error if NULL.
200 : *
201 : * This constructor is intended to be used with other-class constructors
202 : * that may report a failure UErrorCode,
203 : * so that callers need to check only for U_FAILURE(errorCode)
204 : * and not also separately for isNull().
205 : *
206 : * @param p simple pointer to an object that is adopted
207 : * @param errorCode in/out UErrorCode, set to U_MEMORY_ALLOCATION_ERROR
208 : * if p==NULL and no other failure code had been set
209 : * @stable ICU 55
210 : */
211 0 : LocalPointer(T *p, UErrorCode &errorCode) : LocalPointerBase<T>(p) {
212 0 : if(p==NULL && U_SUCCESS(errorCode)) {
213 0 : errorCode=U_MEMORY_ALLOCATION_ERROR;
214 : }
215 0 : }
216 : #if U_HAVE_RVALUE_REFERENCES
217 : /**
218 : * Move constructor, leaves src with isNull().
219 : * @param src source smart pointer
220 : * @stable ICU 56
221 : */
222 : LocalPointer(LocalPointer<T> &&src) U_NOEXCEPT : LocalPointerBase<T>(src.ptr) {
223 : src.ptr=NULL;
224 : }
225 : #endif
226 : /**
227 : * Destructor deletes the object it owns.
228 : * @stable ICU 4.4
229 : */
230 3 : ~LocalPointer() {
231 3 : delete LocalPointerBase<T>::ptr;
232 3 : }
233 : #if U_HAVE_RVALUE_REFERENCES
234 : /**
235 : * Move assignment operator, leaves src with isNull().
236 : * The behavior is undefined if *this and src are the same object.
237 : * @param src source smart pointer
238 : * @return *this
239 : * @stable ICU 56
240 : */
241 : LocalPointer<T> &operator=(LocalPointer<T> &&src) U_NOEXCEPT {
242 : return moveFrom(src);
243 : }
244 : #endif
245 : // do not use #ifndef U_HIDE_DRAFT_API for moveFrom, needed by non-draft API
246 : /**
247 : * Move assignment, leaves src with isNull().
248 : * The behavior is undefined if *this and src are the same object.
249 : *
250 : * Can be called explicitly, does not need C++11 support.
251 : * @param src source smart pointer
252 : * @return *this
253 : * @draft ICU 56
254 : */
255 0 : LocalPointer<T> &moveFrom(LocalPointer<T> &src) U_NOEXCEPT {
256 0 : delete LocalPointerBase<T>::ptr;
257 0 : LocalPointerBase<T>::ptr=src.ptr;
258 0 : src.ptr=NULL;
259 0 : return *this;
260 : }
261 : /**
262 : * Swap pointers.
263 : * @param other other smart pointer
264 : * @stable ICU 56
265 : */
266 : void swap(LocalPointer<T> &other) U_NOEXCEPT {
267 : T *temp=LocalPointerBase<T>::ptr;
268 : LocalPointerBase<T>::ptr=other.ptr;
269 : other.ptr=temp;
270 : }
271 : /**
272 : * Non-member LocalPointer swap function.
273 : * @param p1 will get p2's pointer
274 : * @param p2 will get p1's pointer
275 : * @stable ICU 56
276 : */
277 : friend inline void swap(LocalPointer<T> &p1, LocalPointer<T> &p2) U_NOEXCEPT {
278 : p1.swap(p2);
279 : }
280 : /**
281 : * Deletes the object it owns,
282 : * and adopts (takes ownership of) the one passed in.
283 : * @param p simple pointer to an object that is adopted
284 : * @stable ICU 4.4
285 : */
286 0 : void adoptInstead(T *p) {
287 0 : delete LocalPointerBase<T>::ptr;
288 0 : LocalPointerBase<T>::ptr=p;
289 0 : }
290 : /**
291 : * Deletes the object it owns,
292 : * and adopts (takes ownership of) the one passed in.
293 : *
294 : * If U_FAILURE(errorCode), then the current object is retained and the new one deleted.
295 : *
296 : * If U_SUCCESS(errorCode) but the input pointer is NULL,
297 : * then U_MEMORY_ALLOCATION_ERROR is set,
298 : * the current object is deleted, and NULL is set.
299 : *
300 : * @param p simple pointer to an object that is adopted
301 : * @param errorCode in/out UErrorCode, set to U_MEMORY_ALLOCATION_ERROR
302 : * if p==NULL and no other failure code had been set
303 : * @stable ICU 55
304 : */
305 0 : void adoptInsteadAndCheckErrorCode(T *p, UErrorCode &errorCode) {
306 0 : if(U_SUCCESS(errorCode)) {
307 0 : delete LocalPointerBase<T>::ptr;
308 0 : LocalPointerBase<T>::ptr=p;
309 0 : if(p==NULL) {
310 0 : errorCode=U_MEMORY_ALLOCATION_ERROR;
311 : }
312 : } else {
313 0 : delete p;
314 : }
315 0 : }
316 : };
317 :
318 : /**
319 : * "Smart pointer" class, deletes objects via the C++ array delete[] operator.
320 : * For most methods see the LocalPointerBase base class.
321 : * Adds operator[] for array item access.
322 : *
323 : * Usage example:
324 : * \code
325 : * LocalArray<UnicodeString> a(new UnicodeString[2]);
326 : * a[0].append((char16_t)0x61);
327 : * if(some condition) { return; } // no need to explicitly delete the array
328 : * a.adoptInstead(new UnicodeString[4]);
329 : * a[3].append((char16_t)0x62).append((char16_t)0x63).reverse();
330 : * // no need to explicitly delete the array
331 : * \endcode
332 : *
333 : * @see LocalPointerBase
334 : * @stable ICU 4.4
335 : */
336 : template<typename T>
337 : class LocalArray : public LocalPointerBase<T> {
338 : public:
339 : using LocalPointerBase<T>::operator*;
340 : using LocalPointerBase<T>::operator->;
341 : /**
342 : * Constructor takes ownership.
343 : * @param p simple pointer to an array of T objects that is adopted
344 : * @stable ICU 4.4
345 : */
346 0 : explicit LocalArray(T *p=NULL) : LocalPointerBase<T>(p) {}
347 : /**
348 : * Constructor takes ownership and reports an error if NULL.
349 : *
350 : * This constructor is intended to be used with other-class constructors
351 : * that may report a failure UErrorCode,
352 : * so that callers need to check only for U_FAILURE(errorCode)
353 : * and not also separately for isNull().
354 : *
355 : * @param p simple pointer to an array of T objects that is adopted
356 : * @param errorCode in/out UErrorCode, set to U_MEMORY_ALLOCATION_ERROR
357 : * if p==NULL and no other failure code had been set
358 : * @stable ICU 56
359 : */
360 0 : LocalArray(T *p, UErrorCode &errorCode) : LocalPointerBase<T>(p) {
361 0 : if(p==NULL && U_SUCCESS(errorCode)) {
362 0 : errorCode=U_MEMORY_ALLOCATION_ERROR;
363 : }
364 0 : }
365 : #if U_HAVE_RVALUE_REFERENCES
366 : /**
367 : * Move constructor, leaves src with isNull().
368 : * @param src source smart pointer
369 : * @stable ICU 56
370 : */
371 : LocalArray(LocalArray<T> &&src) U_NOEXCEPT : LocalPointerBase<T>(src.ptr) {
372 : src.ptr=NULL;
373 : }
374 : #endif
375 : /**
376 : * Destructor deletes the array it owns.
377 : * @stable ICU 4.4
378 : */
379 0 : ~LocalArray() {
380 0 : delete[] LocalPointerBase<T>::ptr;
381 0 : }
382 : #if U_HAVE_RVALUE_REFERENCES
383 : /**
384 : * Move assignment operator, leaves src with isNull().
385 : * The behavior is undefined if *this and src are the same object.
386 : * @param src source smart pointer
387 : * @return *this
388 : * @stable ICU 56
389 : */
390 : LocalArray<T> &operator=(LocalArray<T> &&src) U_NOEXCEPT {
391 : return moveFrom(src);
392 : }
393 : #endif
394 : // do not use #ifndef U_HIDE_DRAFT_API for moveFrom, needed by non-draft API
395 : /**
396 : * Move assignment, leaves src with isNull().
397 : * The behavior is undefined if *this and src are the same object.
398 : *
399 : * Can be called explicitly, does not need C++11 support.
400 : * @param src source smart pointer
401 : * @return *this
402 : * @draft ICU 56
403 : */
404 : LocalArray<T> &moveFrom(LocalArray<T> &src) U_NOEXCEPT {
405 : delete[] LocalPointerBase<T>::ptr;
406 : LocalPointerBase<T>::ptr=src.ptr;
407 : src.ptr=NULL;
408 : return *this;
409 : }
410 : /**
411 : * Swap pointers.
412 : * @param other other smart pointer
413 : * @stable ICU 56
414 : */
415 : void swap(LocalArray<T> &other) U_NOEXCEPT {
416 : T *temp=LocalPointerBase<T>::ptr;
417 : LocalPointerBase<T>::ptr=other.ptr;
418 : other.ptr=temp;
419 : }
420 : /**
421 : * Non-member LocalArray swap function.
422 : * @param p1 will get p2's pointer
423 : * @param p2 will get p1's pointer
424 : * @stable ICU 56
425 : */
426 : friend inline void swap(LocalArray<T> &p1, LocalArray<T> &p2) U_NOEXCEPT {
427 : p1.swap(p2);
428 : }
429 : /**
430 : * Deletes the array it owns,
431 : * and adopts (takes ownership of) the one passed in.
432 : * @param p simple pointer to an array of T objects that is adopted
433 : * @stable ICU 4.4
434 : */
435 : void adoptInstead(T *p) {
436 : delete[] LocalPointerBase<T>::ptr;
437 : LocalPointerBase<T>::ptr=p;
438 : }
439 : /**
440 : * Deletes the array it owns,
441 : * and adopts (takes ownership of) the one passed in.
442 : *
443 : * If U_FAILURE(errorCode), then the current array is retained and the new one deleted.
444 : *
445 : * If U_SUCCESS(errorCode) but the input pointer is NULL,
446 : * then U_MEMORY_ALLOCATION_ERROR is set,
447 : * the current array is deleted, and NULL is set.
448 : *
449 : * @param p simple pointer to an array of T objects that is adopted
450 : * @param errorCode in/out UErrorCode, set to U_MEMORY_ALLOCATION_ERROR
451 : * if p==NULL and no other failure code had been set
452 : * @stable ICU 56
453 : */
454 : void adoptInsteadAndCheckErrorCode(T *p, UErrorCode &errorCode) {
455 : if(U_SUCCESS(errorCode)) {
456 : delete[] LocalPointerBase<T>::ptr;
457 : LocalPointerBase<T>::ptr=p;
458 : if(p==NULL) {
459 : errorCode=U_MEMORY_ALLOCATION_ERROR;
460 : }
461 : } else {
462 : delete[] p;
463 : }
464 : }
465 : /**
466 : * Array item access (writable).
467 : * No index bounds check.
468 : * @param i array index
469 : * @return reference to the array item
470 : * @stable ICU 4.4
471 : */
472 0 : T &operator[](ptrdiff_t i) const { return LocalPointerBase<T>::ptr[i]; }
473 : };
474 :
475 : /**
476 : * \def U_DEFINE_LOCAL_OPEN_POINTER
477 : * "Smart pointer" definition macro, deletes objects via the closeFunction.
478 : * Defines a subclass of LocalPointerBase which works just
479 : * like LocalPointer<Type> except that this subclass will use the closeFunction
480 : * rather than the C++ delete operator.
481 : *
482 : * Usage example:
483 : * \code
484 : * LocalUCaseMapPointer csm(ucasemap_open(localeID, options, &errorCode));
485 : * utf8OutLength=ucasemap_utf8ToLower(csm.getAlias(),
486 : * utf8Out, (int32_t)sizeof(utf8Out),
487 : * utf8In, utf8InLength, &errorCode);
488 : * if(U_FAILURE(errorCode)) { return; } // no need to explicitly delete the UCaseMap
489 : * \endcode
490 : *
491 : * @see LocalPointerBase
492 : * @see LocalPointer
493 : * @stable ICU 4.4
494 : */
495 : #if U_HAVE_RVALUE_REFERENCES
496 : #define U_DEFINE_LOCAL_OPEN_POINTER(LocalPointerClassName, Type, closeFunction) \
497 : class LocalPointerClassName : public LocalPointerBase<Type> { \
498 : public: \
499 : using LocalPointerBase<Type>::operator*; \
500 : using LocalPointerBase<Type>::operator->; \
501 : explicit LocalPointerClassName(Type *p=NULL) : LocalPointerBase<Type>(p) {} \
502 : LocalPointerClassName(LocalPointerClassName &&src) U_NOEXCEPT \
503 : : LocalPointerBase<Type>(src.ptr) { \
504 : src.ptr=NULL; \
505 : } \
506 : ~LocalPointerClassName() { if (ptr != NULL) { closeFunction(ptr); } } \
507 : LocalPointerClassName &operator=(LocalPointerClassName &&src) U_NOEXCEPT { \
508 : return moveFrom(src); \
509 : } \
510 : LocalPointerClassName &moveFrom(LocalPointerClassName &src) U_NOEXCEPT { \
511 : if (ptr != NULL) { closeFunction(ptr); } \
512 : LocalPointerBase<Type>::ptr=src.ptr; \
513 : src.ptr=NULL; \
514 : return *this; \
515 : } \
516 : void swap(LocalPointerClassName &other) U_NOEXCEPT { \
517 : Type *temp=LocalPointerBase<Type>::ptr; \
518 : LocalPointerBase<Type>::ptr=other.ptr; \
519 : other.ptr=temp; \
520 : } \
521 : friend inline void swap(LocalPointerClassName &p1, LocalPointerClassName &p2) U_NOEXCEPT { \
522 : p1.swap(p2); \
523 : } \
524 : void adoptInstead(Type *p) { \
525 : if (ptr != NULL) { closeFunction(ptr); } \
526 : ptr=p; \
527 : } \
528 : }
529 : #else
530 : #define U_DEFINE_LOCAL_OPEN_POINTER(LocalPointerClassName, Type, closeFunction) \
531 : class LocalPointerClassName : public LocalPointerBase<Type> { \
532 : public: \
533 : using LocalPointerBase<Type>::operator*; \
534 : using LocalPointerBase<Type>::operator->; \
535 : explicit LocalPointerClassName(Type *p=NULL) : LocalPointerBase<Type>(p) {} \
536 : ~LocalPointerClassName() { closeFunction(ptr); } \
537 : LocalPointerClassName &moveFrom(LocalPointerClassName &src) U_NOEXCEPT { \
538 : if (ptr != NULL) { closeFunction(ptr); } \
539 : LocalPointerBase<Type>::ptr=src.ptr; \
540 : src.ptr=NULL; \
541 : return *this; \
542 : } \
543 : void swap(LocalPointerClassName &other) U_NOEXCEPT { \
544 : Type *temp=LocalPointerBase<Type>::ptr; \
545 : LocalPointerBase<Type>::ptr=other.ptr; \
546 : other.ptr=temp; \
547 : } \
548 : friend inline void swap(LocalPointerClassName &p1, LocalPointerClassName &p2) U_NOEXCEPT { \
549 : p1.swap(p2); \
550 : } \
551 : void adoptInstead(Type *p) { \
552 : if (ptr != NULL) { closeFunction(ptr); } \
553 : ptr=p; \
554 : } \
555 : }
556 : #endif
557 :
558 : U_NAMESPACE_END
559 :
560 : #endif /* U_SHOW_CPLUSPLUS_API */
561 : #endif /* __LOCALPOINTER_H__ */
|
