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 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
 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
 295     It is the template version of the old-style @ref wxScopedPtr "scoped pointer macros".
 296
 297     Notice that objects of this class intentionally cannot be copied.
 298
 299     @library{wxbase}
 300     @category{smartpointers}
 301
 302     @see wxSharedPtr<T>, wxWeakRef<T>
 303 */
 304 template<typename T>
 305 class wxScopedPtr<T>
 306 {
 307 public:
 308     /**
 309         Constructor takes ownership of the pointer.
 310
 311         @param ptr
 312             Pointer allocated with @c new or @NULL.
 313     */
 314     wxScopedPtr(T* ptr = NULL);
 315
 316     /**
 317         Destructor deletes the pointer.
 318     */
 319     ~wxScopedPtr();
 320
 321     /**
 322         Returns pointer to object or @NULL.
 323     */
 324     T* get() const;
 325
 326     /**
 327         Conversion to a boolean expression (in a variant which is not
 328         convertible to anything but a boolean expression).
 329
 330         If this class contains a valid pointer it will return @true, if it contains
 331         a @NULL pointer it will return @false.
 332     */
 333     operator unspecified_bool_type() const;
 334
 335     /**
 336         Returns a reference to the object.
 337
 338         @note
 339         If the internal pointer is @NULL this method will cause an assert
 340         in debug mode.
 341     */
 342     T operator*() const;
 343
 344     /**
 345         Returns pointer to object. If the pointer is @NULL this method will
 346         cause an assert in debug mode.
 347     */
 348     T* operator->() const;
 349
 350     /**
 351         Releases the current pointer and returns it.
 352
 353         @remarks
 354         Afterwards the caller is responsible for deleting
 355         the data contained in the scoped pointer before.
 356     */
 357     T* release();
 358
 359     /**
 360         Reset pointer to the value of @a ptr.
 361         The previous pointer will be deleted.
 362     */
 363     void reset(T* ptr = NULL);
 364
 365     /**
 366         Swaps pointers.
 367     */
 368     void swap(wxScopedPtr<T>& ot);
 369 };
 370
 371 /**
 372     A scoped array template class.
 373
 374     This class is similar to boost scoped_array class:
 375     http://www.boost.org/doc/libs/1_37_0/libs/smart_ptr/scoped_array.htm
 376
 377     Notice that objects of this class intentionally cannot be copied.
 378
 379     @library{wxbase}
 380     @category{smartpointers}
 381  */
 382 template <class T>
 383 class wxScopedArray
 384 {
 385 public:
 386     /// The type of the array elements.
 387     typedef T element_type;
 388
 389     /**
 390         Constructor takes ownership of the given array.
 391
 392         If @a array is @NULL, reset() must presumably be called later.
 393
 394         @param array
 395             An array allocated using @c new[] or @NULL.
 396      */
 397     explicit wxScopedArray(T * array = NULL);
 398
 399     /// Destructor destroy the array.
 400     ~wxScopedArray();
 401
 402     /**
 403         Conversion to a boolean expression (in a variant which is not
 404         convertible to anything but a boolean expression).
 405
 406         If this class contains a valid array it will return @true, if it contains
 407         a @NULL pointer it will return @false.
 408     */
 409     operator unspecified_bool_type() const;
 410
 411     /**
 412         Change the array pointer stored.
 413
 414         The previously stored array is deleted.
 415
 416         @param array
 417             An array allocated using @c new[] or @NULL.
 418      */
 419     void reset(T *array = NULL);
 420
 421     /**
 422         Return the n-th element of the array.
 423
 424         Must not be called if the array has no valid pointer.
 425      */
 426     T& operator[](size_t n) const;
 427
 428     /**
 429         Return the array pointer.
 430
 431         The returned pointer may be @NULL. It must not be deleted by the
 432         caller, call @c reset(NULL) instead.
 433      */
 434     T *get() const { return m_array; }
 435
 436     /// Swaps the contents of this array with another one.
 437     void swap(wxScopedArray &other)
 438     {
 439         T * const tmp = other.m_array;
 440         other.m_array = m_array;
 441         m_array = tmp;
 442     }
 443 };