| /* |
| ******************************************************************************* |
| * |
| * Copyright (C) 2009-2010, 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 |
| |
| /** |
| * "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: |
| T *ptr; |
| private: |
| // No comparison operators with other LocalPointerBases. |
| bool operator==(const LocalPointerBase &other); |
| bool operator!=(const LocalPointerBase &other); |
| // No ownership transfer: No copy constructor, no assignment operator. |
| LocalPointerBase(const LocalPointerBase &other); |
| void operator=(const LocalPointerBase &other); |
| // No heap allocation. Use only on the stack. |
| static void * U_EXPORT2 operator new(size_t size); |
| static void * U_EXPORT2 operator new[](size_t size); |
| #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) {} |
| /** |
| * Destructor deletes the object it owns. |
| * @stable ICU 4.4 |
| */ |
| ~LocalPointer() { |
| delete LocalPointerBase<T>::ptr; |
| } |
| /** |
| * 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; |
| } |
| }; |
| |
| /** |
| * "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) {} |
| /** |
| * Destructor deletes the array it owns. |
| * @stable ICU 4.4 |
| */ |
| ~LocalArray() { |
| delete[] LocalPointerBase<T>::ptr; |
| } |
| /** |
| * 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; |
| } |
| /** |
| * 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 |
| */ |
| #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); } \ |
| void adoptInstead(Type *p) { \ |
| closeFunction(ptr); \ |
| ptr=p; \ |
| } \ |
| } |
| |
| U_NAMESPACE_END |
| |
| #endif /* U_SHOW_CPLUSPLUS_API */ |
| #endif /* __LOCALPOINTER_H__ */ |