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
43U_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 */
63template<typename T>
64class LocalPointerBase {
65public:
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    }
146protected:
147    T *ptr;
148private:
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 */
181template<typename T>
182class LocalPointer : public LocalPointerBase<T> {
183public:
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 */
227template<typename T>
228class LocalArray : public LocalPointerBase<T> {
229public:
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
297U_NAMESPACE_END
298
299#endif  /* U_SHOW_CPLUSPLUS_API */
300#endif  /* __LOCALPOINTER_H__ */
301