]> git.saurik.com Git - wxWidgets.git/blame - docs/latex/wx/scpdptr.tex
typo
[wxWidgets.git] / docs / latex / wx / scpdptr.tex
CommitLineData
3684ade8 1\section{\class{wxScopedPtr}}\label{wxscopedptr}
5b222f1c
JS
2
3This is a simple scoped smart pointer implementation that is similar to
d83eeece 4the \urlref{Boost}{http://www.boost.org/} smart pointers but rewritten to
5b222f1c
JS
5use macros instead.
6
89969a91
RR
7Since wxWidgets 2.9.0 there is also a templated version of this class
8with the same name. See \helpref{wxScopedPtr<T>}{wxscopedptrtemplate}.
9
d83eeece
VZ
10A smart pointer holds a pointer to an object. The memory used by the object is
11deleted when the smart pointer goes out of scope. This class is different from
12the \texttt{std::auto\_ptr<>} in so far as it doesn't provide copy constructor
13nor assignment operator. This limits what you can do with it but is much less
14surprizing than the ``destructive copy'' behaviour of the standard class.
15
5b222f1c
JS
16\wxheading{Example}
17
fc2171bd 18Below is an example of using a wxWidgets scoped smart pointer and
5b222f1c
JS
19pointer 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
d83eeece
VZ
53To declare the smart pointer class \texttt{CLASSNAME} containing pointes to a
54(possibly incomplete) type \texttt{TYPE} you should use
d2c2afc9 55
5b222f1c 56\begin{verbatim}
d83eeece 57 wxDECLARE_SCOPED_PTR( TYPE, // type of the values
5b222f1c
JS
58 CLASSNAME ); // name of the class
59\end{verbatim}
60
d83eeece 61And later, when \texttt{TYPE} is fully defined, you must also use
d2c2afc9 62
d83eeece
VZ
63\begin{verbatim}
64 wxDEFINE_SCOPED_PTR( TYPE, CLASSNAME );
65\end{verbatim}
66to implement the scoped pointer class.
67
68The first argument of these macro is the pointer type, the second is the name
69of the new smart pointer class being created. Below we will use wxScopedPtr to
5b222f1c
JS
70represent the scoped pointer class, but the user may create the class with any
71legal name.
72
d83eeece
VZ
73Alternatively, if you don't have to separate the point of declaration and
74definition of this class and if you accept the standard naming convention, that
75is 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:
d2c2afc9 77
d83eeece
VZ
78\begin{verbatim}
79 wxDEFINE_SCOPED_PTR_TYPE( TYPE );
80\end{verbatim}
d2c2afc9 81
d83eeece
VZ
82Once again, in this cass \texttt{CLASSNAME} will be \texttt{TYPEPtr}.
83
5b222f1c
JS
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
39275175 94\membersection{wxScopedPtr::wxScopedPtr}\label{wxscopedptrctor}
5b222f1c 95
38f15267 96\func{}{explicit wxScopedPtr}{\param{type}{ * T = NULL}}
5b222f1c 97
38f15267 98Creates the smart pointer with the given pointer or none if {\tt NULL}. On
5b222f1c
JS
99compilers that support it, this uses the explicit keyword.
100
38f15267 101
39275175 102\membersection{wxScopedPtr::\destruct{wxScopedPtr}}\label{wxscopedptrdtor}
38f15267
VZ
103
104\func{}{\destruct{wxScopedPtr}}{\void}
105
840d782c 106Destructor frees the pointer help by this object if it is not {\tt NULL}.
38f15267
VZ
107
108
39275175 109\membersection{wxScopedPtr::release}\label{wxscopedptrrelease}
5455e227
VZ
110
111\func{T *}{release}{\void}
112
113Returns 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
115deleting the pointer.
116
117
39275175 118\membersection{wxScopedPtr::reset}\label{wxscopedptrreset}
5b222f1c
JS
119
120\func{\void}{reset}{\param{T}{ p * = NULL}}
121
5455e227 122Deletes the currently held pointer and sets it to {\it p} or to NULL if no
5b222f1c
JS
123arguments are specified. This function does check to make sure that the
124pointer you are assigning is not the same pointer that is already stored.
125
38f15267 126
39275175 127\membersection{wxScopedPtr::operator *}\label{wxscopedptrptr}
5b222f1c
JS
128
129\func{const T\&}{operator *}{\void}
130
131This operator works like the standard C++ pointer operator to return the object
132being pointed to by the pointer. If the pointer is NULL or invalid this will
133crash.
134
38f15267 135
39275175 136\membersection{wxScopedPtr::operator -$>$}\label{wxscopedptrref}
5b222f1c 137
bf43ff9a 138\func{const T*}{operator -$>$}{\void} % TODO
5b222f1c
JS
139
140This operator works like the standard C++ pointer operator to return the pointer
141in the smart pointer or NULL if it is empty.
142
38f15267 143
39275175 144\membersection{wxScopedPtr::get}\label{wxscopedptrget}
5b222f1c
JS
145
146\func{const T*}{get}{\void}
147
148This operator gets the pointer stored in the smart pointer or returns NULL if
149there is none.
150
38f15267 151
39275175 152\membersection{wxScopedPtr::swap}\label{wxscopedptrswap}
5b222f1c 153
5455e227 154\func{\void}{swap}{\param{wxScopedPtr}{ \& other}}
5b222f1c 155
5455e227
VZ
156Swap the pointer inside the smart pointer with {\it other}. The pointer being
157swapped must be of the same type (hence the same class name).
5b222f1c 158
38f15267
VZ
159
160
161
162%%%%%%% wxScopedTiedPtr %%%%%%%
163\section{\class{wxScopedTiedPtr}}\label{wxscopedtiedptr}
164
165This is a variation on the topic of \helpref{wxScopedPtr}{wxscopedptr}. This
166class is also a smart pointer but in addition it ``ties'' the pointer value to
167another variable. In other words, during the life time of this class the value
168of that variable is set to be the same as the value of the pointer itself and
169it is reset to its old value when the object is destroyed. This class is
170especially useful when converting the existing code (which may already store
171the 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
189Constructor 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
197Destructor frees the pointer help by this object and restores the value stored
198at the tied location (as specified in the \helpref{constructor}{wxscopedtiedptrctor})
199to the old value.
200
201Warning: this location may now contain an uninitialized value if it hadn't been
202initialized previously, in particular don't count on it magically being
203{\tt NULL}!
204
205