interface/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     @wxheader{ptr_scpd.h}
  12
  13     This is a simple scoped smart pointer implementation that is similar to
  14     the Boost smart pointers (see http://www.boost.org) but rewritten
  15     to use macros instead.
  16
  17     Since wxWidgets 2.9.0 there is also a templated version of this class
  18     with the same name. See wxScopedPtr<T>.
  19
  20     A smart pointer holds a pointer to an object. The memory used by the object is
  21     deleted when the smart pointer goes out of scope. This class is different from
  22     the @c std::auto_ptr<> in so far as it doesn't provide copy constructor
  23     nor assignment operator. This limits what you can do with it but is much less
  24     surprizing than the "destructive copy" behaviour of the standard class.
  25
  26     @b Example:
  27
  28     Below is an example of using a wxWidgets scoped smart pointer and pointer array.
  29
  30     @code
  31     class MyClass{ ... };
  32
  33     // declare a smart pointer to a MyClass called wxMyClassPtr
  34     wxDECLARE_SCOPED_PTR(MyClass, wxMyClassPtr)
  35     // declare a smart pointer to an array of chars
  36     wxDECLARE_SCOPED_ARRAY(char, wxCharArray)
  37
  38     ...
  39
  40     // define the first pointer class, must be complete
  41     wxDEFINE_SCOPED_PTR(MyClass, wxMyClassPtr)
  42     // define the second pointer class
  43     wxDEFINE_SCOPED_ARRAY(char, wxCharArray)
  44
  45     // create an object with a new pointer to MyClass
  46     wxMyClassPtr theObj(new MyClass());
  47     // reset the pointer (deletes the previous one)
  48     theObj.reset(new MyClass());
  49
  50     // access the pointer
  51     theObj->MyFunc();
  52
  53     // create an object with a new array of chars
  54     wxCharArray theCharObj(new char[100]);
  55
  56     // access the array
  57     theCharObj[0] = "!";
  58     @endcode
  59
  60     @section wxscopedptr_newpointers Declaring new smart pointer types
  61
  62     To declare the smart pointer class @c CLASSNAME containing pointes to
  63     a (possibly incomplete) type @c TYPE you should use
  64     @code
  65         wxDECLARE_SCOPED_PTR( TYPE,        // type of the values
  66                               CLASSNAME ); // name of the class
  67     @endcode
  68     And later, when @c TYPE is fully defined, you must also use
  69     @code
  70         wxDEFINE_SCOPED_PTR( TYPE, CLASSNAME );
  71     @endcode
  72     to implement the scoped pointer class.
  73
  74     The first argument of these macro is the pointer type, the second is the name
  75     of the new smart pointer class being created. Below we will use wxScopedPtr
  76     to represent the scoped pointer class, but the user may create the class with
  77     any legal name.
  78
  79     Alternatively, if you don't have to separate the point of declaration and
  80     definition of this class and if you accept the standard naming convention,
  81     that is that the scoped pointer for the class @c Foo is called @c FooPtr,
  82     you can use a single macro which replaces two macros above:
  83     @code
  84         wxDEFINE_SCOPED_PTR_TYPE( TYPE );
  85     @endcode
  86     Once again, in this cass @c CLASSNAME will be @c TYPEPtr.
  87
  88     @library{wxbase}
  89     @category{smartpointers}
  90
  91     @see wxScopedArray
  92 */
  93 class wxScopedPtr
  94 {
  95 public:
  96     /**
  97         Creates the smart pointer with the given pointer or none if @NULL.
  98
  99         On compilers that support it, this uses the explicit keyword.
 100     */
 101     explicit wxScopedPtr(type* T = NULL);
 102
 103     /**
 104         Destructor frees the pointer help by this object if it is not @NULL.
 105     */
 106     ~wxScopedPtr();
 107
 108     /**
 109         This operator gets the pointer stored in the smart pointer or returns
 110         @NULL if there is none.
 111     */
 112     const T* get();
 113
 114     /**
 115         This operator works like the standard C++ pointer operator to return the object
 116         being pointed to by the pointer.
 117
 118         @note
 119         If the pointer is @NULL or invalid this will crash.
 120     */
 121     const T& operator *();
 122
 123     /**
 124         This operator works like the standard C++ pointer operator to return the pointer
 125         in the smart pointer or @NULL if it is empty.
 126     */
 127     const T* operator ->();
 128
 129     /**
 130         Returns the currently hold pointer and resets the smart pointer object to
 131         @NULL.
 132
 133         @remarks
 134         After a call to this function the caller is responsible for deleting the
 135         pointer.
 136     */
 137     T* release();
 138
 139     /**
 140         Deletes the currently held pointer and sets it to @a p or to @NULL if no
 141         arguments are specified.
 142
 143         @note
 144         This function does check to make sure that the pointer you are assigning
 145         is not the same pointer that is already stored.
 146     */
 147     reset(T* p  = NULL);
 148
 149     /**
 150         Swap the pointer inside the smart pointer with @a other. The pointer being
 151         swapped must be of the same type (hence the same class name).
 152     */
 153     swap(wxScopedPtr& other);
 154 };
 155
 156
 157
 158 /**
 159     @class wxScopedArray
 160     @wxheader{ptr_scpd.h}
 161
 162     This is a simple scoped smart pointer array implementation that is similar to
 163     the Boost smart pointers (see http://www.boost.org/) but rewritten to
 164     use macros instead.
 165
 166     @b Example:
 167
 168     Below is an example of using a wxWidgets scoped smart pointer and pointer array.
 169
 170     @code
 171     class MyClass { ... };
 172
 173     // declare a smart pointer to a MyClass called wxMyClassPtr
 174     wxDECLARE_SCOPED_PTR(MyClass, wxMyClassPtr)
 175     // declare a smart pointer to an array of chars
 176     wxDECLARE_SCOPED_ARRAY(char, wxCharArray)
 177
 178     ...
 179
 180     // define the first pointer class, must be complete
 181     wxDEFINE_SCOPED_PTR(MyClass, wxMyClassPtr)
 182     // define the second pointer class
 183     wxDEFINE_SCOPED_ARRAY(char, wxCharArray)
 184
 185     // create an object with a new pointer to MyClass
 186     wxMyClassPtr theObj(new MyClass());
 187     // reset the pointer (deletes the previous one)
 188     theObj.reset(new MyClass());
 189
 190     // access the pointer
 191     theObj->MyFunc();
 192
 193     // create an object with a new array of chars
 194     wxCharArray theCharObj(new char[100]);
 195
 196     // access the array
 197     theCharObj[0] = "!";
 198     @endcode
 199
 200     <b>Declaring new smart pointer types:</b>
 201     @code
 202     wxDECLAR_SCOPED_ARRAY( TYPE,        // type of the values
 203                            CLASSNAME ); // name of the class
 204     @endcode
 205
 206     A smart pointer holds a pointer to an object (which must be complete when
 207     wxDEFINE_SCOPED_ARRAY() is called).
 208
 209     The memory used by the object is deleted when the smart pointer goes out of
 210     scope. The first argument of the macro is the pointer type, the second is the
 211     name of the new smart pointer class being created. Below we will use wxScopedArray
 212     to represent the scoped pointer array class, but the user may create the class with
 213     any legal name.
 214
 215     @library{wxbase}
 216     @category{smartpointers}
 217
 218     @see wxScopedPtr
 219 */
 220 class wxScopedArray
 221 {
 222 public:
 223     /**
 224         Creates the smart pointer with the given pointer or none if @NULL.  On
 225         compilers that support it, this uses the explicit keyword.
 226     */
 227     wxScopedArray(type*  T = NULL);
 228
 229     /**
 230         This operator gets the pointer stored in the smart pointer or returns @NULL if
 231         there is none.
 232     */
 233     const T* get();
 234
 235     /**
 236         This operator acts like the standard [] indexing operator for C++ arrays.  The
 237         function does not do bounds checking.
 238     */
 239     const T& operator [](long int i);
 240
 241     /**
 242         Deletes the currently held pointer and sets it to 'p' or to @NULL if no
 243         arguments are specified. This function does check to make sure that the
 244         pointer you are assigning is not the same pointer that is already stored.
 245     */
 246     reset(T* p  = NULL);
 247
 248     /**
 249         Swap the pointer inside the smart pointer with @a ot. The pointer being swapped
 250         must be of the same type (hence the same class name).
 251     */
 252     swap(wxScopedPtr& ot);
 253 };
 254
 255
 256
 257 /**
 258     @class wxScopedTiedPtr
 259     @wxheader{ptr_scpd.h}
 260
 261     This is a variation on the topic of wxScopedPtr. This class is also a smart pointer
 262     but in addition it "ties" the pointer value to another variable. In other words,
 263     during the life time of this class the value of that variable is set to be the same
 264     as the value of the pointer itself and it is reset to its old value when the object
 265     is destroyed. This class is especially useful when converting the existing code
 266     (which may already store the pointers value in some variable) to the smart pointers.
 267
 268     @library{wxbase}
 269     @category{smartpointers}
 270 */
 271 class wxScopedTiedPtr : public wxScopedPtr
 272 {
 273 public:
 274     /**
 275         Constructor creates a smart pointer initialized with @a ptr and stores
 276         @a ptr in the location specified by @a ppTie which must not be @NULL.
 277     */
 278     wxScopedTiedPtr(T** ppTie, T* ptr);
 279
 280     /**
 281         Destructor frees the pointer help by this object and restores the value stored
 282         at the tied location (as specified in the @ref ctor() constructor)
 283         to the old value.
 284
 285         @warning
 286         This location may now contain an uninitialized value if it hadn't been
 287         initialized previously, in particular don't count on it magically being @NULL!
 288     */
 289     ~wxScopedTiedPtr();
 290 };
 291
 292
 293
 294 /**
 295     @wxheader{ptr_scpd.h}
 296
 297     A scoped pointer template class. It is the template version of
 298     the old-style @ref classwx_scoped_ptr "scoped pointer macros".
 299
 300     @library{wxbase}
 301     @category{smartpointers}
 302
 303     @see wxSharedPtr<T>, wxWeakRef<T>
 304 */
 305 template<typename T>
 306 class wxScopedPtr<T>
 307 {
 308 public:
 309     /**
 310         Constructor.
 311     */
 312     wxScopedPtr(T* ptr = NULL);
 313
 314     /**
 315         Destructor.
 316     */
 317     ~wxScopedPtr();
 318
 319     /**
 320         Returns pointer to object or @NULL.
 321     */
 322     T* get() const;
 323
 324     /**
 325         Conversion to a boolean expression (in a variant which is not
 326         convertable to anything but a boolean expression).
 327
 328         If this class contains a valid pointer it will return @true, if it contains
 329         a @NULL pointer it will return @false.
 330     */
 331     operator unspecified_bool_type() const;
 332
 333     /**
 334         Returns a reference to the object.
 335
 336         @note
 337         If the internal pointer is @NULL this method will cause an assert
 338         in debug mode.
 339     */
 340     T operator*() const;
 341
 342     /**
 343         Returns pointer to object. If the pointer is @NULL this method will
 344         cause an assert in debug mode.
 345     */
 346     T* operator->() const;
 347
 348     /**
 349         Releases the current pointer and returns it.
 350
 351         @remarks
 352         Afterwards the caller is responsible for deleting
 353         the data contained in the scoped pointer before.
 354     */
 355     T* release();
 356
 357     /**
 358         Reset pointer to the value of @a ptr.
 359         The previous pointer will be deleted.
 360     */
 361     void reset(T* ptr = NULL);
 362
 363     /**
 364         Swaps pointers.
 365     */
 366     void swap(wxScopedPtr<T>& ot);
 367 };
 368