X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/1ac74d83a39abb3697745e0d494f28f4d27f3efd..c36cdfc084f779b67668af8cad3eb6906182af21:/docs/latex/wx/list.tex diff --git a/docs/latex/wx/list.tex b/docs/latex/wx/list.tex index 5144cf38d3..2d49800caf 100644 --- a/docs/latex/wx/list.tex +++ b/docs/latex/wx/list.tex @@ -9,31 +9,32 @@ %% License: wxWindows license %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\section{\class{wxList}}\label{wxlist} - -wxList classes provide linked list functionality for wxWidgets, and for an -application if it wishes. Depending on the form of constructor used, a list -can be keyed on integer or string keys to provide a primitive look-up ability, -but please note that this feature is {\bf deprecated}. -See \helpref{wxHashMap}{wxhashmap}\rtfsp for a faster method of storage -when random access is required. - -While wxList class in the previous versions of wxWidgets only could contain -elements of type wxObject and had essentially untyped interface (thus allowing -you to put apples in the list and read back oranges from it), the new wxList -classes family may contain elements of any type and has much more strict type -checking. Unfortunately, it also requires an additional line to be inserted in -your program for each list class you use (which is the only solution short of -using templates which is not done in wxWidgets because of portability issues). - -The general idea is to have the base class wxListBase working with {\it void *} -data but make all of its dangerous (because untyped) functions protected, so -that they can only be used from derived classes which, in turn, expose a type -safe interface. With this approach a new wxList-like class must be defined for -each list type (i.e. list of ints, of wxStrings or of MyObjects). This is done -with {\it WX\_DECLARE\_LIST} and {\it WX\_DEFINE\_LIST} macros like this -(notice the similarity with WX\_DECLARE\_OBJARRAY and WX\_IMPLEMENT\_OBJARRAY -macros): +\section{\class{wxList}}\label{wxlist} + +The wxList class provides linked list functionality. It has been written +to be type safe and to provide the full API of the STL std::list container and +should be used like it. The exception is that wxList actually stores +pointers and therefore its iterators return pointers and not references +to the actual objets in the list (see example below) and {\it value\_type} +is defined as {\it T*}. + + +Unfortunately, the +new wxList class requires that you declare and define each wxList +class in your program. This is done with {\it WX\_DECLARE\_LIST} and +{\it WX\_DEFINE\_LIST} macros (see example). We hope that we'll be able +to provide a proper template class providing both the STL std::list +and the old wxList API in the future. + +Please refer to the STL std::list documentation for further +information on how to use the class. Below we documented both +the supported STL and the legacy API that originated from the +old wxList class and which can still be used alternatively for +the the same class. + +Note that if you compile wxWidgets in STL mode (wxUSE\_STL defined as 1) +then wxList will actually derive from std::list and just add a legacy +compatibility layer for the old wxList class. \wxheading{Example} @@ -44,8 +45,7 @@ macros): ... // whatever }; - // declare our list class: this macro declares and partly implements MyList - // class (which derives from wxListBase) + // this macro declares and partly implements MyList class WX_DECLARE_LIST(MyListElement, MyList); ... @@ -57,21 +57,32 @@ macros): #include WX_DEFINE_LIST(MyList); - // now MyList class may be used as a usual wxList, but all of its methods - // will take/return the objects of the right (i.e. MyListElement) type. You - // also have MyList::Node type which is the type-safe version of wxNode. + MyList list; MyListElement element; list.Append(&element); // ok list.Append(17); // error: incorrect type - // let's iterate over the list - for ( MyList::Node *node = list.GetFirst(); node; node = node->GetNext() ) + // let's iterate over the list in STL syntax + MyList::iterator iter; + for (iter = list.begin(); iter != list.end(); ++iter) + { + MyListElement *current = *iter; + + ...process the current element... + } + + // the same with the legacy API from the old wxList class + MyList::compatibility_iterator node = list.GetFirst(); + while (node) { MyListElement *current = node->GetData(); ...process the current element... + + node = node->GetNext(); } + \end{verbatim} For compatibility with previous versions wxList and wxStringList classes are @@ -80,244 +91,164 @@ future versions completely. The use of the latter is especially discouraged as it is not only unsafe but is also much less efficient than \helpref{wxArrayString}{wxarraystring} class. -In the documentation of the list classes below, the template notations are -used even though these classes are not really templates at all -- but it helps -to think about them as if they were. You should replace wxNode with -wxListName::Node and T itself with the list element type (i.e. the first -parameter of WX\_DECLARE\_LIST). - -\wxheading{Derived from} - -\helpref{wxObject}{wxobject} - \wxheading{Include files} -\wxheading{Example} - -It is very common to iterate on a list as follows: - -\begin{verbatim} - ... - wxWindow *win1 = new wxWindow(...); - wxWindow *win2 = new wxWindow(...); - - wxList SomeList; - SomeList.Append(win1); - SomeList.Append(win2); - - ... - - wxNode *node = SomeList.GetFirst(); - while (node) - { - wxWindow *win = node->GetData(); - ... - node = node->GetNext(); - } -\end{verbatim} - -To delete nodes in a list as the list is being traversed, replace - -\begin{verbatim} - ... - node = node->GetNext(); - ... -\end{verbatim} - -with - -\begin{verbatim} - ... - delete win; - delete node; - node = SomeList.GetFirst(); - ... -\end{verbatim} +\wxheading{Library} -See \helpref{wxNode}{wxnode} for members that retrieve the data associated with a node, and -members for getting to the next or previous node. +\helpref{wxBase}{librarieslist} \wxheading{See also} -\helpref{wxNode}{wxnode}, -\helpref{wxArray}{wxarray} +\helpref{wxArray}{wxarray}, +\helpref{wxVector}{wxvector} \latexignore{\rtfignore{\wxheading{Members}}} -\membersection{wxList::wxList}\label{wxlistctor} - -\func{}{wxList}{\void} - -\func{}{wxList}{\param{int}{ n}, \param{T *}{objects[]}} - -\func{}{wxList}{\param{T *}{object}, ...} - -{\bf Note}: keyed lists are deprecated and should not be used in new code. +\membersection{wxList::wxList}\label{wxlistctor} -\func{}{wxList}{\param{unsigned int}{ key\_type}} +\func{}{wxList}{\void} -Constructors. {\it key\_type} is one of wxKEY\_NONE, wxKEY\_INTEGER, or wxKEY\_STRING, -and indicates what sort of keying is required (if any). +\func{}{wxList}{\param{size\_t}{ count}, \param{T *}{elements[]}} -{\it objects} is an array of {\it n} objects with which to initialize the list. +Constructors. -The variable-length argument list constructor must be supplied with a -terminating NULL. +\membersection{wxList::\destruct{wxList}}\label{wxlistdtor} -\membersection{wxList::\destruct{wxList}}\label{wxlistdtor} +\func{}{\destruct{wxList}}{\void} -\func{}{\destruct{wxList}}{\void} +Destroys the list, but does not delete the objects stored in the list +unless you called DeleteContents({\tt true} ). -Destroys the list. Also destroys any remaining nodes, but does not destroy -client data held in the nodes. +\membersection{wxList::Append}\label{wxlistappend} -\membersection{wxList::Append}\label{wxlistappend} +\func{wxList::compatibility\_iterator }{Append}{\param{T *}{object}} -\func{wxNode *}{Append}{\param{T *}{object}} +Appends the pointer to \rtfsp{\it object} to the list. -{\bf Note}: keyed lists are deprecated and should not be used in new code. - -\func{wxNode *}{Append}{\param{long}{ key}, \param{T *}{object}} - -\func{wxNode *}{Append}{\param{const wxString\& }{key}, \param{T *}{object}} - -Appends a new \helpref{wxNode}{wxnode} to the end of the list and puts a -pointer to the \rtfsp{\it object} in the node. The last two forms store a key -with the object for later retrieval using the key. The new node is returned in -each case. - -The key string is copied and stored by the list implementation. - -\membersection{wxList::Clear}\label{wxlistclear} +\membersection{wxList::Clear}\label{wxlistclear1} \func{void}{Clear}{\void} -Clears the list (but does not delete the client data stored with each node -unless you called DeleteContents({\tt true}), in which case it deletes data). +Clears the list, but does not delete the objects stored in the list +unless you called DeleteContents({\tt true} ). -\membersection{wxList::DeleteContents}\label{wxlistdeletecontents} +\membersection{wxList::DeleteContents}\label{wxlistdeletecontents} \func{void}{DeleteContents}{\param{bool}{ destroy}} -If {\it destroy} is {\tt true}, instructs the list to call {\it delete} on the client contents of -a node whenever the node is destroyed. The default is {\tt false}. +If {\it destroy} is {\tt true}, instructs the list to call {\it delete} +on objects stored in the list whenever they are removed. +The default is {\tt false}. -\membersection{wxList::DeleteNode}\label{wxlistdeletenode} +\membersection{wxList::DeleteNode}\label{wxlistdeletenode} -\func{bool}{DeleteNode}{\param{wxNode *}{node}} +\func{bool}{DeleteNode}{\param{const compatibility\_iterator &}{iter}} -Deletes the given node from the list, returning {\tt true} if successful. +Deletes the given element refered to by {\tt iter} from the list, +returning {\tt true} if successful. -\membersection{wxList::DeleteObject}\label{wxlistdeleteobject} +\membersection{wxList::DeleteObject}\label{wxlistdeleteobject} \func{bool}{DeleteObject}{\param{T *}{object}} -Finds the given client {\it object} and deletes the appropriate node from the list, returning -{\tt true} if successful. The application must delete the actual object separately. - -\membersection{wxList::Erase}\label{wxlisterase} - -\func{void}{Erase}{\param{wxNode *}{node}} - -Removes element at given position. +Finds the given {\it object} and removes it from the list, returning +{\tt true} if successful. The application must delete the actual object +separately. -\membersection{wxList::Find}\label{wxlistfind} +\membersection{wxList::Erase}\label{wxlisterase} -\func{wxNode *}{Find}{\param{T *}{ object}} +\func{void}{Erase}{\param{const compatibility\_iterator &}{iter}} -Returns the node whose client data is {\it object} or NULL if none found. +Removes element refered to be {\tt iter}. -{\bf Note}: keyed lists are deprecated and should not be used in new code. +\membersection{wxList::Find}\label{wxlistfind} -\func{wxNode *}{Find}{\param{long}{ key}} +\constfunc{wxList::compatibility\_iterator}{Find}{\param{T *}{ object}} -\func{wxNode *}{Find}{\param{const wxString\& }{key}} +Returns the iterator refering to {\it object} or NULL if none found. -Returns the node whose stored key matches {\it key}. Use on a keyed list only. - -\membersection{wxList::GetCount}\label{wxlistgetcount} +\membersection{wxList::GetCount}\label{wxlistgetcount} \constfunc{size\_t}{GetCount}{\void} Returns the number of elements in the list. -\membersection{wxList::GetFirst}\label{wxlistgetfirst} +\membersection{wxList::GetFirst}\label{wxlistgetfirst} -\func{wxNode *}{GetFirst}{\void} +\constfunc{wxList::compatibility\_iterator}{GetFirst}{\void} -Returns the first node in the list (NULL if the list is empty). +Returns the first iterator in the list (NULL if the list is empty). -\membersection{wxList::GetLast}\label{wxlistgetlast} +\membersection{wxList::GetLast}\label{wxlistgetlast} -\func{wxNode *}{GetLast}{\void} +\constfunc{wxList::compatibility\_iterator}{GetLast}{\void} -Returns the last node in the list (NULL if the list is empty). +Returns the last iterator in the list (NULL if the list is empty). -\membersection{wxList::IndexOf}\label{wxlistindexof} +\membersection{wxList::IndexOf}\label{wxlistindexof} -\func{int}{IndexOf}{\param{T*}{ obj }} +\constfunc{int}{IndexOf}{\param{T*}{ obj }} -Returns the index of {\it obj} within the list or {\tt wxNOT\_FOUND} if {\it obj} -is not found in the list. +Returns the index of {\it obj} within the list or {\tt wxNOT\_FOUND} if +{\it obj} is not found in the list. -\membersection{wxList::Insert}\label{wxlistinsert} +\membersection{wxList::Insert}\label{wxlistinsert1} -\func{wxNode *}{Insert}{\param{T *}{object}} +\func{wxList::compatibility\_iterator}{Insert}{\param{T *}{object}} -Insert object at front of list. +Insert object at the front of list. -\func{wxNode *}{Insert}{\param{size\_t }{position}, \param{T *}{object}} +\func{wxList::compatibility\_iterator}{Insert}{\param{size\_t }{position}, \param{T *}{object}} Insert object before {\it position}, i.e. the index of the new item in the list will be equal to {\it position}. {\it position} should be less than or equal to \helpref{GetCount}{wxlistgetcount}; if it is equal to it, this is the same as calling \helpref{Append}{wxlistappend}. -\func{wxNode *}{Insert}{\param{wxNode *}{node}, \param{T *}{object}} +\func{wxList::compatibility\_iterator}{Insert}{\param{compatibility\_iterator}{iter}, \param{T *}{object}} -Inserts the object before the given {\it node}. +Inserts the object before the object refered to be {\it iter}. -\membersection{wxList::IsEmpty}\label{wxlistisempty} +\membersection{wxList::IsEmpty}\label{wxlistisempty} \constfunc{bool}{IsEmpty}{\void} Returns {\tt true} if the list is empty, {\tt false} otherwise. % Use different label name to avoid clashing with wxListItem label -\membersection{wxList::Item}\label{wxlistitemfunc} +\membersection{wxList::Item}\label{wxlistitemfunc} -\constfunc{wxNode *}{Item}{\param{size\_t }{index}} +\constfunc{wxList::compatibility\_iterator}{Item}{\param{size\_t }{index}} -Returns the node at given position in the list. +Returns the iterator refering to the object at the given +{\tt index} in the list. -\membersection{wxList::Member}\label{wxlistmember} +\membersection{wxList::Member}\label{wxlistmember} -\func{wxNode *}{Member}{\param{T *}{object}} +\constfunc{wxList::compatibility\_iterator}{Member}{\param{T *}{ object}} {\bf NB:} This function is deprecated, use \helpref{Find}{wxlistfind} instead. -Returns the node associated with {\it object} if it is in the list, NULL otherwise. - -\membersection{wxList::Nth}\label{wxlistnth} +\membersection{wxList::Nth}\label{wxlistnth} -\func{wxNode *}{Nth}{\param{int}{ n}} +\constfunc{wxList::compatibility\_iterator}{Nth}{\param{int }{n}} {\bf NB:} This function is deprecated, use \helpref{Item}{wxlistitemfunc} instead. Returns the {\it nth} node in the list, indexing from zero (NULL if the list is empty or the nth node could not be found). -\membersection{wxList::Number}\label{wxlistnumber} +\membersection{wxList::Number}\label{wxlistnumber} -\func{int}{Number}{\void} +\constfunc{int}{Number}{\void} {\bf NB:} This function is deprecated, use \helpref{GetCount}{wxlistgetcount} instead. Returns the number of elements in the list. -\membersection{wxList::Sort}\label{wxlistsort} +\membersection{wxList::Sort}\label{wxlistsort} \func{void}{Sort}{\param{wxSortCompareFunction}{ compfunc}} @@ -326,31 +257,164 @@ Returns the number of elements in the list. typedef int (*wxSortCompareFunction)(const void *elem1, const void *elem2); \end{verbatim} -Allows the sorting of arbitrary lists by giving -a function to compare two list elements. We use the system {\bf qsort} function -for the actual sorting process. +Allows the sorting of arbitrary lists by giving a function to compare +two list elements. We use the system {\bf qsort} function for the actual +sorting process. -If you use untyped wxList the sort function receives pointers to wxObject -pointers (wxObject **), so be careful to dereference appropriately - but, -of course, a better solution is to use list of appropriate type defined with -{\tt WX\_DECLARE\_LIST}. -Example: -\begin{verbatim} - int listcompare(const void *arg1, const void *arg2) - { - return(compare(**(wxString **)arg1, // use the wxString 'compare' - **(wxString **)arg2)); // function - } - - void main() - { - wxList list; - - list.Append(new wxString("DEF")); - list.Append(new wxString("GHI")); - list.Append(new wxString("ABC")); - list.Sort(listcompare); - } -\end{verbatim} +\membersection{wxList::assign}\label{wxlistassign} + +\func{void}{assign}{\param{const\_iterator }{first}, \param{const const\_iterator\& }{last}} + + +\func{void}{assign}{\param{size\_type }{n}, \param{const\_reference }{v = value\_type()}} + + +\membersection{wxList::back}\label{wxlistback} + +\func{reference}{back}{\void} + +\constfunc{const\_reference}{back}{\void} + +Returns the last item of the list. + +\membersection{wxList::begin}\label{wxlistbegin} + +\func{iterator}{begin}{\void} + +\constfunc{const\_iterator}{begin}{\void} + +Returns a (const) iterator pointing to the beginning of the list. + +\membersection{wxList::clear}\label{wxlistclear} + +\func{void}{clear}{\void} + +Removes all items from the list. + +\membersection{wxList::empty}\label{wxlistempty} + +\constfunc{bool}{empty}{\void} + +Returns {\it true} if the list is empty. + +\membersection{wxList::end}\label{wxlistend} + +\func{iterator}{end}{\void} + +\constfunc{const\_iterator}{end}{\void} + +Returns a (const) iterator pointing at the end of the list. + +\membersection{wxList::erase}\label{wxlisterase2} + +\func{iterator}{erase}{\param{const iterator\& }{it}} + +Erases the item pointed to by {\it it}. + +\func{iterator}{erase}{\param{const iterator\& }{first}, \param{const iterator\& }{last}} + +Erases the items from {\it first} to {\it last}. + +\membersection{wxList::front}\label{wxlistfront} + +\func{reference}{front}{\void} + +\constfunc{const\_reference}{front}{\void} + +Returns the first item in the list. + +\membersection{wxList::insert}\label{wxlistinsert} + +\func{iterator}{insert}{\param{const iterator\& }{it}, \param{const\_reference }{v = value\_type()}} + +\func{void}{insert}{\param{const iterator\& }{it}, \param{size\_type }{n}, \param{const\_reference }{v = value\_type()}} + +\func{void}{insert}{\param{const iterator\& }{it}, \param{const\_iterator }{first}, \param{const const\_iterator\& }{last}} + +Inserts an item (or several) at the given position. + +\membersection{wxList::max\_size}\label{wxlistmaxsize} + +\constfunc{size\_type}{max\_size}{\void} + +Returns the largest possible size of the list. + +\membersection{wxList::pop\_back}\label{wxlistpopback} + +\func{void}{pop\_back}{\void} + +Removes the last item from the list. + +\membersection{wxList::pop\_front}\label{wxlistpopfront} + +\func{void}{pop\_front}{\void} + +Removes the first item from the list. + +\membersection{wxList::push\_back}\label{wxlistpushback} + +\func{void}{push\_back}{\param{const\_reference }{v = value\_type()}} + +Adds an item to end of the list. + +\membersection{wxList::push\_front}\label{wxlistpushfront} + +\func{void}{push\_front}{\param{const\_reference }{v = value\_type()}} + +Adds an item to the front of the list. + +\membersection{wxList::rbegin}\label{wxlistrbegin} + +\func{reverse\_iterator}{rbegin}{\void} + +\constfunc{const\_reverse\_iterator}{rbegin}{\void} + +Returns a (const) reverse iterator pointing to the beginning of the +reversed list. + +\membersection{wxList::remove}\label{wxlistremove} + +\func{void}{remove}{\param{const\_reference }{v}} + +Removes an item from the list. + +\membersection{wxList::rend}\label{wxlistrend} + +\func{reverse\_iterator}{rend}{\void} + +\constfunc{const\_reverse\_iterator}{rend}{\void} + +Returns a (const) reverse iterator pointing to the end of the +reversed list. + +\membersection{wxList::resize}\label{wxlistresize} + +\func{void}{resize}{\param{size\_type }{n}, \param{value\_type }{v = value\_type()}} + +Resizes the list. If the the list is enlarges items with +the value {\it v} are appended to the list. + +\membersection{wxList::reverse}\label{wxlistreverse} + +\func{void}{reverse}{\void} + +Reverses the list. + +\membersection{wxList::size}\label{wxlistsize} + +\constfunc{size\_type}{size}{\void} + +Returns the size of the list. + +\membersection{wxList::splice}\label{wxlistsplice} + +\func{void}{splice}{\param{const iterator\& }{it}, \param{wxList\& }{l}} + +\func{void}{splice}{\param{const iterator\& }{it}, \param{wxList\& }{l}, \param{const iterator\& }{first}} + +\func{void}{splice}{\param{const iterator\& }{it}, \param{wxList\& }{l}, \param{const iterator\& }{first}, \param{const iterator\& }{last}} + +Moves part of the list into another list, starting from {\it first} and +ending at {\it last} if specified.