tor-browser

localpointer.h (19985B)

---

// © 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 https://icu.unicode.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;
   static void* U_EXPORT2 operator new(size_t, void*) = delete;

   /**
    * Constructor takes ownership.
    * @param p simple pointer to an object that is adopted
    * @stable ICU 4.4
    */
   explicit LocalPointerBase(T *p=nullptr) : ptr(p) {}
   /**
    * Destructor deletes the object it owns.
    * Subclass must override: Base class does nothing.
    * @stable ICU 4.4
    */
   ~LocalPointerBase() { /* delete ptr; */ }
   /**
    * nullptr check.
    * @return true if ==nullptr
    * @stable ICU 4.4
    */
   UBool isNull() const { return ptr==nullptr; }
   /**
    * nullptr check.
    * @return true if !=nullptr
    * @stable ICU 4.4
    */
   UBool isValid() const { return ptr!=nullptr; }
   /**
    * Comparison with a simple pointer, so that existing code
    * with ==nullptr 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 !=nullptr 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 nullptr.
    * @return the pointer value;
    *         caller becomes responsible for deleting the object
    * @stable ICU 4.4
    */
   T *orphan() {
       T *p=ptr;
       ptr=nullptr;
       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) = delete;
   bool operator!=(const LocalPointerBase<T> &other) = delete;
   // No ownership sharing: No copy constructor, no assignment operator.
   LocalPointerBase(const LocalPointerBase<T> &other) = delete;
   void operator=(const LocalPointerBase<T> &other) = delete;
};

/**
* "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=nullptr) : LocalPointerBase<T>(p) {}
   /**
    * Constructor takes ownership and reports an error if nullptr.
    *
    * 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==nullptr and no other failure code had been set
    * @stable ICU 55
    */
   LocalPointer(T *p, UErrorCode &errorCode) : LocalPointerBase<T>(p) {
       if(p==nullptr && 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) noexcept : LocalPointerBase<T>(src.ptr) {
       src.ptr=nullptr;
   }

   /**
    * 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) noexcept {
       delete LocalPointerBase<T>::ptr;
       LocalPointerBase<T>::ptr=src.ptr;
       src.ptr=nullptr;
       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) noexcept {
       adoptInstead(p.release());
       return *this;
   }

   /**
    * Swap pointers.
    * @param other other smart pointer
    * @stable ICU 56
    */
   void swap(LocalPointer<T> &other) 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) 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 nullptr,
    * then U_MEMORY_ALLOCATION_ERROR is set,
    * the current object is deleted, and nullptr 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==nullptr 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==nullptr) {
               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=nullptr) : LocalPointerBase<T>(p) {}
   /**
    * Constructor takes ownership and reports an error if nullptr.
    *
    * 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==nullptr and no other failure code had been set
    * @stable ICU 56
    */
   LocalArray(T *p, UErrorCode &errorCode) : LocalPointerBase<T>(p) {
       if(p==nullptr && 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) noexcept : LocalPointerBase<T>(src.ptr) {
       src.ptr=nullptr;
   }

   /**
    * 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) noexcept {
       delete[] LocalPointerBase<T>::ptr;
       LocalPointerBase<T>::ptr=src.ptr;
       src.ptr=nullptr;
       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) noexcept {
       adoptInstead(p.release());
       return *this;
   }

   /**
    * Swap pointers.
    * @param other other smart pointer
    * @stable ICU 56
    */
   void swap(LocalArray<T> &other) 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) 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 nullptr,
    * then U_MEMORY_ALLOCATION_ERROR is set,
    * the current array is deleted, and nullptr 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==nullptr 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==nullptr) {
               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) \
   using LocalPointerClassName = internal::LocalOpenPointer<Type, closeFunction>

#ifndef U_IN_DOXYGEN
namespace internal {
/**
* Implementation, do not use directly: use U_DEFINE_LOCAL_OPEN_POINTER.
*
* @see U_DEFINE_LOCAL_OPEN_POINTER
* @internal
*/
template <typename Type, auto closeFunction>
class LocalOpenPointer : public LocalPointerBase<Type> {
   using LocalPointerBase<Type>::ptr;
public:
   using LocalPointerBase<Type>::operator*;
   using LocalPointerBase<Type>::operator->;
   explicit LocalOpenPointer(Type *p=nullptr) : LocalPointerBase<Type>(p) {}
   LocalOpenPointer(LocalOpenPointer &&src) noexcept
           : LocalPointerBase<Type>(src.ptr) {
       src.ptr=nullptr;
   }
   /* TODO: Be agnostic of the deleter function signature from the user-provided std::unique_ptr? */
   explicit LocalOpenPointer(std::unique_ptr<Type, decltype(closeFunction)> &&p)
           : LocalPointerBase<Type>(p.release()) {}
   ~LocalOpenPointer() { if (ptr != nullptr) { closeFunction(ptr); } }
   LocalOpenPointer &operator=(LocalOpenPointer &&src) noexcept {
       if (ptr != nullptr) { closeFunction(ptr); }
       LocalPointerBase<Type>::ptr=src.ptr;
       src.ptr=nullptr;
       return *this;
   }
   /* TODO: Be agnostic of the deleter function signature from the user-provided std::unique_ptr? */
   LocalOpenPointer &operator=(std::unique_ptr<Type, decltype(closeFunction)> &&p) {
       adoptInstead(p.release());
       return *this;
   }
   void swap(LocalOpenPointer &other) noexcept {
       Type *temp=LocalPointerBase<Type>::ptr;
       LocalPointerBase<Type>::ptr=other.ptr;
       other.ptr=temp;
   }
   friend inline void swap(LocalOpenPointer &p1, LocalOpenPointer &p2) noexcept {
       p1.swap(p2);
   }
   void adoptInstead(Type *p) {
       if (ptr != nullptr) { closeFunction(ptr); }
       ptr=p;
   }
   operator std::unique_ptr<Type, decltype(closeFunction)> () && {
       return std::unique_ptr<Type, decltype(closeFunction)>(LocalPointerBase<Type>::orphan(), closeFunction);
   }
};
}  // namespace internal
#endif

U_NAMESPACE_END

#endif  /* U_SHOW_CPLUSPLUS_API */
#endif  /* __LOCALPOINTER_H__ */