docs/latex/wx/scpdptr.tex

   1 \section{\class{wxScopedPtr}}\label{wxscopedptr}
   2
   3 This is a simple scoped smart pointer implementation that is similar to
   4 the \urlref{Boost}{http://www.boost.org/} smart pointers but rewritten to
   5 use macros instead.
   6
   7 Since wxWidgets 2.9.0 there is also a templated version of this class
   8 with the same name. See \helpref{wxScopedPtr<T>}{wxscopedptrtemplate}.
   9
  10 A smart pointer holds a pointer to an object. The memory used by the object is
  11 deleted when the smart pointer goes out of scope. This class is different from
  12 the \texttt{std::auto\_ptr<>} in so far as it doesn't provide copy constructor
  13 nor assignment operator. This limits what you can do with it but is much less
  14 surprizing than the ``destructive copy'' behaviour of the standard class.
  15
  16 \wxheading{Example}
  17
  18 Below is an example of using a wxWidgets scoped smart pointer and
  19 pointer array.
  20
  21 \begin{verbatim}
  22   class MyClass { /* ... */ };
  23
  24   // declare a smart pointer to a MyClass called wxMyClassPtr
  25   wxDECLARE_SCOPED_PTR(MyClass, wxMyClassPtr)
  26   // declare a smart pointer to an array of chars
  27   wxDECLARE_SCOPED_ARRAY(char, wxCharArray)
  28
  29   ...
  30
  31   // define the first pointer class, must be complete
  32   wxDEFINE_SCOPED_PTR(MyClass, wxMyClassPtr)
  33   // define the second pointer class
  34   wxDEFINE_SCOPED_ARRAY(char, wxCharArray)
  35
  36   // create an object with a new pointer to MyClass
  37   wxMyClassPtr theObj(new MyClass());
  38   // reset the pointer (deletes the previous one)
  39   theObj.reset(new MyClass());
  40
  41   // access the pointer
  42   theObj->MyFunc();
  43
  44   // create an object with a new array of chars
  45   wxCharArray theCharObj(new char[100]);
  46
  47   // access the array
  48   theCharObj[0] = "!";
  49 \end{verbatim}
  50
  51 \wxheading{Declaring new smart pointer types}
  52
  53 To declare the smart pointer class \texttt{CLASSNAME} containing pointes to a
  54 (possibly incomplete) type \texttt{TYPE} you should use
  55
  56 \begin{verbatim}
  57     wxDECLARE_SCOPED_PTR( TYPE,     // type of the values
  58                                 CLASSNAME ); // name of the class
  59 \end{verbatim}
  60
  61 And later, when \texttt{TYPE} is fully defined, you must also use
  62
  63 \begin{verbatim}
  64     wxDEFINE_SCOPED_PTR( TYPE, CLASSNAME );
  65 \end{verbatim}
  66 to implement the scoped pointer class.
  67
  68 The first argument of these macro is the pointer type, the second is the name
  69 of the new smart pointer class being created.  Below we will use wxScopedPtr to
  70 represent the scoped pointer class, but the user may create the class with any
  71 legal name.
  72
  73 Alternatively, if you don't have to separate the point of declaration and
  74 definition of this class and if you accept the standard naming convention, that
  75 is that the scoped pointer for the class \texttt{Foo} is called
  76 \texttt{FooPtr}, you can use a single macro which replaces two macros above:
  77
  78 \begin{verbatim}
  79     wxDEFINE_SCOPED_PTR_TYPE( TYPE );
  80 \end{verbatim}
  81
  82 Once again, in this cass \texttt{CLASSNAME} will be \texttt{TYPEPtr}.
  83
  84 \wxheading{Include files}
  85
  86 <wx/ptr\_scpd.h>
  87
  88 \wxheading{See also}
  89
  90 \helpref{wxScopedArray}{wxscopedarray}\rtfsp
  91
  92 \latexignore{\rtfignore{\wxheading{Members}}}
  93
  94 \membersection{wxScopedPtr::wxScopedPtr}\label{wxscopedptrctor}
  95
  96 \func{}{explicit wxScopedPtr}{\param{type}{ * T = NULL}}
  97
  98 Creates the smart pointer with the given pointer or none if {\tt NULL}.  On
  99 compilers that support it, this uses the explicit keyword.
 100
 101
 102 \membersection{wxScopedPtr::\destruct{wxScopedPtr}}\label{wxscopedptrdtor}
 103
 104 \func{}{\destruct{wxScopedPtr}}{\void}
 105
 106 Destructor frees the pointer help by this object if it is not {\tt NULL}.
 107
 108
 109 \membersection{wxScopedPtr::release}\label{wxscopedptrrelease}
 110
 111 \func{T *}{release}{\void}
 112
 113 Returns the currently hold pointer and resets the smart pointer object to
 114 {\tt NULL}. After a call to this function the caller is responsible for
 115 deleting the pointer.
 116
 117
 118 \membersection{wxScopedPtr::reset}\label{wxscopedptrreset}
 119
 120 \func{\void}{reset}{\param{T}{ p * = NULL}}
 121
 122 Deletes the currently held pointer and sets it to {\it 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
 127 \membersection{wxScopedPtr::operator *}\label{wxscopedptrptr}
 128
 129 \func{const T\&}{operator *}{\void}
 130
 131 This operator works like the standard C++ pointer operator to return the object
 132 being pointed to by the pointer.  If the pointer is NULL or invalid this will
 133 crash.
 134
 135
 136 \membersection{wxScopedPtr::operator -$>$}\label{wxscopedptrref}
 137
 138 \func{const T*}{operator -$>$}{\void} % TODO
 139
 140 This operator works like the standard C++ pointer operator to return the pointer
 141 in the smart pointer or NULL if it is empty.
 142
 143
 144 \membersection{wxScopedPtr::get}\label{wxscopedptrget}
 145
 146 \func{const T*}{get}{\void}
 147
 148 This operator gets the pointer stored in the smart pointer or returns NULL if
 149 there is none.
 150
 151
 152 \membersection{wxScopedPtr::swap}\label{wxscopedptrswap}
 153
 154 \func{\void}{swap}{\param{wxScopedPtr}{ \& other}}
 155
 156 Swap the pointer inside the smart pointer with {\it other}. The pointer being
 157 swapped must be of the same type (hence the same class name).
 158
 159
 160
 161
 162 %%%%%%% wxScopedTiedPtr %%%%%%%
 163 \section{\class{wxScopedTiedPtr}}\label{wxscopedtiedptr}
 164
 165 This is a variation on the topic of \helpref{wxScopedPtr}{wxscopedptr}. This
 166 class is also a smart pointer but in addition it ``ties'' the pointer value to
 167 another variable. In other words, during the life time of this class the value
 168 of that variable is set to be the same as the value of the pointer itself and
 169 it is reset to its old value when the object is destroyed. This class is
 170 especially useful when converting the existing code (which may already store
 171 the pointers value in some variable) to the smart pointers.
 172
 173 \wxheading{Example}
 174
 175 \wxheading{Derives from}
 176
 177 \helpref{wxScopedPtr}{wxscopedptr}
 178
 179 \wxheading{Include files}
 180
 181 <wx/ptr\_scpd.h>
 182
 183 \latexignore{\rtfignore{\wxheading{Members}}}
 184
 185 \membersection{wxScopedTiedPtr::wxScopedTiedPtr}\label{wxscopedtiedptrctor}
 186
 187 \func{}{wxScopedTiedPtr}{\param{T **}{ppTie}, \param{T *}{ptr}}
 188
 189 Constructor creates a smart pointer initialized with \arg{ptr} and stores
 190 \arg{ptr} in the location specified by \arg{ppTie} which must not be
 191 {\tt NULL}.
 192
 193 \membersection{wxScopedTiedPtr::\destruct{wxScopedTiedPtr}}\label{wxscopedtiedptrdtor}
 194
 195 \func{}{\destruct{wxScopedTiedPtr}}{\void}
 196
 197 Destructor frees the pointer help by this object and restores the value stored
 198 at the tied location (as specified in the \helpref{constructor}{wxscopedtiedptrctor})
 199 to the old value.
 200
 201 Warning: this location may now contain an uninitialized value if it hadn't been
 202 initialized previously, in particular don't count on it magically being
 203 {\tt NULL}!
 204
 205