docs/latex/wx/list.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        list.tex
   3 %% Purpose:     wxList
   4 %% Author:      wxWidgets Team
   5 %% Modified by:
   6 %% Created:
   7 %% RCS-ID:      $Id$
   8 %% Copyright:   (c) wxWidgets Team
   9 %% License:     wxWindows license
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11
  12 \section{\class{wxList<T>}}\label{wxlist}
  13
  14 The wxList<T> class provides linked list functionality. It has been written
  15 to be type safe and to provide the full API of the STL std::list container and
  16 should be used like it. The exception is that wxList<T> actually stores
  17 pointers and therefore its iterators return pointers and not references
  18 to the actual objets in the list (see example below) and {\it value\_type}
  19 is defined as {\it T*}.
  20
  21
  22 Unfortunately, the
  23 new wxList<T> class requires that you declare and define each wxList<T>
  24 class in your program. This is done with {\it WX\_DECLARE\_LIST} and
  25 {\it WX\_DEFINE\_LIST} macros (see example). We hope that we'll be able
  26 to provide a proper template class providing both the STL std::list
  27 and the old wxList API in the future.
  28
  29 Please refer to the STL std::list documentation for further
  30 information on how to use the class. Below we documented both
  31 the supported STL and the legacy API that originated from the
  32 old wxList class and which can still be used alternatively for
  33 the the same class.
  34
  35 Note that if you compile wxWidgets in STL mode (wxUSE\_STL defined as 1)
  36 then wxList<T> will actually derive from std::list and just add a legacy
  37 compatibility layer for the old wxList class.
  38
  39 \wxheading{Example}
  40
  41 \begin{verbatim}
  42     // this part might be in a header or source (.cpp) file
  43     class MyListElement
  44     {
  45         ... // whatever
  46     };
  47
  48     // this macro declares and partly implements MyList class
  49     WX_DECLARE_LIST(MyListElement, MyList);
  50
  51     ...
  52
  53     // the only requirement for the rest is to be AFTER the full declaration of
  54     // MyListElement (for WX_DECLARE_LIST forward declaration is enough), but
  55     // usually it will be found in the source file and not in the header
  56
  57     #include <wx/listimpl.cpp>
  58     WX_DEFINE_LIST(MyList);
  59
  60
  61     MyList list;
  62     MyListElement element;
  63     list.Append(&element);     // ok
  64     list.Append(17);           // error: incorrect type
  65
  66     // let's iterate over the list in STL syntax
  67     MyList::iterator iter;
  68     for (iter = list.begin(); iter != list.end(); ++iter)
  69     {
  70         MyListElement *current = *iter;
  71
  72         ...process the current element...
  73     }
  74
  75     // the same with the legacy API from the old wxList class
  76     MyList::compatibility_iterator node = list.GetFirst();
  77     while (node)
  78     {
  79         MyListElement *current = node->GetData();
  80
  81         ...process the current element...
  82
  83         node = node->GetNext();
  84     }
  85
  86 \end{verbatim}
  87
  88 For compatibility with previous versions wxList and wxStringList classes are
  89 still defined, but their usage is deprecated and they will disappear in the
  90 future versions completely. The use of the latter is especially discouraged as
  91 it is not only unsafe but is also much less efficient than
  92 \helpref{wxArrayString}{wxarraystring} class.
  93
  94 \wxheading{Include files}
  95
  96 <wx/list.h>
  97
  98 \wxheading{Library}
  99
 100 \helpref{wxBase}{librarieslist}
 101
 102 \wxheading{See also}
 103
 104 \helpref{wxArray<T>}{wxarray},
 105 \helpref{wxVector<T>}{wxvector}
 106
 107 \latexignore{\rtfignore{\wxheading{Members}}}
 108
 109 \membersection{wxList<T>::wxList<T>}\label{wxlistctor}
 110
 111 \func{}{wxList<T>}{\void}
 112
 113 \func{}{wxList<T>}{\param{size\_t}{ count}, \param{T *}{elements[]}}
 114
 115 Constructors.
 116
 117 \membersection{wxList<T>::\destruct{wxList<T>}}\label{wxlistdtor}
 118
 119 \func{}{\destruct{wxList<T>}}{\void}
 120
 121 Destroys the list, but does not delete the objects stored in the list
 122 unless you called DeleteContents({\tt true} ).
 123
 124 \membersection{wxList<T>::Append}\label{wxlistappend}
 125
 126 \func{wxList<T>::compatibility\_iterator }{Append}{\param{T *}{object}}
 127
 128 Appends the pointer to \rtfsp{\it object} to the list.
 129
 130 \membersection{wxList<T>::Clear}\label{wxlistclear1}
 131
 132 \func{void}{Clear}{\void}
 133
 134 Clears the list, but does not delete the objects stored in the list
 135 unless you called DeleteContents({\tt true} ).
 136
 137 \membersection{wxList<T>::DeleteContents}\label{wxlistdeletecontents}
 138
 139 \func{void}{DeleteContents}{\param{bool}{ destroy}}
 140
 141 If {\it destroy} is {\tt true}, instructs the list to call {\it delete}
 142 on objects stored in the list whenever they are removed.
 143 The default is {\tt false}.
 144
 145 \membersection{wxList<T>::DeleteNode}\label{wxlistdeletenode}
 146
 147 \func{bool}{DeleteNode}{\param{const compatibility\_iterator &}{iter}}
 148
 149 Deletes the given element refered to by {\tt iter} from the list,
 150 returning {\tt true} if successful.
 151
 152 \membersection{wxList<T>::DeleteObject}\label{wxlistdeleteobject}
 153
 154 \func{bool}{DeleteObject}{\param{T *}{object}}
 155
 156 Finds the given {\it object} and removes it from the list, returning
 157 {\tt true} if successful. The application must delete the actual object
 158 separately.
 159
 160 \membersection{wxList<T>::Erase}\label{wxlisterase}
 161
 162 \func{void}{Erase}{\param{const compatibility\_iterator &}{iter}}
 163
 164 Removes element refered to be {\tt iter}.
 165
 166 \membersection{wxList<T>::Find}\label{wxlistfind}
 167
 168 \constfunc{wxList<T>::compatibility\_iterator}{Find}{\param{T *}{ object}}
 169
 170 Returns the iterator refering to {\it object} or NULL if none found.
 171
 172 \membersection{wxList<T>::GetCount}\label{wxlistgetcount}
 173
 174 \constfunc{size\_t}{GetCount}{\void}
 175
 176 Returns the number of elements in the list.
 177
 178 \membersection{wxList<T>::GetFirst}\label{wxlistgetfirst}
 179
 180 \constfunc{wxList<T>::compatibility\_iterator}{GetFirst}{\void}
 181
 182 Returns the first iterator in the list (NULL if the list is empty).
 183
 184 \membersection{wxList<T>::GetLast}\label{wxlistgetlast}
 185
 186 \constfunc{wxList<T>::compatibility\_iterator}{GetLast}{\void}
 187
 188 Returns the last iterator in the list (NULL if the list is empty).
 189
 190 \membersection{wxList<T>::IndexOf}\label{wxlistindexof}
 191
 192 \constfunc{int}{IndexOf}{\param{T*}{ obj }}
 193
 194 Returns the index of {\it obj} within the list or {\tt wxNOT\_FOUND} if
 195 {\it obj} is not found in the list.
 196
 197 \membersection{wxList<T>::Insert}\label{wxlistinsert1}
 198
 199 \func{wxList<T>::compatibility\_iterator}{Insert}{\param{T *}{object}}
 200
 201 Insert object at the front of list.
 202
 203 \func{wxList<T>::compatibility\_iterator}{Insert}{\param{size\_t }{position}, \param{T *}{object}}
 204
 205 Insert object before {\it position}, i.e. the index of the new item in the
 206 list will be equal to {\it position}. {\it position} should be less than or
 207 equal to \helpref{GetCount}{wxlistgetcount}; if it is equal to it, this is the
 208 same as calling \helpref{Append}{wxlistappend}.
 209
 210 \func{wxList<T>::compatibility\_iterator}{Insert}{\param{compatibility\_iterator}{iter}, \param{T *}{object}}
 211
 212 Inserts the object before the object refered to be {\it iter}.
 213
 214 \membersection{wxList<T>::IsEmpty}\label{wxlistisempty}
 215
 216 \constfunc{bool}{IsEmpty}{\void}
 217
 218 Returns {\tt true} if the list is empty, {\tt false} otherwise.
 219
 220 % Use different label name to avoid clashing with wxListItem label
 221 \membersection{wxList<T>::Item}\label{wxlistitemfunc}
 222
 223 \constfunc{wxList<T>::compatibility\_iterator}{Item}{\param{size\_t }{index}}
 224
 225 Returns the iterator refering to the object at the given
 226 {\tt index} in the list.
 227
 228 \membersection{wxList<T>::Member}\label{wxlistmember}
 229
 230 \constfunc{wxList<T>::compatibility\_iterator}{Member}{\param{T *}{ object}}
 231
 232 {\bf NB:} This function is deprecated, use \helpref{Find}{wxlistfind} instead.
 233
 234 \membersection{wxList<T>::Nth}\label{wxlistnth}
 235
 236 \constfunc{wxList<T>::compatibility\_iterator}{Nth}{\param{int }{n}}
 237
 238 {\bf NB:} This function is deprecated, use \helpref{Item}{wxlistitemfunc} instead.
 239
 240 Returns the {\it nth} node in the list, indexing from zero (NULL if the list is empty
 241 or the nth node could not be found).
 242
 243 \membersection{wxList<T>::Number}\label{wxlistnumber}
 244
 245 \constfunc{int}{Number}{\void}
 246
 247 {\bf NB:} This function is deprecated, use \helpref{GetCount}{wxlistgetcount} instead.
 248
 249 Returns the number of elements in the list.
 250
 251 \membersection{wxList<T>::Sort}\label{wxlistsort}
 252
 253 \func{void}{Sort}{\param{wxSortCompareFunction}{ compfunc}}
 254
 255 \begin{verbatim}
 256   // Type of compare function for list sort operation (as in 'qsort')
 257   typedef int (*wxSortCompareFunction)(const void *elem1, const void *elem2);
 258 \end{verbatim}
 259
 260 Allows the sorting of arbitrary lists by giving a function to compare
 261 two list elements. We use the system {\bf qsort} function for the actual
 262 sorting process.
 263
 264
 265
 266 \membersection{wxList<T>::assign}\label{wxlistassign}
 267
 268 \func{void}{assign}{\param{const\_iterator }{first}, \param{const const\_iterator\& }{last}}
 269
 270
 271 \func{void}{assign}{\param{size\_type }{n}, \param{const\_reference }{v = value\_type()}}
 272
 273
 274 \membersection{wxList<T>::back}\label{wxlistback}
 275
 276 \func{reference}{back}{\void}
 277
 278 \constfunc{const\_reference}{back}{\void}
 279
 280 Returns the last item of the list.
 281
 282 \membersection{wxList<T>::begin}\label{wxlistbegin}
 283
 284 \func{iterator}{begin}{\void}
 285
 286 \constfunc{const\_iterator}{begin}{\void}
 287
 288 Returns a (const) iterator pointing to the beginning of the list.
 289
 290 \membersection{wxList<T>::clear}\label{wxlistclear}
 291
 292 \func{void}{clear}{\void}
 293
 294 Removes all items from the list.
 295
 296 \membersection{wxList<T>::empty}\label{wxlistempty}
 297
 298 \constfunc{bool}{empty}{\void}
 299
 300 Returns {\it true} if the list is empty.
 301
 302 \membersection{wxList<T>::end}\label{wxlistend}
 303
 304 \func{iterator}{end}{\void}
 305
 306 \constfunc{const\_iterator}{end}{\void}
 307
 308 Returns a (const) iterator pointing at the end of the list.
 309
 310 \membersection{wxList<T>::erase}\label{wxlisterase2}
 311
 312 \func{iterator}{erase}{\param{const iterator\& }{it}}
 313
 314 Erases the item pointed to by {\it it}.
 315
 316 \func{iterator}{erase}{\param{const iterator\& }{first}, \param{const iterator\& }{last}}
 317
 318 Erases the items from {\it first} to {\it last}.
 319
 320 \membersection{wxList<T>::front}\label{wxlistfront}
 321
 322 \func{reference}{front}{\void}
 323
 324 \constfunc{const\_reference}{front}{\void}
 325
 326 Returns the first item in the list.
 327
 328 \membersection{wxList<T>::insert}\label{wxlistinsert}
 329
 330 \func{iterator}{insert}{\param{const iterator\& }{it}, \param{const\_reference }{v = value\_type()}}
 331
 332 \func{void}{insert}{\param{const iterator\& }{it}, \param{size\_type }{n}, \param{const\_reference }{v = value\_type()}}
 333
 334 \func{void}{insert}{\param{const iterator\& }{it}, \param{const\_iterator }{first}, \param{const const\_iterator\& }{last}}
 335
 336 Inserts an item (or several) at the given position.
 337
 338 \membersection{wxList<T>::max\_size}\label{wxlistmaxsize}
 339
 340 \constfunc{size\_type}{max\_size}{\void}
 341
 342 Returns the largest possible size of the list.
 343
 344 \membersection{wxList<T>::pop\_back}\label{wxlistpopback}
 345
 346 \func{void}{pop\_back}{\void}
 347
 348 Removes the last item from the list.
 349
 350 \membersection{wxList<T>::pop\_front}\label{wxlistpopfront}
 351
 352 \func{void}{pop\_front}{\void}
 353
 354 Removes the first item from the list.
 355
 356 \membersection{wxList<T>::push\_back}\label{wxlistpushback}
 357
 358 \func{void}{push\_back}{\param{const\_reference }{v = value\_type()}}
 359
 360 Adds an item to end of the list.
 361
 362 \membersection{wxList<T>::push\_front}\label{wxlistpushfront}
 363
 364 \func{void}{push\_front}{\param{const\_reference }{v = value\_type()}}
 365
 366 Adds an item to the front of the list.
 367
 368 \membersection{wxList<T>::rbegin}\label{wxlistrbegin}
 369
 370 \func{reverse\_iterator}{rbegin}{\void}
 371
 372 \constfunc{const\_reverse\_iterator}{rbegin}{\void}
 373
 374 Returns a (const) reverse iterator pointing to the beginning of the
 375 reversed list.
 376
 377 \membersection{wxList<T>::remove}\label{wxlistremove}
 378
 379 \func{void}{remove}{\param{const\_reference }{v}}
 380
 381 Removes an item from the list.
 382
 383 \membersection{wxList<T>::rend}\label{wxlistrend}
 384
 385 \func{reverse\_iterator}{rend}{\void}
 386
 387 \constfunc{const\_reverse\_iterator}{rend}{\void}
 388
 389 Returns a (const) reverse iterator pointing to the end of the
 390 reversed list.
 391
 392 \membersection{wxList<T>::resize}\label{wxlistresize}
 393
 394 \func{void}{resize}{\param{size\_type }{n}, \param{value\_type }{v = value\_type()}}
 395
 396 Resizes the list. If the the list is enlarges items with
 397 the value {\it v} are appended to the list.
 398
 399 \membersection{wxList<T>::reverse}\label{wxlistreverse}
 400
 401 \func{void}{reverse}{\void}
 402
 403 Reverses the list.
 404
 405 \membersection{wxList<T>::size}\label{wxlistsize}
 406
 407 \constfunc{size\_type}{size}{\void}
 408
 409 Returns the size of the list.
 410
 411 \membersection{wxList<T>::splice}\label{wxlistsplice}
 412
 413 \func{void}{splice}{\param{const iterator\& }{it}, \param{wxList<T>\& }{l}}
 414
 415 \func{void}{splice}{\param{const iterator\& }{it}, \param{wxList<T>\& }{l}, \param{const iterator\& }{first}}
 416
 417 \func{void}{splice}{\param{const iterator\& }{it}, \param{wxList<T>\& }{l}, \param{const iterator\& }{first}, \param{const iterator\& }{last}}
 418
 419 Moves part of the list into another list, starting from {\it first} and
 420 ending at {\it last} if specified.