// © 2016 and later: Unicode, Inc. and others. // License & terms of use: http://www.unicode.org/copyright.html /* ******************************************************************************* * * Copyright (C) 2009-2016, International Business Machines * Corporation and others. All Rights Reserved. * ******************************************************************************* * file name: localpointer.h * encoding: UTF-8 * 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 #include <memory> 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 orphan() * (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: // No heap allocation. Use only on the stack. static void* U_EXPORT2 operator new(size_t) = delete; static void* U_EXPORT2 operator new[](size_t) = delete; #if U_HAVE_PLACEMENT_NEW static void* U_EXPORT2 operator new(size_t, void*) = delete; #endif /** * 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); }; /** * "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 * char16_t lead=s->charAt(0); // 0xd900 * if(some condition) { return; } // no need to explicitly delete the pointer * s.adoptInstead(new UnicodeString((char16_t)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: using LocalPointerBase<T>::operator*; using LocalPointerBase<T>::operator->; /** * 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) {} /** * 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 * @stable ICU 55 */ LocalPointer(T *p, UErrorCode &errorCode) : LocalPointerBase<T>(p) { if(p==NULL && U_SUCCESS(errorCode)) { errorCode=U_MEMORY_ALLOCATION_ERROR; } } /** * Move constructor, leaves src with isNull(). * @param src source smart pointer * @stable ICU 56 */ LocalPointer(LocalPointer<T> &&src) U_NOEXCEPT : LocalPointerBase<T>(src.ptr) { src.ptr=NULL; } /** * Constructs a LocalPointer from a C++11 std::unique_ptr. * The LocalPointer steals the object owned by the std::unique_ptr. * * This constructor works via move semantics. If your std::unique_ptr is * in a local variable, you must use std::move. * * @param p The std::unique_ptr from which the pointer will be stolen. * @stable ICU 64 */ explicit LocalPointer(std::unique_ptr<T> &&p) : LocalPointerBase<T>(p.release()) {} /** * Destructor deletes the object it owns. * @stable ICU 4.4 */ ~LocalPointer() { delete LocalPointerBase<T>::ptr; } /** * 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 * @stable ICU 56 */ LocalPointer<T> &operator=(LocalPointer<T> &&src) U_NOEXCEPT { delete LocalPointerBase<T>::ptr; LocalPointerBase<T>::ptr=src.ptr; src.ptr=NULL; return *this; } /** * Move-assign from an std::unique_ptr to this LocalPointer. * Steals the pointer from the std::unique_ptr. * * @param p The std::unique_ptr from which the pointer will be stolen. * @return *this * @stable ICU 64 */ LocalPointer<T> &operator=(std::unique_ptr<T> &&p) U_NOEXCEPT { adoptInstead(p.release()); return *this; } /** * Swap pointers. * @param other other smart pointer * @stable 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 * @stable ICU 56 */ friend inline void swap(LocalPointer<T> &p1, LocalPointer<T> &p2) U_NOEXCEPT { p1.swap(p2); } /** * 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; } /** * 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 * @stable 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; } } /** * Conversion operator to a C++11 std::unique_ptr. * Disowns the object and gives it to the returned std::unique_ptr. * * This operator works via move semantics. If your LocalPointer is * in a local variable, you must use std::move. * * @return An std::unique_ptr owning the pointer previously owned by this * icu::LocalPointer. * @stable ICU 64 */ operator std::unique_ptr<T> () && { return std::unique_ptr<T>(LocalPointerBase<T>::orphan()); } }; /** * "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((char16_t)0x61); * if(some condition) { return; } // no need to explicitly delete the array * a.adoptInstead(new UnicodeString[4]); * a[3].append((char16_t)0x62).append((char16_t)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: using LocalPointerBase<T>::operator*; using LocalPointerBase<T>::operator->; /** * 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) {} /** * 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 * @stable ICU 56 */ LocalArray(T *p, UErrorCode &errorCode) : LocalPointerBase<T>(p) { if(p==NULL && U_SUCCESS(errorCode)) { errorCode=U_MEMORY_ALLOCATION_ERROR; } } /** * Move constructor, leaves src with isNull(). * @param src source smart pointer * @stable ICU 56 */ LocalArray(LocalArray<T> &&src) U_NOEXCEPT : LocalPointerBase<T>(src.ptr) { src.ptr=NULL; } /** * Constructs a LocalArray from a C++11 std::unique_ptr of an array type. * The LocalPointer steals the array owned by the std::unique_ptr. * * This constructor works via move semantics. If your std::unique_ptr is * in a local variable, you must use std::move. * * @param p The std::unique_ptr from which the array will be stolen. * @stable ICU 64 */ explicit LocalArray(std::unique_ptr<T[]> &&p) : LocalPointerBase<T>(p.release()) {} /** * Destructor deletes the array it owns. * @stable ICU 4.4 */ ~LocalArray() { delete[] LocalPointerBase<T>::ptr; } /** * 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 * @stable ICU 56 */ LocalArray<T> &operator=(LocalArray<T> &&src) U_NOEXCEPT { delete[] LocalPointerBase<T>::ptr; LocalPointerBase<T>::ptr=src.ptr; src.ptr=NULL; return *this; } /** * Move-assign from an std::unique_ptr to this LocalPointer. * Steals the array from the std::unique_ptr. * * @param p The std::unique_ptr from which the array will be stolen. * @return *this * @stable ICU 64 */ LocalArray<T> &operator=(std::unique_ptr<T[]> &&p) U_NOEXCEPT { adoptInstead(p.release()); return *this; } /** * Swap pointers. * @param other other smart pointer * @stable 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 * @stable ICU 56 */ friend inline void swap(LocalArray<T> &p1, LocalArray<T> &p2) U_NOEXCEPT { p1.swap(p2); } /** * 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; } /** * 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 * @stable 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; } } /** * 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]; } /** * Conversion operator to a C++11 std::unique_ptr. * Disowns the object and gives it to the returned std::unique_ptr. * * This operator works via move semantics. If your LocalPointer is * in a local variable, you must use std::move. * * @return An std::unique_ptr owning the pointer previously owned by this * icu::LocalPointer. * @stable ICU 64 */ operator std::unique_ptr<T[]> () && { return std::unique_ptr<T[]>(LocalPointerBase<T>::orphan()); } }; /** * \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. * * 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: \ using LocalPointerBase<Type>::operator*; \ using LocalPointerBase<Type>::operator->; \ explicit LocalPointerClassName(Type *p=NULL) : LocalPointerBase<Type>(p) {} \ LocalPointerClassName(LocalPointerClassName &&src) U_NOEXCEPT \ : LocalPointerBase<Type>(src.ptr) { \ src.ptr=NULL; \ } \ /* TODO: Be agnostic of the deleter function signature from the user-provided std::unique_ptr? */ \ explicit LocalPointerClassName(std::unique_ptr<Type, decltype(&closeFunction)> &&p) \ : LocalPointerBase<Type>(p.release()) {} \ ~LocalPointerClassName() { if (ptr != NULL) { closeFunction(ptr); } } \ LocalPointerClassName &operator=(LocalPointerClassName &&src) U_NOEXCEPT { \ if (ptr != NULL) { closeFunction(ptr); } \ LocalPointerBase<Type>::ptr=src.ptr; \ src.ptr=NULL; \ return *this; \ } \ /* TODO: Be agnostic of the deleter function signature from the user-provided std::unique_ptr? */ \ LocalPointerClassName &operator=(std::unique_ptr<Type, decltype(&closeFunction)> &&p) { \ adoptInstead(p.release()); \ 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) { \ if (ptr != NULL) { closeFunction(ptr); } \ ptr=p; \ } \ operator std::unique_ptr<Type, decltype(&closeFunction)> () && { \ return std::unique_ptr<Type, decltype(&closeFunction)>(LocalPointerBase<Type>::orphan(), closeFunction); \ } \ } U_NAMESPACE_END #endif /* U_SHOW_CPLUSPLUS_API */ #endif /* __LOCALPOINTER_H__ */