text: /*
  *******************************************************************************
  *
  *   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__ */
  