interface/wx/ptr_scpd.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        ptr_scpd.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     surprizing 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 wxscopedptr_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
 157 /**
 158     @class wxScopedArray
 159
 160     This is a simple scoped smart pointer array implementation that is similar to
 161     the Boost smart pointers (see http://www.boost.org/) but rewritten to
 162     use macros instead.
 163
 164     @b Example:
 165
 166     Below is an example of using a wxWidgets scoped smart pointer and pointer array.
 167
 168     @code
 169     class MyClass { ... };
 170
 171     // declare a smart pointer to a MyClass called wxMyClassPtr
 172     wxDECLARE_SCOPED_PTR(MyClass, wxMyClassPtr)
 173     // declare a smart pointer to an array of chars
 174     wxDECLARE_SCOPED_ARRAY(char, wxCharArray)
 175
 176     ...
 177
 178     // define the first pointer class, must be complete
 179     wxDEFINE_SCOPED_PTR(MyClass, wxMyClassPtr)
 180     // define the second pointer class
 181     wxDEFINE_SCOPED_ARRAY(char, wxCharArray)
 182
 183     // create an object with a new pointer to MyClass
 184     wxMyClassPtr theObj(new MyClass());
 185     // reset the pointer (deletes the previous one)
 186     theObj.reset(new MyClass());
 187
 188     // access the pointer
 189     theObj->MyFunc();
 190
 191     // create an object with a new array of chars
 192     wxCharArray theCharObj(new char[100]);
 193
 194     // access the array
 195     theCharObj[0] = "!";
 196     @endcode
 197
 198     <b>Declaring new smart pointer types:</b>
 199     @code
 200     wxDECLAR_SCOPED_ARRAY( TYPE,        // type of the values
 201                            CLASSNAME ); // name of the class
 202     @endcode
 203
 204     A smart pointer holds a pointer to an object (which must be complete when
 205     wxDEFINE_SCOPED_ARRAY() is called).
 206
 207     The memory used by the object is deleted when the smart pointer goes out of
 208     scope. The first argument of the macro is the pointer type, the second is the
 209     name of the new smart pointer class being created. Below we will use wxScopedArray
 210     to represent the scoped pointer array class, but the user may create the class with
 211     any legal name.
 212
 213     @library{wxbase}
 214     @category{smartpointers}
 215
 216     @see wxScopedPtr
 217 */
 218 class wxScopedArray
 219 {
 220 public:
 221     /**
 222         Creates the smart pointer with the given pointer or none if @NULL.  On
 223         compilers that support it, this uses the explicit keyword.
 224     */
 225     wxScopedArray(type*  T = NULL);
 226
 227     /**
 228         This operator gets the pointer stored in the smart pointer or returns @NULL if
 229         there is none.
 230     */
 231     const T* get();
 232
 233     /**
 234         This operator acts like the standard [] indexing operator for C++ arrays.  The
 235         function does not do bounds checking.
 236     */
 237     const T& operator [](long int i);
 238
 239     /**
 240         Deletes the currently held pointer and sets it to 'p' or to @NULL if no
 241         arguments are specified. This function does check to make sure that the
 242         pointer you are assigning is not the same pointer that is already stored.
 243     */
 244     reset(T* p  = NULL);
 245
 246     /**
 247         Swap the pointer inside the smart pointer with @a ot. The pointer being swapped
 248         must be of the same type (hence the same class name).
 249     */
 250     swap(wxScopedPtr& ot);
 251 };
 252
 253
 254
 255 /**
 256     @class wxScopedTiedPtr
 257
 258     This is a variation on the topic of wxScopedPtr. This class is also a smart pointer
 259     but in addition it "ties" the pointer value to another variable. In other words,
 260     during the life time of this class the value of that variable is set to be the same
 261     as the value of the pointer itself and it is reset to its old value when the object
 262     is destroyed. This class is especially useful when converting the existing code
 263     (which may already store the pointers value in some variable) to the smart pointers.
 264
 265     @library{wxbase}
 266     @category{smartpointers}
 267 */
 268 class wxScopedTiedPtr : public wxScopedPtr
 269 {
 270 public:
 271     /**
 272         Constructor creates a smart pointer initialized with @a ptr and stores
 273         @a ptr in the location specified by @a ppTie which must not be @NULL.
 274     */
 275     wxScopedTiedPtr(T** ppTie, T* ptr);
 276
 277     /**
 278         Destructor frees the pointer help by this object and restores the value
 279         stored at the tied location (as specified in the @ref wxScopedTiedPtr() constructor)
 280         to the old value.
 281
 282         @warning
 283         This location may now contain an uninitialized value if it hadn't been
 284         initialized previously, in particular don't count on it magically being @NULL!
 285     */
 286     ~wxScopedTiedPtr();
 287 };
 288
 289
 290
 291 /**
 292
 293     A scoped pointer template class.
 294     It is the template version of the old-style @ref wxScopedPtr "scoped pointer macros".
 295
 296     @library{wxbase}
 297     @category{smartpointers}
 298
 299     @see wxSharedPtr<T>, wxWeakRef<T>
 300 */
 301 template<typename T>
 302 class wxScopedPtr<T>
 303 {
 304 public:
 305     /**
 306         Constructor.
 307     */
 308     wxScopedPtr(T* ptr = NULL);
 309
 310     /**
 311         Destructor.
 312     */
 313     ~wxScopedPtr();
 314
 315     /**
 316         Returns pointer to object or @NULL.
 317     */
 318     T* get() const;
 319
 320     /**
 321         Conversion to a boolean expression (in a variant which is not
 322         convertable to anything but a boolean expression).
 323
 324         If this class contains a valid pointer it will return @true, if it contains
 325         a @NULL pointer it will return @false.
 326     */
 327     operator unspecified_bool_type() const;
 328
 329     /**
 330         Returns a reference to the object.
 331
 332         @note
 333         If the internal pointer is @NULL this method will cause an assert
 334         in debug mode.
 335     */
 336     T operator*() const;
 337
 338     /**
 339         Returns pointer to object. If the pointer is @NULL this method will
 340         cause an assert in debug mode.
 341     */
 342     T* operator->() const;
 343
 344     /**
 345         Releases the current pointer and returns it.
 346
 347         @remarks
 348         Afterwards the caller is responsible for deleting
 349         the data contained in the scoped pointer before.
 350     */
 351     T* release();
 352
 353     /**
 354         Reset pointer to the value of @a ptr.
 355         The previous pointer will be deleted.
 356     */
 357     void reset(T* ptr = NULL);
 358
 359     /**
 360         Swaps pointers.
 361     */
 362     void swap(wxScopedPtr<T>& ot);
 363 };
 364