1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/intl/icu/source/common/unicode/localpointer.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,304 @@
1.4 +/*
1.5 +*******************************************************************************
1.6 +*
1.7 +* Copyright (C) 2009-2012, International Business Machines
1.8 +* Corporation and others. All Rights Reserved.
1.9 +*
1.10 +*******************************************************************************
1.11 +* file name: localpointer.h
1.12 +* encoding: US-ASCII
1.13 +* tab size: 8 (not used)
1.14 +* indentation:4
1.15 +*
1.16 +* created on: 2009nov13
1.17 +* created by: Markus W. Scherer
1.18 +*/
1.19 +
1.20 +#ifndef __LOCALPOINTER_H__
1.21 +#define __LOCALPOINTER_H__
1.22 +
1.23 +/**
1.24 + * \file
1.25 + * \brief C++ API: "Smart pointers" for use with and in ICU4C C++ code.
1.26 + *
1.27 + * These classes are inspired by
1.28 + * - std::auto_ptr
1.29 + * - boost::scoped_ptr & boost::scoped_array
1.30 + * - Taligent Safe Pointers (TOnlyPointerTo)
1.31 + *
1.32 + * but none of those provide for all of the goals for ICU smart pointers:
1.33 + * - Smart pointer owns the object and releases it when it goes out of scope.
1.34 + * - No transfer of ownership via copy/assignment to reduce misuse. Simpler & more robust.
1.35 + * - ICU-compatible: No exceptions.
1.36 + * - Need to be able to orphan/release the pointer and its ownership.
1.37 + * - Need variants for normal C++ object pointers, C++ arrays, and ICU C service objects.
1.38 + *
1.39 + * For details see http://site.icu-project.org/design/cpp/scoped_ptr
1.40 + */
1.41 +
1.42 +#include "unicode/utypes.h"
1.43 +
1.44 +#if U_SHOW_CPLUSPLUS_API
1.45 +
1.46 +U_NAMESPACE_BEGIN
1.47 +
1.48 +/**
1.49 + * "Smart pointer" base class; do not use directly: use LocalPointer etc.
1.50 + *
1.51 + * Base class for smart pointer classes that do not throw exceptions.
1.52 + *
1.53 + * Do not use this base class directly, since it does not delete its pointer.
1.54 + * A subclass must implement methods that delete the pointer:
1.55 + * Destructor and adoptInstead().
1.56 + *
1.57 + * There is no operator T *() provided because the programmer must decide
1.58 + * whether to use getAlias() (without transfer of ownership) or orpan()
1.59 + * (with transfer of ownership and NULLing of the pointer).
1.60 + *
1.61 + * @see LocalPointer
1.62 + * @see LocalArray
1.63 + * @see U_DEFINE_LOCAL_OPEN_POINTER
1.64 + * @stable ICU 4.4
1.65 + */
1.66 +template<typename T>
1.67 +class LocalPointerBase {
1.68 +public:
1.69 + /**
1.70 + * Constructor takes ownership.
1.71 + * @param p simple pointer to an object that is adopted
1.72 + * @stable ICU 4.4
1.73 + */
1.74 + explicit LocalPointerBase(T *p=NULL) : ptr(p) {}
1.75 + /**
1.76 + * Destructor deletes the object it owns.
1.77 + * Subclass must override: Base class does nothing.
1.78 + * @stable ICU 4.4
1.79 + */
1.80 + ~LocalPointerBase() { /* delete ptr; */ }
1.81 + /**
1.82 + * NULL check.
1.83 + * @return TRUE if ==NULL
1.84 + * @stable ICU 4.4
1.85 + */
1.86 + UBool isNull() const { return ptr==NULL; }
1.87 + /**
1.88 + * NULL check.
1.89 + * @return TRUE if !=NULL
1.90 + * @stable ICU 4.4
1.91 + */
1.92 + UBool isValid() const { return ptr!=NULL; }
1.93 + /**
1.94 + * Comparison with a simple pointer, so that existing code
1.95 + * with ==NULL need not be changed.
1.96 + * @param other simple pointer for comparison
1.97 + * @return true if this pointer value equals other
1.98 + * @stable ICU 4.4
1.99 + */
1.100 + bool operator==(const T *other) const { return ptr==other; }
1.101 + /**
1.102 + * Comparison with a simple pointer, so that existing code
1.103 + * with !=NULL need not be changed.
1.104 + * @param other simple pointer for comparison
1.105 + * @return true if this pointer value differs from other
1.106 + * @stable ICU 4.4
1.107 + */
1.108 + bool operator!=(const T *other) const { return ptr!=other; }
1.109 + /**
1.110 + * Access without ownership change.
1.111 + * @return the pointer value
1.112 + * @stable ICU 4.4
1.113 + */
1.114 + T *getAlias() const { return ptr; }
1.115 + /**
1.116 + * Access without ownership change.
1.117 + * @return the pointer value as a reference
1.118 + * @stable ICU 4.4
1.119 + */
1.120 + T &operator*() const { return *ptr; }
1.121 + /**
1.122 + * Access without ownership change.
1.123 + * @return the pointer value
1.124 + * @stable ICU 4.4
1.125 + */
1.126 + T *operator->() const { return ptr; }
1.127 + /**
1.128 + * Gives up ownership; the internal pointer becomes NULL.
1.129 + * @return the pointer value;
1.130 + * caller becomes responsible for deleting the object
1.131 + * @stable ICU 4.4
1.132 + */
1.133 + T *orphan() {
1.134 + T *p=ptr;
1.135 + ptr=NULL;
1.136 + return p;
1.137 + }
1.138 + /**
1.139 + * Deletes the object it owns,
1.140 + * and adopts (takes ownership of) the one passed in.
1.141 + * Subclass must override: Base class does not delete the object.
1.142 + * @param p simple pointer to an object that is adopted
1.143 + * @stable ICU 4.4
1.144 + */
1.145 + void adoptInstead(T *p) {
1.146 + // delete ptr;
1.147 + ptr=p;
1.148 + }
1.149 +protected:
1.150 + /**
1.151 + * Actual pointer.
1.152 + * @internal
1.153 + */
1.154 + T *ptr;
1.155 +private:
1.156 + // No comparison operators with other LocalPointerBases.
1.157 + bool operator==(const LocalPointerBase &other);
1.158 + bool operator!=(const LocalPointerBase &other);
1.159 + // No ownership transfer: No copy constructor, no assignment operator.
1.160 + LocalPointerBase(const LocalPointerBase &other);
1.161 + void operator=(const LocalPointerBase &other);
1.162 + // No heap allocation. Use only on the stack.
1.163 + static void * U_EXPORT2 operator new(size_t size);
1.164 + static void * U_EXPORT2 operator new[](size_t size);
1.165 +#if U_HAVE_PLACEMENT_NEW
1.166 + static void * U_EXPORT2 operator new(size_t, void *ptr);
1.167 +#endif
1.168 +};
1.169 +
1.170 +/**
1.171 + * "Smart pointer" class, deletes objects via the standard C++ delete operator.
1.172 + * For most methods see the LocalPointerBase base class.
1.173 + *
1.174 + * Usage example:
1.175 + * \code
1.176 + * LocalPointer<UnicodeString> s(new UnicodeString((UChar32)0x50005));
1.177 + * int32_t length=s->length(); // 2
1.178 + * UChar lead=s->charAt(0); // 0xd900
1.179 + * if(some condition) { return; } // no need to explicitly delete the pointer
1.180 + * s.adoptInstead(new UnicodeString((UChar)0xfffc));
1.181 + * length=s->length(); // 1
1.182 + * // no need to explicitly delete the pointer
1.183 + * \endcode
1.184 + *
1.185 + * @see LocalPointerBase
1.186 + * @stable ICU 4.4
1.187 + */
1.188 +template<typename T>
1.189 +class LocalPointer : public LocalPointerBase<T> {
1.190 +public:
1.191 + /**
1.192 + * Constructor takes ownership.
1.193 + * @param p simple pointer to an object that is adopted
1.194 + * @stable ICU 4.4
1.195 + */
1.196 + explicit LocalPointer(T *p=NULL) : LocalPointerBase<T>(p) {}
1.197 + /**
1.198 + * Destructor deletes the object it owns.
1.199 + * @stable ICU 4.4
1.200 + */
1.201 + ~LocalPointer() {
1.202 + delete LocalPointerBase<T>::ptr;
1.203 + }
1.204 + /**
1.205 + * Deletes the object it owns,
1.206 + * and adopts (takes ownership of) the one passed in.
1.207 + * @param p simple pointer to an object that is adopted
1.208 + * @stable ICU 4.4
1.209 + */
1.210 + void adoptInstead(T *p) {
1.211 + delete LocalPointerBase<T>::ptr;
1.212 + LocalPointerBase<T>::ptr=p;
1.213 + }
1.214 +};
1.215 +
1.216 +/**
1.217 + * "Smart pointer" class, deletes objects via the C++ array delete[] operator.
1.218 + * For most methods see the LocalPointerBase base class.
1.219 + * Adds operator[] for array item access.
1.220 + *
1.221 + * Usage example:
1.222 + * \code
1.223 + * LocalArray<UnicodeString> a(new UnicodeString[2]);
1.224 + * a[0].append((UChar)0x61);
1.225 + * if(some condition) { return; } // no need to explicitly delete the array
1.226 + * a.adoptInstead(new UnicodeString[4]);
1.227 + * a[3].append((UChar)0x62).append((UChar)0x63).reverse();
1.228 + * // no need to explicitly delete the array
1.229 + * \endcode
1.230 + *
1.231 + * @see LocalPointerBase
1.232 + * @stable ICU 4.4
1.233 + */
1.234 +template<typename T>
1.235 +class LocalArray : public LocalPointerBase<T> {
1.236 +public:
1.237 + /**
1.238 + * Constructor takes ownership.
1.239 + * @param p simple pointer to an array of T objects that is adopted
1.240 + * @stable ICU 4.4
1.241 + */
1.242 + explicit LocalArray(T *p=NULL) : LocalPointerBase<T>(p) {}
1.243 + /**
1.244 + * Destructor deletes the array it owns.
1.245 + * @stable ICU 4.4
1.246 + */
1.247 + ~LocalArray() {
1.248 + delete[] LocalPointerBase<T>::ptr;
1.249 + }
1.250 + /**
1.251 + * Deletes the array it owns,
1.252 + * and adopts (takes ownership of) the one passed in.
1.253 + * @param p simple pointer to an array of T objects that is adopted
1.254 + * @stable ICU 4.4
1.255 + */
1.256 + void adoptInstead(T *p) {
1.257 + delete[] LocalPointerBase<T>::ptr;
1.258 + LocalPointerBase<T>::ptr=p;
1.259 + }
1.260 + /**
1.261 + * Array item access (writable).
1.262 + * No index bounds check.
1.263 + * @param i array index
1.264 + * @return reference to the array item
1.265 + * @stable ICU 4.4
1.266 + */
1.267 + T &operator[](ptrdiff_t i) const { return LocalPointerBase<T>::ptr[i]; }
1.268 +};
1.269 +
1.270 +/**
1.271 + * \def U_DEFINE_LOCAL_OPEN_POINTER
1.272 + * "Smart pointer" definition macro, deletes objects via the closeFunction.
1.273 + * Defines a subclass of LocalPointerBase which works just
1.274 + * like LocalPointer<Type> except that this subclass will use the closeFunction
1.275 + * rather than the C++ delete operator.
1.276 + *
1.277 + * Requirement: The closeFunction must tolerate a NULL pointer.
1.278 + * (We could add a NULL check here but it is normally redundant.)
1.279 + *
1.280 + * Usage example:
1.281 + * \code
1.282 + * LocalUCaseMapPointer csm(ucasemap_open(localeID, options, &errorCode));
1.283 + * utf8OutLength=ucasemap_utf8ToLower(csm.getAlias(),
1.284 + * utf8Out, (int32_t)sizeof(utf8Out),
1.285 + * utf8In, utf8InLength, &errorCode);
1.286 + * if(U_FAILURE(errorCode)) { return; } // no need to explicitly delete the UCaseMap
1.287 + * \endcode
1.288 + *
1.289 + * @see LocalPointerBase
1.290 + * @see LocalPointer
1.291 + * @stable ICU 4.4
1.292 + */
1.293 +#define U_DEFINE_LOCAL_OPEN_POINTER(LocalPointerClassName, Type, closeFunction) \
1.294 + class LocalPointerClassName : public LocalPointerBase<Type> { \
1.295 + public: \
1.296 + explicit LocalPointerClassName(Type *p=NULL) : LocalPointerBase<Type>(p) {} \
1.297 + ~LocalPointerClassName() { closeFunction(ptr); } \
1.298 + void adoptInstead(Type *p) { \
1.299 + closeFunction(ptr); \
1.300 + ptr=p; \
1.301 + } \
1.302 + }
1.303 +
1.304 +U_NAMESPACE_END
1.305 +
1.306 +#endif /* U_SHOW_CPLUSPLUS_API */
1.307 +#endif /* __LOCALPOINTER_H__ */
