initial commit, 4.5 stable

thirdparty/icu4c/common/unicode/localpointer.h

@@ -0,0 +1,609 @@
+// © 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;
+#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=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__ */