| /* | |
| ******************************************************************************* | |
| * | |
| * Copyright (C) 2009-2015, International Business Machines | |
| * Corporation and others. All Rights Reserved. | |
| * | |
| ******************************************************************************* | |
| * file name: localpointer.h | |
| * encoding: US-ASCII | |
| * tab size: 8 (not used) | |
| * indentation:4 | |
| * | |
| * created on: 2009nov13 | |
| * created by: Markus W. Scherer | |
| */ | |
| #ifndef __LOCALPOINTER_H__ | |
| #define __LOCALPOINTER_H__ | |
| /** | |
| * \file | |
| * \brief C++ API: "Smart pointers" for use with and in ICU4C C++ code. | |
| * | |
| * These classes are inspired by | |
| * - std::auto_ptr | |
| * - boost::scoped_ptr & boost::scoped_array | |
| * - Taligent Safe Pointers (TOnlyPointerTo) | |
| * | |
| * but none of those provide for all of the goals for ICU smart pointers: | |
| * - Smart pointer owns the object and releases it when it goes out of scope. | |
| * - No transfer of ownership via copy/assignment to reduce misuse. Simpler & more robust. | |
| * - ICU-compatible: No exceptions. | |
| * - Need to be able to orphan/release the pointer and its ownership. | |
| * - Need variants for normal C++ object pointers, C++ arrays, and ICU C service objects. | |
| * | |
| * For details see http://site.icu-project.org/design/cpp/scoped_ptr | |
| */ | |
| #include "unicode/utypes.h" | |
| #if U_SHOW_CPLUSPLUS_API | |
| U_NAMESPACE_BEGIN | |
| // The operator new is declared but not defined to prevent custom functions that | |
| // heap allocate the object. | |
| #if defined(__ghs__) | |
| // Linker requires an implementation. | |
| #define IGNORE_DECLARATION { ASSERT(0); return NULL; } | |
| #else | |
| #define IGNORE_DECLARATION | |
| #endif | |
| /** | |
| * "Smart pointer" base class; do not use directly: use LocalPointer etc. | |
| * | |
| * Base class for smart pointer classes that do not throw exceptions. | |
| * | |
| * Do not use this base class directly, since it does not delete its pointer. | |
| * A subclass must implement methods that delete the pointer: | |
| * Destructor and adoptInstead(). | |
| * | |
| * There is no operator T *() provided because the programmer must decide | |
| * whether to use getAlias() (without transfer of ownership) or orpan() | |
| * (with transfer of ownership and NULLing of the pointer). | |
| * | |
| * @see LocalPointer | |
| * @see LocalArray | |
| * @see U_DEFINE_LOCAL_OPEN_POINTER | |
| * @stable ICU 4.4 | |
| */ | |
| template<typename T> | |
| class LocalPointerBase { | |
| public: | |
| /** | |
| * Constructor takes ownership. | |
| * @param p simple pointer to an object that is adopted | |
| * @stable ICU 4.4 | |
| */ | |
| explicit LocalPointerBase(T *p=NULL) : ptr(p) {} | |
| /** | |
| * Destructor deletes the object it owns. | |
| * Subclass must override: Base class does nothing. | |
| * @stable ICU 4.4 | |
| */ | |
| ~LocalPointerBase() { /* delete ptr; */ } | |
| /** | |
| * NULL check. | |
| * @return TRUE if ==NULL | |
| * @stable ICU 4.4 | |
| */ | |
| UBool isNull() const { return ptr==NULL; } | |
| /** | |
| * NULL check. | |
| * @return TRUE if !=NULL | |
| * @stable ICU 4.4 | |
| */ | |
| UBool isValid() const { return ptr!=NULL; } | |
| /** | |
| * Comparison with a simple pointer, so that existing code | |
| * with ==NULL need not be changed. | |
| * @param other simple pointer for comparison | |
| * @return true if this pointer value equals other | |
| * @stable ICU 4.4 | |
| */ | |
| bool operator==(const T *other) const { return ptr==other; } | |
| /** | |
| * Comparison with a simple pointer, so that existing code | |
| * with !=NULL need not be changed. | |
| * @param other simple pointer for comparison | |
| * @return true if this pointer value differs from other | |
| * @stable ICU 4.4 | |
| */ | |
| bool operator!=(const T *other) const { return ptr!=other; } | |
| /** | |
| * Access without ownership change. | |
| * @return the pointer value | |
| * @stable ICU 4.4 | |
| */ | |
| T *getAlias() const { return ptr; } | |
| /** | |
| * Access without ownership change. | |
| * @return the pointer value as a reference | |
| * @stable ICU 4.4 | |
| */ | |
| T &operator*() const { return *ptr; } | |
| /** | |
| * Access without ownership change. | |
| * @return the pointer value | |
| * @stable ICU 4.4 | |
| */ | |
| T *operator->() const { return ptr; } | |
| /** | |
| * Gives up ownership; the internal pointer becomes NULL. | |
| * @return the pointer value; | |
| * caller becomes responsible for deleting the object | |
| * @stable ICU 4.4 | |
| */ | |
| T *orphan() { | |
| T *p=ptr; | |
| ptr=NULL; | |
| return p; | |
| } | |
| /** | |
| * Deletes the object it owns, | |
| * and adopts (takes ownership of) the one passed in. | |
| * Subclass must override: Base class does not delete the object. | |
| * @param p simple pointer to an object that is adopted | |
| * @stable ICU 4.4 | |
| */ | |
| void adoptInstead(T *p) { | |
| // delete ptr; | |
| ptr=p; | |
| } | |
| protected: | |
| /** | |
| * Actual pointer. | |
| * @internal | |
| */ | |
| T *ptr; | |
| private: | |
| // No comparison operators with other LocalPointerBases. | |
| bool operator==(const LocalPointerBase<T> &other); | |
| bool operator!=(const LocalPointerBase<T> &other); | |
| // No ownership sharing: No copy constructor, no assignment operator. | |
| LocalPointerBase(const LocalPointerBase<T> &other); | |
| void operator=(const LocalPointerBase<T> &other); | |
| // No heap allocation. Use only on the stack. | |
| static void * U_EXPORT2 operator new(size_t size) IGNORE_DECLARATION; | |
| static void * U_EXPORT2 operator new[](size_t size) IGNORE_DECLARATION; | |
| #if U_HAVE_PLACEMENT_NEW | |
| static void * U_EXPORT2 operator new(size_t, void *ptr); | |
| #endif | |
| }; | |
| /** | |
| * "Smart pointer" class, deletes objects via the standard C++ delete operator. | |
| * For most methods see the LocalPointerBase base class. | |
| * | |
| * Usage example: | |
| * \code | |
| * LocalPointer<UnicodeString> s(new UnicodeString((UChar32)0x50005)); | |
| * int32_t length=s->length(); // 2 | |
| * UChar lead=s->charAt(0); // 0xd900 | |
| * if(some condition) { return; } // no need to explicitly delete the pointer | |
| * s.adoptInstead(new UnicodeString((UChar)0xfffc)); | |
| * length=s->length(); // 1 | |
| * // no need to explicitly delete the pointer | |
| * \endcode | |
| * | |
| * @see LocalPointerBase | |
| * @stable ICU 4.4 | |
| */ | |
| template<typename T> | |
| class LocalPointer : public LocalPointerBase<T> { | |
| public: | |
| /** | |
| * Constructor takes ownership. | |
| * @param p simple pointer to an object that is adopted | |
| * @stable ICU 4.4 | |
| */ | |
| explicit LocalPointer(T *p=NULL) : LocalPointerBase<T>(p) {} | |
| #ifndef U_HIDE_DRAFT_API | |
| /** | |
| * Constructor takes ownership and reports an error if NULL. | |
| * | |
| * This constructor is intended to be used with other-class constructors | |
| * that may report a failure UErrorCode, | |
| * so that callers need to check only for U_FAILURE(errorCode) | |
| * and not also separately for isNull(). | |
| * | |
| * @param p simple pointer to an object that is adopted | |
| * @param errorCode in/out UErrorCode, set to U_MEMORY_ALLOCATION_ERROR | |
| * if p==NULL and no other failure code had been set | |
| * @draft ICU 55 | |
| */ | |
| LocalPointer(T *p, UErrorCode &errorCode) : LocalPointerBase<T>(p) { | |
| if(p==NULL && U_SUCCESS(errorCode)) { | |
| errorCode=U_MEMORY_ALLOCATION_ERROR; | |
| } | |
| } | |
| #if U_HAVE_RVALUE_REFERENCES | |
| /** | |
| * Move constructor, leaves src with isNull(). | |
| * @param src source smart pointer | |
| * @draft ICU 56 | |
| */ | |
| LocalPointer(LocalPointer<T> &&src) U_NOEXCEPT : LocalPointerBase<T>(src.ptr) { | |
| src.ptr=NULL; | |
| } | |
| #endif | |
| #endif /* U_HIDE_DRAFT_API */ | |
| /** | |
| * Destructor deletes the object it owns. | |
| * @stable ICU 4.4 | |
| */ | |
| ~LocalPointer() { | |
| delete LocalPointerBase<T>::ptr; | |
| } | |
| #ifndef U_HIDE_DRAFT_API | |
| #if U_HAVE_RVALUE_REFERENCES | |
| /** | |
| * Move assignment operator, leaves src with isNull(). | |
| * The behavior is undefined if *this and src are the same object. | |
| * @param src source smart pointer | |
| * @return *this | |
| * @draft ICU 56 | |
| */ | |
| LocalPointer<T> &operator=(LocalPointer<T> &&src) U_NOEXCEPT { | |
| return moveFrom(src); | |
| } | |
| #endif | |
| /** | |
| * Move assignment, leaves src with isNull(). | |
| * The behavior is undefined if *this and src are the same object. | |
| * | |
| * Can be called explicitly, does not need C++11 support. | |
| * @param src source smart pointer | |
| * @return *this | |
| * @draft ICU 56 | |
| */ | |
| LocalPointer<T> &moveFrom(LocalPointer<T> &src) U_NOEXCEPT { | |
| delete LocalPointerBase<T>::ptr; | |
| LocalPointerBase<T>::ptr=src.ptr; | |
| src.ptr=NULL; | |
| return *this; | |
| } | |
| /** | |
| * Swap pointers. | |
| * @param other other smart pointer | |
| * @draft ICU 56 | |
| */ | |
| void swap(LocalPointer<T> &other) U_NOEXCEPT { | |
| T *temp=LocalPointerBase<T>::ptr; | |
| LocalPointerBase<T>::ptr=other.ptr; | |
| other.ptr=temp; | |
| } | |
| /** | |
| * Non-member LocalPointer swap function. | |
| * @param p1 will get p2's pointer | |
| * @param p2 will get p1's pointer | |
| * @draft ICU 56 | |
| */ | |
| friend inline void swap(LocalPointer<T> &p1, LocalPointer<T> &p2) U_NOEXCEPT { | |
| p1.swap(p2); | |
| } | |
| #endif /* U_HIDE_DRAFT_API */ | |
| /** | |
| * Deletes the object it owns, | |
| * and adopts (takes ownership of) the one passed in. | |
| * @param p simple pointer to an object that is adopted | |
| * @stable ICU 4.4 | |
| */ | |
| void adoptInstead(T *p) { | |
| delete LocalPointerBase<T>::ptr; | |
| LocalPointerBase<T>::ptr=p; | |
| } | |
| #ifndef U_HIDE_DRAFT_API | |
| /** | |
| * Deletes the object it owns, | |
| * and adopts (takes ownership of) the one passed in. | |
| * | |
| * If U_FAILURE(errorCode), then the current object is retained and the new one deleted. | |
| * | |
| * If U_SUCCESS(errorCode) but the input pointer is NULL, | |
| * then U_MEMORY_ALLOCATION_ERROR is set, | |
| * the current object is deleted, and NULL is set. | |
| * | |
| * @param p simple pointer to an object that is adopted | |
| * @param errorCode in/out UErrorCode, set to U_MEMORY_ALLOCATION_ERROR | |
| * if p==NULL and no other failure code had been set | |
| * @draft ICU 55 | |
| */ | |
| void adoptInsteadAndCheckErrorCode(T *p, UErrorCode &errorCode) { | |
| if(U_SUCCESS(errorCode)) { | |
| delete LocalPointerBase<T>::ptr; | |
| LocalPointerBase<T>::ptr=p; | |
| if(p==NULL) { | |
| errorCode=U_MEMORY_ALLOCATION_ERROR; | |
| } | |
| } else { | |
| delete p; | |
| } | |
| } | |
| #endif /* U_HIDE_DRAFT_API */ | |
| }; | |
| /** | |
| * "Smart pointer" class, deletes objects via the C++ array delete[] operator. | |
| * For most methods see the LocalPointerBase base class. | |
| * Adds operator[] for array item access. | |
| * | |
| * Usage example: | |
| * \code | |
| * LocalArray<UnicodeString> a(new UnicodeString[2]); | |
| * a[0].append((UChar)0x61); | |
| * if(some condition) { return; } // no need to explicitly delete the array | |
| * a.adoptInstead(new UnicodeString[4]); | |
| * a[3].append((UChar)0x62).append((UChar)0x63).reverse(); | |
| * // no need to explicitly delete the array | |
| * \endcode | |
| * | |
| * @see LocalPointerBase | |
| * @stable ICU 4.4 | |
| */ | |
| template<typename T> | |
| class LocalArray : public LocalPointerBase<T> { | |
| public: | |
| /** | |
| * Constructor takes ownership. | |
| * @param p simple pointer to an array of T objects that is adopted | |
| * @stable ICU 4.4 | |
| */ | |
| explicit LocalArray(T *p=NULL) : LocalPointerBase<T>(p) {} | |
| #ifndef U_HIDE_DRAFT_API | |
| /** | |
| * Constructor takes ownership and reports an error if NULL. | |
| * | |
| * This constructor is intended to be used with other-class constructors | |
| * that may report a failure UErrorCode, | |
| * so that callers need to check only for U_FAILURE(errorCode) | |
| * and not also separately for isNull(). | |
| * | |
| * @param p simple pointer to an array of T objects that is adopted | |
| * @param errorCode in/out UErrorCode, set to U_MEMORY_ALLOCATION_ERROR | |
| * if p==NULL and no other failure code had been set | |
| * @draft ICU 56 | |
| */ | |
| LocalArray(T *p, UErrorCode &errorCode) : LocalPointerBase<T>(p) { | |
| if(p==NULL && U_SUCCESS(errorCode)) { | |
| errorCode=U_MEMORY_ALLOCATION_ERROR; | |
| } | |
| } | |
| #if U_HAVE_RVALUE_REFERENCES | |
| /** | |
| * Move constructor, leaves src with isNull(). | |
| * @param src source smart pointer | |
| * @draft ICU 56 | |
| */ | |
| LocalArray(LocalArray<T> &&src) U_NOEXCEPT : LocalPointerBase<T>(src.ptr) { | |
| src.ptr=NULL; | |
| } | |
| #endif | |
| #endif /* U_HIDE_DRAFT_API */ | |
| /** | |
| * Destructor deletes the array it owns. | |
| * @stable ICU 4.4 | |
| */ | |
| ~LocalArray() { | |
| delete[] LocalPointerBase<T>::ptr; | |
| } | |
| #ifndef U_HIDE_DRAFT_API | |
| #if U_HAVE_RVALUE_REFERENCES | |
| /** | |
| * Move assignment operator, leaves src with isNull(). | |
| * The behavior is undefined if *this and src are the same object. | |
| * @param src source smart pointer | |
| * @return *this | |
| * @draft ICU 56 | |
| */ | |
| LocalArray<T> &operator=(LocalArray<T> &&src) U_NOEXCEPT { | |
| return moveFrom(src); | |
| } | |
| #endif | |
| /** | |
| * Move assignment, leaves src with isNull(). | |
| * The behavior is undefined if *this and src are the same object. | |
| * | |
| * Can be called explicitly, does not need C++11 support. | |
| * @param src source smart pointer | |
| * @return *this | |
| * @draft ICU 56 | |
| */ | |
| LocalArray<T> &moveFrom(LocalArray<T> &src) U_NOEXCEPT { | |
| delete[] LocalPointerBase<T>::ptr; | |
| LocalPointerBase<T>::ptr=src.ptr; | |
| src.ptr=NULL; | |
| return *this; | |
| } | |
| /** | |
| * Swap pointers. | |
| * @param other other smart pointer | |
| * @draft ICU 56 | |
| */ | |
| void swap(LocalArray<T> &other) U_NOEXCEPT { | |
| T *temp=LocalPointerBase<T>::ptr; | |
| LocalPointerBase<T>::ptr=other.ptr; | |
| other.ptr=temp; | |
| } | |
| /** | |
| * Non-member LocalArray swap function. | |
| * @param p1 will get p2's pointer | |
| * @param p2 will get p1's pointer | |
| * @draft ICU 56 | |
| */ | |
| friend inline void swap(LocalArray<T> &p1, LocalArray<T> &p2) U_NOEXCEPT { | |
| p1.swap(p2); | |
| } | |
| #endif /* U_HIDE_DRAFT_API */ | |
| /** | |
| * Deletes the array it owns, | |
| * and adopts (takes ownership of) the one passed in. | |
| * @param p simple pointer to an array of T objects that is adopted | |
| * @stable ICU 4.4 | |
| */ | |
| void adoptInstead(T *p) { | |
| delete[] LocalPointerBase<T>::ptr; | |
| LocalPointerBase<T>::ptr=p; | |
| } | |
| #ifndef U_HIDE_DRAFT_API | |
| /** | |
| * Deletes the array it owns, | |
| * and adopts (takes ownership of) the one passed in. | |
| * | |
| * If U_FAILURE(errorCode), then the current array is retained and the new one deleted. | |
| * | |
| * If U_SUCCESS(errorCode) but the input pointer is NULL, | |
| * then U_MEMORY_ALLOCATION_ERROR is set, | |
| * the current array is deleted, and NULL is set. | |
| * | |
| * @param p simple pointer to an array of T objects that is adopted | |
| * @param errorCode in/out UErrorCode, set to U_MEMORY_ALLOCATION_ERROR | |
| * if p==NULL and no other failure code had been set | |
| * @draft ICU 56 | |
| */ | |
| void adoptInsteadAndCheckErrorCode(T *p, UErrorCode &errorCode) { | |
| if(U_SUCCESS(errorCode)) { | |
| delete[] LocalPointerBase<T>::ptr; | |
| LocalPointerBase<T>::ptr=p; | |
| if(p==NULL) { | |
| errorCode=U_MEMORY_ALLOCATION_ERROR; | |
| } | |
| } else { | |
| delete[] p; | |
| } | |
| } | |
| #endif /* U_HIDE_DRAFT_API */ | |
| /** | |
| * Array item access (writable). | |
| * No index bounds check. | |
| * @param i array index | |
| * @return reference to the array item | |
| * @stable ICU 4.4 | |
| */ | |
| T &operator[](ptrdiff_t i) const { return LocalPointerBase<T>::ptr[i]; } | |
| }; | |
| /** | |
| * \def U_DEFINE_LOCAL_OPEN_POINTER | |
| * "Smart pointer" definition macro, deletes objects via the closeFunction. | |
| * Defines a subclass of LocalPointerBase which works just | |
| * like LocalPointer<Type> except that this subclass will use the closeFunction | |
| * rather than the C++ delete operator. | |
| * | |
| * Requirement: The closeFunction must tolerate a NULL pointer. | |
| * (We could add a NULL check here but it is normally redundant.) | |
| * | |
| * Usage example: | |
| * \code | |
| * LocalUCaseMapPointer csm(ucasemap_open(localeID, options, &errorCode)); | |
| * utf8OutLength=ucasemap_utf8ToLower(csm.getAlias(), | |
| * utf8Out, (int32_t)sizeof(utf8Out), | |
| * utf8In, utf8InLength, &errorCode); | |
| * if(U_FAILURE(errorCode)) { return; } // no need to explicitly delete the UCaseMap | |
| * \endcode | |
| * | |
| * @see LocalPointerBase | |
| * @see LocalPointer | |
| * @stable ICU 4.4 | |
| */ | |
| #if U_HAVE_RVALUE_REFERENCES | |
| #define U_DEFINE_LOCAL_OPEN_POINTER(LocalPointerClassName, Type, closeFunction) \ | |
| class LocalPointerClassName : public LocalPointerBase<Type> { \ | |
| public: \ | |
| explicit LocalPointerClassName(Type *p=NULL) : LocalPointerBase<Type>(p) {} \ | |
| LocalPointerClassName(LocalPointerClassName &&src) U_NOEXCEPT \ | |
| : LocalPointerBase<Type>(src.ptr) { \ | |
| src.ptr=NULL; \ | |
| } \ | |
| ~LocalPointerClassName() { closeFunction(ptr); } \ | |
| LocalPointerClassName &operator=(LocalPointerClassName &&src) U_NOEXCEPT { \ | |
| return moveFrom(src); \ | |
| } \ | |
| LocalPointerClassName &moveFrom(LocalPointerClassName &src) U_NOEXCEPT { \ | |
| closeFunction(ptr); \ | |
| LocalPointerBase<Type>::ptr=src.ptr; \ | |
| src.ptr=NULL; \ | |
| return *this; \ | |
| } \ | |
| void swap(LocalPointerClassName &other) U_NOEXCEPT { \ | |
| Type *temp=LocalPointerBase<Type>::ptr; \ | |
| LocalPointerBase<Type>::ptr=other.ptr; \ | |
| other.ptr=temp; \ | |
| } \ | |
| friend inline void swap(LocalPointerClassName &p1, LocalPointerClassName &p2) U_NOEXCEPT { \ | |
| p1.swap(p2); \ | |
| } \ | |
| void adoptInstead(Type *p) { \ | |
| closeFunction(ptr); \ | |
| ptr=p; \ | |
| } \ | |
| } | |
| #else | |
| #define U_DEFINE_LOCAL_OPEN_POINTER(LocalPointerClassName, Type, closeFunction) \ | |
| class LocalPointerClassName : public LocalPointerBase<Type> { \ | |
| public: \ | |
| explicit LocalPointerClassName(Type *p=NULL) : LocalPointerBase<Type>(p) {} \ | |
| ~LocalPointerClassName() { closeFunction(ptr); } \ | |
| LocalPointerClassName &moveFrom(LocalPointerClassName &src) U_NOEXCEPT { \ | |
| closeFunction(ptr); \ | |
| LocalPointerBase<Type>::ptr=src.ptr; \ | |
| src.ptr=NULL; \ | |
| return *this; \ | |
| } \ | |
| void swap(LocalPointerClassName &other) U_NOEXCEPT { \ | |
| Type *temp=LocalPointerBase<Type>::ptr; \ | |
| LocalPointerBase<Type>::ptr=other.ptr; \ | |
| other.ptr=temp; \ | |
| } \ | |
| friend inline void swap(LocalPointerClassName &p1, LocalPointerClassName &p2) U_NOEXCEPT { \ | |
| p1.swap(p2); \ | |
| } \ | |
| void adoptInstead(Type *p) { \ | |
| closeFunction(ptr); \ | |
| ptr=p; \ | |
| } \ | |
| } | |
| #endif | |
| U_NAMESPACE_END | |
| #endif /* U_SHOW_CPLUSPLUS_API */ | |
| #endif /* __LOCALPOINTER_H__ */ |