interface/wx/scopedptr.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/scopedptr.h
   3 // Purpose:     interface of wxScopedPtr
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxScopedPtr
  11
  12     This is a simple scoped smart pointer implementation that is similar to
  13     the Boost smart pointers (see http://www.boost.org) but rewritten
  14     to use macros instead.
  15
  16     Since wxWidgets 2.9.0 there is also a templated version of this class
  17     with the same name. See wxScopedPtr<T>.
  18
  19     A smart pointer holds a pointer to an object. The memory used by the object is
  20     deleted when the smart pointer goes out of scope. This class is different from
  21     the @c std::auto_ptr<> in so far as it doesn't provide copy constructor
  22     nor assignment operator. This limits what you can do with it but is much less
  23     surprising than the "destructive copy" behaviour of the standard class.
  24
  25     @b Example:
  26
  27     Below is an example of using a wxWidgets scoped smart pointer and pointer array.
  28
  29     @code
  30     class MyClass{ ... };
  31
  32     // declare a smart pointer to a MyClass called wxMyClassPtr
  33     wxDECLARE_SCOPED_PTR(MyClass, wxMyClassPtr)
  34     // declare a smart pointer to an array of chars
  35     wxDECLARE_SCOPED_ARRAY(char, wxCharArray)
  36
  37     ...
  38
  39     // define the first pointer class, must be complete
  40     wxDEFINE_SCOPED_PTR(MyClass, wxMyClassPtr)
  41     // define the second pointer class
  42     wxDEFINE_SCOPED_ARRAY(char, wxCharArray)
  43
  44     // create an object with a new pointer to MyClass
  45     wxMyClassPtr theObj(new MyClass());
  46     // reset the pointer (deletes the previous one)
  47     theObj.reset(new MyClass());
  48
  49     // access the pointer
  50     theObj->MyFunc();
  51
  52     // create an object with a new array of chars
  53     wxCharArray theCharObj(new char[100]);
  54
  55     // access the array
  56     theCharObj[0] = "!";
  57     @endcode
  58
  59     @section scopedptr_newpointers Declaring new smart pointer types
  60
  61     To declare the smart pointer class @c CLASSNAME containing pointes to
  62     a (possibly incomplete) type @c TYPE you should use
  63     @code
  64         wxDECLARE_SCOPED_PTR( TYPE,        // type of the values
  65                               CLASSNAME ); // name of the class
  66     @endcode
  67     And later, when @c TYPE is fully defined, you must also use
  68     @code
  69         wxDEFINE_SCOPED_PTR( TYPE, CLASSNAME );
  70     @endcode
  71     to implement the scoped pointer class.
  72
  73     The first argument of these macro is the pointer type, the second is the name
  74     of the new smart pointer class being created. Below we will use wxScopedPtr
  75     to represent the scoped pointer class, but the user may create the class with
  76     any legal name.
  77
  78     Alternatively, if you don't have to separate the point of declaration and
  79     definition of this class and if you accept the standard naming convention,
  80     that is that the scoped pointer for the class @c Foo is called @c FooPtr,
  81     you can use a single macro which replaces two macros above:
  82     @code
  83         wxDEFINE_SCOPED_PTR_TYPE( TYPE );
  84     @endcode
  85     Once again, in this cass @c CLASSNAME will be @c TYPEPtr.
  86
  87     @library{wxbase}
  88     @category{smartpointers}
  89
  90     @see wxScopedArray
  91 */
  92 class wxScopedPtr
  93 {
  94 public:
  95     /**
  96         Creates the smart pointer with the given pointer or none if @NULL.
  97
  98         On compilers that support it, this uses the explicit keyword.
  99     */
 100     explicit wxScopedPtr(type* T = NULL);
 101
 102     /**
 103         Destructor frees the pointer help by this object if it is not @NULL.
 104     */
 105     ~wxScopedPtr();
 106
 107     /**
 108         This operator gets the pointer stored in the smart pointer or returns
 109         @NULL if there is none.
 110     */
 111     const T* get();
 112
 113     /**
 114         This operator works like the standard C++ pointer operator to return the object
 115         being pointed to by the pointer.
 116
 117         @note
 118         If the pointer is @NULL or invalid this will crash.
 119     */
 120     const T& operator *();
 121
 122     /**
 123         This operator works like the standard C++ pointer operator to return the pointer
 124         in the smart pointer or @NULL if it is empty.
 125     */
 126     const T* operator ->();
 127
 128     /**
 129         Returns the currently hold pointer and resets the smart pointer object to
 130         @NULL.
 131
 132         @remarks
 133         After a call to this function the caller is responsible for deleting the
 134         pointer.
 135     */
 136     T* release();
 137
 138     /**
 139         Deletes the currently held pointer and sets it to @a p or to @NULL if no
 140         arguments are specified.
 141
 142         @note
 143         This function does check to make sure that the pointer you are assigning
 144         is not the same pointer that is already stored.
 145     */
 146     reset(T* p  = NULL);
 147
 148     /**
 149         Swap the pointer inside the smart pointer with @a other. The pointer being
 150         swapped must be of the same type (hence the same class name).
 151     */
 152     swap(wxScopedPtr& other);
 153 };
 154
 155 /**
 156     @class wxScopedTiedPtr
 157
 158     This is a variation on the topic of wxScopedPtr. This class is also a smart pointer
 159     but in addition it "ties" the pointer value to another variable. In other words,
 160     during the life time of this class the value of that variable is set to be the same
 161     as the value of the pointer itself and it is reset to its old value when the object
 162     is destroyed. This class is especially useful when converting the existing code
 163     (which may already store the pointers value in some variable) to the smart pointers.
 164
 165     @library{wxbase}
 166     @category{smartpointers}
 167 */
 168 class wxScopedTiedPtr : public wxScopedPtr
 169 {
 170 public:
 171     /**
 172         Constructor creates a smart pointer initialized with @a ptr and stores
 173         @a ptr in the location specified by @a ppTie which must not be @NULL.
 174     */
 175     wxScopedTiedPtr(T** ppTie, T* ptr);
 176
 177     /**
 178         Destructor frees the pointer help by this object and restores the value
 179         stored at the tied location (as specified in the @ref wxScopedTiedPtr() constructor)
 180         to the old value.
 181
 182         @warning
 183         This location may now contain an uninitialized value if it hadn't been
 184         initialized previously, in particular don't count on it magically being @NULL!
 185     */
 186     ~wxScopedTiedPtr();
 187 };
 188
 189
 190
 191 /**
 192     A scoped pointer template class.
 193
 194     It is the template version of the old-style @ref wxScopedPtr "scoped pointer macros".
 195
 196     Notice that objects of this class intentionally cannot be copied.
 197
 198     @library{wxbase}
 199     @category{smartpointers}
 200
 201     @see wxSharedPtr<T>, wxWeakRef<T>
 202 */
 203 template<typename T>
 204 class wxScopedPtr<T>
 205 {
 206 public:
 207     /**
 208         Constructor takes ownership of the pointer.
 209
 210         @param ptr
 211             Pointer allocated with @c new or @NULL.
 212     */
 213     wxScopedPtr(T* ptr = NULL);
 214
 215     /**
 216         Destructor deletes the pointer.
 217     */
 218     ~wxScopedPtr();
 219
 220     /**
 221         Returns pointer to object or @NULL.
 222     */
 223     T* get() const;
 224
 225     /**
 226         Conversion to a boolean expression (in a variant which is not
 227         convertible to anything but a boolean expression).
 228
 229         If this class contains a valid pointer it will return @true, if it contains
 230         a @NULL pointer it will return @false.
 231     */
 232     operator unspecified_bool_type() const;
 233
 234     /**
 235         Returns a reference to the object.
 236
 237         @note
 238         If the internal pointer is @NULL this method will cause an assert
 239         in debug mode.
 240     */
 241     T operator*() const;
 242
 243     /**
 244         Returns pointer to object. If the pointer is @NULL this method will
 245         cause an assert in debug mode.
 246     */
 247     T* operator->() const;
 248
 249     /**
 250         Releases the current pointer and returns it.
 251
 252         @remarks
 253         Afterwards the caller is responsible for deleting
 254         the data contained in the scoped pointer before.
 255     */
 256     T* release();
 257
 258     /**
 259         Reset pointer to the value of @a ptr.
 260         The previous pointer will be deleted.
 261     */
 262     void reset(T* ptr = NULL);
 263
 264     /**
 265         Swaps pointers.
 266     */
 267     void swap(wxScopedPtr<T>& ot);
 268 };
 269