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 but rewritten to
  15     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 wxScopedPtrT().
  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     @library{wxbase}
  27     @category{FIXME}
  28
  29     @see wxScopedArray
  30 */
  31 class wxScopedPtr
  32 {
  33 public:
  34     /**
  35         Creates the smart pointer with the given pointer or none if @NULL.  On
  36         compilers that support it, this uses the explicit keyword.
  37     */
  38     explicit wxScopedPtr(type T = NULL);
  39
  40     /**
  41         Destructor frees the pointer help by this object if it is not @NULL.
  42     */
  43     ~wxScopedPtr();
  44
  45     /**
  46         This operator gets the pointer stored in the smart pointer or returns @NULL if
  47         there is none.
  48     */
  49     const T* get();
  50
  51     /**
  52         This operator works like the standard C++ pointer operator to return the object
  53         being pointed to by the pointer.  If the pointer is @NULL or invalid this will
  54         crash.
  55     */
  56     const T operator *();
  57
  58     /**
  59         This operator works like the standard C++ pointer operator to return the pointer
  60         in the smart pointer or @NULL if it is empty.
  61     */
  62     const T* operator -();
  63
  64     /**
  65         Returns the currently hold pointer and resets the smart pointer object to
  66         @NULL. After a call to this function the caller is responsible for
  67         deleting the pointer.
  68     */
  69     T* release();
  70
  71     /**
  72         Deletes the currently held pointer and sets it to @a p or to @NULL if no
  73         arguments are specified. This function does check to make sure that the
  74         pointer you are assigning is not the same pointer that is already stored.
  75     */
  76     reset(T p  = NULL);
  77
  78     /**
  79         Swap the pointer inside the smart pointer with @e other. The pointer being
  80         swapped must be of the same type (hence the same class name).
  81     */
  82     swap(wxScopedPtr amp; other);
  83 };
  84
  85
  86
  87 /**
  88     @class wxScopedArray
  89     @wxheader{ptr_scpd.h}
  90
  91     This is a simple scoped smart pointer array implementation that is similar to
  92     the Boost smart pointers but rewritten to
  93     use macros instead.
  94
  95     @library{wxbase}
  96     @category{FIXME}
  97
  98     @see wxScopedPtr
  99 */
 100 class wxScopedArray
 101 {
 102 public:
 103     /**
 104         Creates the smart pointer with the given pointer or none if @NULL.  On
 105         compilers that support it, this uses the explicit keyword.
 106     */
 107     wxScopedArray(type T = NULL);
 108
 109     /**
 110         This operator gets the pointer stored in the smart pointer or returns @NULL if
 111         there is none.
 112     */
 113     const T* get();
 114
 115     /**
 116         This operator acts like the standard [] indexing operator for C++ arrays.  The
 117         function does not do bounds checking.
 118     */
 119     const T operator [](long int i);
 120
 121     /**
 122         Deletes the currently held pointer and sets it to 'p' or to @NULL if no
 123         arguments are specified. This function does check to make sure that the
 124         pointer you are assigning is not the same pointer that is already stored.
 125     */
 126     reset(T p  = NULL);
 127
 128     /**
 129         Swap the pointer inside the smart pointer with 'ot'. The pointer being swapped
 130         must be of the same type (hence the same class name).
 131     */
 132     swap(wxScopedPtr amp; ot);
 133 };
 134
 135
 136
 137 /**
 138     @class wxScopedTiedPtr
 139     @wxheader{ptr_scpd.h}
 140
 141     This is a variation on the topic of wxScopedPtr. This
 142     class is also a smart pointer but in addition it "ties" the pointer value to
 143     another variable. In other words, during the life time of this class the value
 144     of that variable is set to be the same as the value of the pointer itself and
 145     it is reset to its old value when the object is destroyed. This class is
 146     especially useful when converting the existing code (which may already store
 147     the pointers value in some variable) to the smart pointers.
 148
 149     @library{wxbase}
 150     @category{FIXME}
 151 */
 152 class wxScopedTiedPtr
 153 {
 154 public:
 155     /**
 156         Constructor creates a smart pointer initialized with @a ptr and stores
 157         @a ptr in the location specified by @a ppTie which must not be
 158         @NULL.
 159     */
 160     wxScopedTiedPtr(T** ppTie, T* ptr);
 161
 162     /**
 163         Destructor frees the pointer help by this object and restores the value stored
 164         at the tied location (as specified in the @ref ctor() constructor)
 165         to the old value.
 166         Warning: this location may now contain an uninitialized value if it hadn't been
 167         initialized previously, in particular don't count on it magically being
 168         @NULL!
 169     */
 170     ~wxScopedTiedPtr();
 171 };
 172
 173
 174
 175 /**
 176     @wxheader{ptr_scpd.h}
 177
 178     A scoped pointer template class. It is the template version of
 179     the old-style @ref overview_wxscopedptr "scoped pointer macros".
 180
 181     @library{wxbase}
 182     @category{FIXME}
 183
 184     @see wxSharedPtr, wxWeakRef
 185 */
 186 template<typename T>
 187 class wxScopedPtr<T>
 188 {
 189 public:
 190     /**
 191         Constructor.
 192     */
 193     wxScopedPtr(T* ptr = NULL);
 194
 195     /**
 196         Destructor.
 197     */
 198     ~wxScopedPtr();
 199
 200     /**
 201         Returns pointer to object or @NULL.
 202     */
 203     T* get() const;
 204
 205     /**
 206         Conversion to a boolean expression (in a variant which is not
 207         convertable to anything but a boolean expression). If this class
 208         contains a valid pointer it will return @e @true, if it contains
 209         a @NULL pointer it will return @e @false.
 210     */
 211     operator unspecified_bool_type() const;
 212
 213     /**
 214         Returns a reference to the object. If the internal pointer is @NULL
 215         this method will cause an assert in debug mode.
 216     */
 217     T operator*() const;
 218
 219     /**
 220         Returns pointer to object. If the pointer is @NULL this method will
 221         cause an assert in debug mode.
 222     */
 223     T* operator-() const;
 224
 225     /**
 226         Releases the current pointer and returns it.
 227         Afterwards the caller is responsible for deleting
 228         the data contained in the scoped pointer before.
 229     */
 230     T* release();
 231
 232     /**
 233         Reset pointer to the value of @e ptr. The
 234         previous pointer will be deleted.
 235     */
 236     void reset(T* ptr = NULL);
 237
 238     /**
 239         Swaps pointers.
 240     */
 241     void swap(wxScopedPtr<T>& ot);
 242 };
 243