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