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