1 /* 2 ******************************************************************************* 3 * 4 * Copyright (C) 2009-2010, International Business Machines 5 * Corporation and others. All Rights Reserved. 6 * 7 ******************************************************************************* 8 * file name: localpointer.h 9 * encoding: US-ASCII 10 * tab size: 8 (not used) 11 * indentation:4 12 * 13 * created on: 2009nov13 14 * created by: Markus W. Scherer 15 */ 16 17 #ifndef __LOCALPOINTER_H__ 18 #define __LOCALPOINTER_H__ 19 20 /** 21 * \file 22 * \brief C++ API: "Smart pointers" for use with and in ICU4C C++ code. 23 * 24 * These classes are inspired by 25 * - std::auto_ptr 26 * - boost::scoped_ptr & boost::scoped_array 27 * - Taligent Safe Pointers (TOnlyPointerTo) 28 * 29 * but none of those provide for all of the goals for ICU smart pointers: 30 * - Smart pointer owns the object and releases it when it goes out of scope. 31 * - No transfer of ownership via copy/assignment to reduce misuse. Simpler & more robust. 32 * - ICU-compatible: No exceptions. 33 * - Need to be able to orphan/release the pointer and its ownership. 34 * - Need variants for normal C++ object pointers, C++ arrays, and ICU C service objects. 35 * 36 * For details see http://site.icu-project.org/design/cpp/scoped_ptr 37 */ 38 39 #include "unicode/utypes.h" 40 41 #if U_SHOW_CPLUSPLUS_API 42 43 U_NAMESPACE_BEGIN 44 45 /** 46 * "Smart pointer" base class; do not use directly: use LocalPointer etc. 47 * 48 * Base class for smart pointer classes that do not throw exceptions. 49 * 50 * Do not use this base class directly, since it does not delete its pointer. 51 * A subclass must implement methods that delete the pointer: 52 * Destructor and adoptInstead(). 53 * 54 * There is no operator T *() provided because the programmer must decide 55 * whether to use getAlias() (without transfer of ownership) or orpan() 56 * (with transfer of ownership and NULLing of the pointer). 57 * 58 * @see LocalPointer 59 * @see LocalArray 60 * @see U_DEFINE_LOCAL_OPEN_POINTER 61 * @stable ICU 4.4 62 */ 63 template<typename T> 64 class LocalPointerBase { 65 public: 66 /** 67 * Constructor takes ownership. 68 * @param p simple pointer to an object that is adopted 69 * @stable ICU 4.4 70 */ 71 explicit LocalPointerBase(T *p=NULL) : ptr(p) {} 72 /** 73 * Destructor deletes the object it owns. 74 * Subclass must override: Base class does nothing. 75 * @stable ICU 4.4 76 */ 77 ~LocalPointerBase() { /* delete ptr; */ } 78 /** 79 * NULL check. 80 * @return TRUE if ==NULL 81 * @stable ICU 4.4 82 */ 83 UBool isNull() const { return ptr==NULL; } 84 /** 85 * NULL check. 86 * @return TRUE if !=NULL 87 * @stable ICU 4.4 88 */ 89 UBool isValid() const { return ptr!=NULL; } 90 /** 91 * Comparison with a simple pointer, so that existing code 92 * with ==NULL need not be changed. 93 * @param other simple pointer for comparison 94 * @return true if this pointer value equals other 95 * @stable ICU 4.4 96 */ 97 bool operator==(const T *other) const { return ptr==other; } 98 /** 99 * Comparison with a simple pointer, so that existing code 100 * with !=NULL need not be changed. 101 * @param other simple pointer for comparison 102 * @return true if this pointer value differs from other 103 * @stable ICU 4.4 104 */ 105 bool operator!=(const T *other) const { return ptr!=other; } 106 /** 107 * Access without ownership change. 108 * @return the pointer value 109 * @stable ICU 4.4 110 */ 111 T *getAlias() const { return ptr; } 112 /** 113 * Access without ownership change. 114 * @return the pointer value as a reference 115 * @stable ICU 4.4 116 */ 117 T &operator*() const { return *ptr; } 118 /** 119 * Access without ownership change. 120 * @return the pointer value 121 * @stable ICU 4.4 122 */ 123 T *operator->() const { return ptr; } 124 /** 125 * Gives up ownership; the internal pointer becomes NULL. 126 * @return the pointer value; 127 * caller becomes responsible for deleting the object 128 * @stable ICU 4.4 129 */ 130 T *orphan() { 131 T *p=ptr; 132 ptr=NULL; 133 return p; 134 } 135 /** 136 * Deletes the object it owns, 137 * and adopts (takes ownership of) the one passed in. 138 * Subclass must override: Base class does not delete the object. 139 * @param p simple pointer to an object that is adopted 140 * @stable ICU 4.4 141 */ 142 void adoptInstead(T *p) { 143 // delete ptr; 144 ptr=p; 145 } 146 protected: 147 T *ptr; 148 private: 149 // No comparison operators with other LocalPointerBases. 150 bool operator==(const LocalPointerBase &other); 151 bool operator!=(const LocalPointerBase &other); 152 // No ownership transfer: No copy constructor, no assignment operator. 153 LocalPointerBase(const LocalPointerBase &other); 154 void operator=(const LocalPointerBase &other); 155 // No heap allocation. Use only on the stack. 156 static void * U_EXPORT2 operator new(size_t size); 157 static void * U_EXPORT2 operator new[](size_t size); 158 #if U_HAVE_PLACEMENT_NEW 159 static void * U_EXPORT2 operator new(size_t, void *ptr); 160 #endif 161 }; 162 163 /** 164 * "Smart pointer" class, deletes objects via the standard C++ delete operator. 165 * For most methods see the LocalPointerBase base class. 166 * 167 * Usage example: 168 * \code 169 * LocalPointer<UnicodeString> s(new UnicodeString((UChar32)0x50005)); 170 * int32_t length=s->length(); // 2 171 * UChar lead=s->charAt(0); // 0xd900 172 * if(some condition) { return; } // no need to explicitly delete the pointer 173 * s.adoptInstead(new UnicodeString((UChar)0xfffc)); 174 * length=s->length(); // 1 175 * // no need to explicitly delete the pointer 176 * \endcode 177 * 178 * @see LocalPointerBase 179 * @stable ICU 4.4 180 */ 181 template<typename T> 182 class LocalPointer : public LocalPointerBase<T> { 183 public: 184 /** 185 * Constructor takes ownership. 186 * @param p simple pointer to an object that is adopted 187 * @stable ICU 4.4 188 */ 189 explicit LocalPointer(T *p=NULL) : LocalPointerBase<T>(p) {} 190 /** 191 * Destructor deletes the object it owns. 192 * @stable ICU 4.4 193 */ 194 ~LocalPointer() { 195 delete LocalPointerBase<T>::ptr; 196 } 197 /** 198 * Deletes the object it owns, 199 * and adopts (takes ownership of) the one passed in. 200 * @param p simple pointer to an object that is adopted 201 * @stable ICU 4.4 202 */ 203 void adoptInstead(T *p) { 204 delete LocalPointerBase<T>::ptr; 205 LocalPointerBase<T>::ptr=p; 206 } 207 }; 208 209 /** 210 * "Smart pointer" class, deletes objects via the C++ array delete[] operator. 211 * For most methods see the LocalPointerBase base class. 212 * Adds operator[] for array item access. 213 * 214 * Usage example: 215 * \code 216 * LocalArray<UnicodeString> a(new UnicodeString[2]); 217 * a[0].append((UChar)0x61); 218 * if(some condition) { return; } // no need to explicitly delete the array 219 * a.adoptInstead(new UnicodeString[4]); 220 * a[3].append((UChar)0x62).append((UChar)0x63).reverse(); 221 * // no need to explicitly delete the array 222 * \endcode 223 * 224 * @see LocalPointerBase 225 * @stable ICU 4.4 226 */ 227 template<typename T> 228 class LocalArray : public LocalPointerBase<T> { 229 public: 230 /** 231 * Constructor takes ownership. 232 * @param p simple pointer to an array of T objects that is adopted 233 * @stable ICU 4.4 234 */ 235 explicit LocalArray(T *p=NULL) : LocalPointerBase<T>(p) {} 236 /** 237 * Destructor deletes the array it owns. 238 * @stable ICU 4.4 239 */ 240 ~LocalArray() { 241 delete[] LocalPointerBase<T>::ptr; 242 } 243 /** 244 * Deletes the array it owns, 245 * and adopts (takes ownership of) the one passed in. 246 * @param p simple pointer to an array of T objects that is adopted 247 * @stable ICU 4.4 248 */ 249 void adoptInstead(T *p) { 250 delete[] LocalPointerBase<T>::ptr; 251 LocalPointerBase<T>::ptr=p; 252 } 253 /** 254 * Array item access (writable). 255 * No index bounds check. 256 * @param i array index 257 * @return reference to the array item 258 * @stable ICU 4.4 259 */ 260 T &operator[](ptrdiff_t i) const { return LocalPointerBase<T>::ptr[i]; } 261 }; 262 263 /** 264 * \def U_DEFINE_LOCAL_OPEN_POINTER 265 * "Smart pointer" definition macro, deletes objects via the closeFunction. 266 * Defines a subclass of LocalPointerBase which works just 267 * like LocalPointer<Type> except that this subclass will use the closeFunction 268 * rather than the C++ delete operator. 269 * 270 * Requirement: The closeFunction must tolerate a NULL pointer. 271 * (We could add a NULL check here but it is normally redundant.) 272 * 273 * Usage example: 274 * \code 275 * LocalUCaseMapPointer csm(ucasemap_open(localeID, options, &errorCode)); 276 * utf8OutLength=ucasemap_utf8ToLower(csm.getAlias(), 277 * utf8Out, (int32_t)sizeof(utf8Out), 278 * utf8In, utf8InLength, &errorCode); 279 * if(U_FAILURE(errorCode)) { return; } // no need to explicitly delete the UCaseMap 280 * \endcode 281 * 282 * @see LocalPointerBase 283 * @see LocalPointer 284 * @stable ICU 4.4 285 */ 286 #define U_DEFINE_LOCAL_OPEN_POINTER(LocalPointerClassName, Type, closeFunction) \ 287 class LocalPointerClassName : public LocalPointerBase<Type> { \ 288 public: \ 289 explicit LocalPointerClassName(Type *p=NULL) : LocalPointerBase<Type>(p) {} \ 290 ~LocalPointerClassName() { closeFunction(ptr); } \ 291 void adoptInstead(Type *p) { \ 292 closeFunction(ptr); \ 293 ptr=p; \ 294 } \ 295 } 296 297 U_NAMESPACE_END 298 299 #endif /* U_SHOW_CPLUSPLUS_API */ 300 #endif /* __LOCALPOINTER_H__ */ 301
