// © 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 { … }; /** * "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> { … }; /** * "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> { … }; /** * \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) … #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> { … }; } // namespace internal #endif U_NAMESPACE_END #endif /* U_SHOW_CPLUSPLUS_API */ #endif /* __LOCALPOINTER_H__ */