interface/wx/scopedptr.h

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