escape underscores introduced by the last change

[wxWidgets.git] / docs / latex / wx / list.tex

diff --git a/docs/latex/wx/list.tex b/docs/latex/wx/list.tex
index 8cdcdf03f81fa30caf4bfb717b3da8b50885f727..2d49800cafa23b28fe80f51b09ea21111ca46d20 100644 (file)
--- a/docs/latex/wx/list.tex
+++ b/docs/latex/wx/list.tex
@@ -1,31 +1,43 @@
-\section{\class{wxList}}\label{wxlist}
-
-wxList classes provide linked list functionality for wxWindows, 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.
-See \helpref{wxHashTable}{wxhashtable}\rtfsp for a faster method of storage
-when random access is required.
-
-While wxList class in the previous versions of wxWindows 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 stricter 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 wxWindows 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\_IMPLEMENT\_LIST} macros like this
-(notice the similarity with WX\_DECLARE\_OBJARRAY and WX\_IMPLEMENT\_OBJARRAY
-macros):
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name:        list.tex
+%% Purpose:     wxList
+%% Author:      wxWidgets Team
+%% Modified by:
+%% Created:
+%% RCS-ID:      $Id$
+%% Copyright:   (c) wxWidgets Team
+%% License:     wxWindows license
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{\class{wxList<T>}}\label{wxlist}
+
+The wxList<T> 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<T> 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<T> class requires that you declare and define each wxList<T>
+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<T> will actually derive from std::list and just add a legacy 
+compatibility layer for the old wxList class.

 
 \wxheading{Example}
 
 
 \wxheading{Example}
 

-{\small%

 \begin{verbatim}
     // this part might be in a header or source (.cpp) file
     class MyListElement
 \begin{verbatim}
     // this part might be in a header or source (.cpp) file
     class MyListElement


@@ -33,228 +45,210 @@ macros):
         ... // whatever
     };
 
         ... // 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);
 
     ...
 
     WX_DECLARE_LIST(MyListElement, MyList);
 
     ...
 

-    // the only requirment for the rest is to be AFTER the full declaration of
+    // the only requirement for the rest is to be AFTER the full declaration of

     // MyListElement (for WX_DECLARE_LIST forward declaration is enough), but
     // usually it will be found in the source file and not in the header
 
     #include <wx/listimpl.cpp>
     WX_DEFINE_LIST(MyList);
 
     // MyListElement (for WX_DECLARE_LIST forward declaration is enough), but
     // usually it will be found in the source file and not in the header
 
     #include <wx/listimpl.cpp>
     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;
     MyList list;
     MyListElement element;

-    list.Add(element);      // ok
-    list.Add(17);           // error: incorrect type
+    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...
     {
         MyListElement *current = node->GetData();
 
         ...process the current element...

+        
+        node = node->GetNext();

     }
     }

+

 \end{verbatim}
 \end{verbatim}

-}

 
 For compatibility with previous versions wxList and wxStringList classes are
 still defined, but their usage is deprecated and they will disappear in the
 
 For compatibility with previous versions wxList and wxStringList classes are
 still defined, but their usage is deprecated and they will disappear in the

-future versions completely.
-
-\wxheading{Derived from}
-
-\helpref{wxObject}{wxobject}
+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.

 
 \wxheading{Include files}
 
 <wx/list.h>
 
 
 \wxheading{Include files}
 
 <wx/list.h>
 

-\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);
+\wxheading{Library}

 
 

-  ...
+\helpref{wxBase}{librarieslist}

 
 

-  wxNode *node = SomeList.GetFirst();
-  while (node)
-  {
-    wxWindow *win = (wxWindow *)node->Data();
-    ...
-    node = node->Next();
-  }
-\end{verbatim}
-
-To delete nodes in a list as the list is being traversed, replace
+\wxheading{See also}

 
 

-\begin{verbatim}
-    ...
-    node = node->Next();
-    ...
-\end{verbatim}
+\helpref{wxArray<T>}{wxarray},
+\helpref{wxVector<T>}{wxvector}

 
 

-with
+\latexignore{\rtfignore{\wxheading{Members}}}

 
 

-\begin{verbatim}
-    ...
-    delete win;
-    delete node;
-    node = SomeList.GetFirst();
-    ...
-\end{verbatim}
+\membersection{wxList<T>::wxList<T>}\label{wxlistctor}

 
 

-See \helpref{wxNode}{wxnode} for members that retrieve the data associated with a node, and
-members for getting to the next or previous node.
+\func{}{wxList<T>}{\void}

 
 

-Note that a cast is required when retrieving the data from a node.  Although a
-node is defined to store objects of type {\bf wxObject} and derived types, other
-types (such as char*) may be used with appropriate casting.
+\func{}{wxList<T>}{\param{size\_t}{ count}, \param{T *}{elements[]}}

 
 

-\wxheading{See also}
+Constructors.

 
 

-\helpref{wxNode}{wxnode}, \helpref{wxStringList}{wxstringlist},
-\helpref{wxArray}{wxarray}
+\membersection{wxList<T>::\destruct{wxList<T>}}\label{wxlistdtor}

 
 

-\latexignore{\rtfignore{\wxheading{Members}}}
+\func{}{\destruct{wxList<T>}}{\void}

 
 

-\membersection{wxList::wxList}
+Destroys the list, but does not delete the objects stored in the list
+unless you called DeleteContents({\tt true} ).

 
 

-\func{}{wxList}{\void}
+\membersection{wxList<T>::Append}\label{wxlistappend}

 
 

-\func{}{wxList}{\param{unsigned int}{ key\_type}}
+\func{wxList<T>::compatibility\_iterator }{Append}{\param{T *}{object}}

 
 

-\func{}{wxList}{\param{int}{ n}, \param{wxObject *}{objects[]}}
+Appends the pointer to \rtfsp{\it object} to the list.

 
 

-\func{}{wxList}{\param{wxObject *}{object}, ...}
+\membersection{wxList<T>::Clear}\label{wxlistclear1}

 
 

-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{void}{Clear}{\void}

 
 

-{\it objects} is an array of {\it n} objects with which to initialize the list.
+Clears the list, but does not delete the objects stored in the list
+unless you called DeleteContents({\tt true} ).

 
 

-The variable-length argument list constructor must be supplied with a
-terminating NULL.
+\membersection{wxList<T>::DeleteContents}\label{wxlistdeletecontents}

 
 

-\membersection{wxList::\destruct{wxList}}
+\func{void}{DeleteContents}{\param{bool}{ destroy}}

 
 

-\func{}{\destruct{wxList}}{\void}
+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}.

 
 

-Destroys the list.  Also destroys any remaining nodes, but does not destroy
-client data held in the nodes.
+\membersection{wxList<T>::DeleteNode}\label{wxlistdeletenode}

 
 

-\membersection{wxList::Append}
+\func{bool}{DeleteNode}{\param{const compatibility\_iterator &}{iter}}

 
 

-\func{wxNode *}{Append}{\param{wxObject *}{object}}
+Deletes the given element refered to by {\tt iter} from the list, 
+returning {\tt true} if successful.

 
 

-\func{wxNode *}{Append}{\param{long}{ key}, \param{wxObject *}{object}}
+\membersection{wxList<T>::DeleteObject}\label{wxlistdeleteobject}

 
 

-\func{wxNode *}{Append}{\param{const wxString\& }{key}, \param{wxObject *}{object}}
+\func{bool}{DeleteObject}{\param{T *}{object}}

 
 

-Appends a new {\bf 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.
+Finds the given {\it object} and removes it from the list, returning
+{\tt true} if successful. The application must delete the actual object
+separately.

 
 

-The key string is copied and stored by the list implementation.
+\membersection{wxList<T>::Erase}\label{wxlisterase}

 
 

-\membersection{wxList::Clear}
+\func{void}{Erase}{\param{const compatibility\_iterator &}{iter}}

 
 

-\func{void}{Clear}{\void}
+Removes element refered to be {\tt iter}.

 
 

-Clears the list (but does not delete the client data stored with each node).
+\membersection{wxList<T>::Find}\label{wxlistfind}

 
 

-\membersection{wxList::DeleteContents}\label{wxlistdeletecontents}
+\constfunc{wxList<T>::compatibility\_iterator}{Find}{\param{T *}{ object}}

 
 

-\func{void}{DeleteContents}{\param{bool}{ destroy}}
+Returns the iterator refering to {\it object} or NULL if none found.

 
 

-If {\it destroy} is TRUE, instructs the list to call {\it delete} on the client contents of
-a node whenever the node is destroyed. The default is FALSE.
+\membersection{wxList<T>::GetCount}\label{wxlistgetcount}

 
 

-\membersection{wxList::DeleteNode}
+\constfunc{size\_t}{GetCount}{\void}

 
 

-\func{bool}{DeleteNode}{\param{wxNode *}{node}}
+Returns the number of elements in the list.

 
 

-Deletes the given node from the list, returning TRUE if successful.
+\membersection{wxList<T>::GetFirst}\label{wxlistgetfirst}

 
 

-\membersection{wxList::DeleteObject}
+\constfunc{wxList<T>::compatibility\_iterator}{GetFirst}{\void}

 
 

-\func{bool}{DeleteObject}{\param{wxObject *}{object}}
+Returns the first iterator in the list (NULL if the list is empty).

 
 

-Finds the given client {\it object} and deletes the appropriate node from the list, returning
-TRUE if successful. The application must delete the actual object separately.
+\membersection{wxList<T>::GetLast}\label{wxlistgetlast}

 
 

-\membersection{wxList::Find}
+\constfunc{wxList<T>::compatibility\_iterator}{GetLast}{\void}

 
 

-\func{wxNode *}{Find}{\param{long}{ key}}
+Returns the last iterator in the list (NULL if the list is empty).

 
 

-\func{wxNode *}{Find}{\param{const wxString\& }{key}}
+\membersection{wxList<T>::IndexOf}\label{wxlistindexof}

 
 

-Returns the node whose stored key matches {\it key}. Use on a keyed list only.
+\constfunc{int}{IndexOf}{\param{T*}{ obj }}

 
 

-\membersection{wxList::GetFirst}
+Returns the index of {\it obj} within the list or {\tt wxNOT\_FOUND} if
+{\it obj} is not found in the list.

 
 

-\func{wxNode *}{GetFirst}{\void}
+\membersection{wxList<T>::Insert}\label{wxlistinsert1}

 
 

-Returns the first node in the list (NULL if the list is empty).
+\func{wxList<T>::compatibility\_iterator}{Insert}{\param{T *}{object}}

 
 

-\membersection{wxList::IndexOf}
+Insert object at the front of list.

 
 

-\func{int}{IndexOf}{\param{wxObject*}{ obj }}
+\func{wxList<T>::compatibility\_iterator}{Insert}{\param{size\_t }{position}, \param{T *}{object}}

 
 

-Returns the index of {\it obj} within the list or NOT\_FOUND if {\it obj} 
-is not found in the list.
+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}.

 
 

-\membersection{wxList::Insert}
+\func{wxList<T>::compatibility\_iterator}{Insert}{\param{compatibility\_iterator}{iter}, \param{T *}{object}}

 
 

-\func{wxNode *}{Insert}{\param{wxObject *}{object}}
+Inserts the object before the object refered to be {\it iter}.

 
 

-Insert object at front of list.
+\membersection{wxList<T>::IsEmpty}\label{wxlistisempty}

 
 

-\func{wxNode *}{Insert}{\param{wxNode *}{position}, \param{wxObject *}{object}}
+\constfunc{bool}{IsEmpty}{\void}

 
 

-Insert object before {\it position}.
+Returns {\tt true} if the list is empty, {\tt false} otherwise.

 
 

+% Use different label name to avoid clashing with wxListItem label
+\membersection{wxList<T>::Item}\label{wxlistitemfunc}

 
 

-\membersection{wxList::GetLast}
+\constfunc{wxList<T>::compatibility\_iterator}{Item}{\param{size\_t }{index}}

 
 

-\func{wxNode *}{GetLast}{\void}
+Returns the iterator refering to the object at the given
+{\tt index} in the list.

 
 

-Returns the last node in the list (NULL if the list is empty).
+\membersection{wxList<T>::Member}\label{wxlistmember}

 
 

-\membersection{wxList::Member}
+\constfunc{wxList<T>::compatibility\_iterator}{Member}{\param{T *}{ object}}

 
 

-\func{wxNode *}{Member}{\param{wxObject *}{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<T>::Nth}\label{wxlistnth}

 
 

-\membersection{wxList::Nth}
+\constfunc{wxList<T>::compatibility\_iterator}{Nth}{\param{int }{n}}

 
 

-\func{wxNode *}{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).
 
 
 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}
+\membersection{wxList<T>::Number}\label{wxlistnumber}
+
+\constfunc{int}{Number}{\void}

 
 

-\func{int}{Number}{\void}
+{\bf NB:} This function is deprecated, use \helpref{GetCount}{wxlistgetcount} instead.

 
 Returns the number of elements in the list.
 
 
 Returns the number of elements in the list.
 

-\membersection{wxList::Sort}
+\membersection{wxList<T>::Sort}\label{wxlistsort}

 
 \func{void}{Sort}{\param{wxSortCompareFunction}{ compfunc}}
 
 
 \func{void}{Sort}{\param{wxSortCompareFunction}{ compfunc}}
 


@@ -263,29 +257,164 @@ Returns the number of elements in the list.
   typedef int (*wxSortCompareFunction)(const void *elem1, const void *elem2);
 \end{verbatim}
 
   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. The sort function receives pointers to wxObject pointers (wxObject **),
-so be careful to dereference appropriately.
+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.

 
 

-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<T>::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<T>::back}\label{wxlistback}
+
+\func{reference}{back}{\void}
+
+\constfunc{const\_reference}{back}{\void}
+
+Returns the last item of the list.
+
+\membersection{wxList<T>::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<T>::clear}\label{wxlistclear}
+
+\func{void}{clear}{\void}
+
+Removes all items from the list.
+
+\membersection{wxList<T>::empty}\label{wxlistempty}
+
+\constfunc{bool}{empty}{\void}
+
+Returns {\it true} if the list is empty.
+
+\membersection{wxList<T>::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<T>::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<T>::front}\label{wxlistfront}
+
+\func{reference}{front}{\void}
+
+\constfunc{const\_reference}{front}{\void}
+
+Returns the first item in the list.
+
+\membersection{wxList<T>::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<T>::max\_size}\label{wxlistmaxsize}
+
+\constfunc{size\_type}{max\_size}{\void}
+
+Returns the largest possible size of the list.
+
+\membersection{wxList<T>::pop\_back}\label{wxlistpopback}
+
+\func{void}{pop\_back}{\void}
+
+Removes the last item from the list.
+
+\membersection{wxList<T>::pop\_front}\label{wxlistpopfront}
+
+\func{void}{pop\_front}{\void}
+
+Removes the first item from the list.
+
+\membersection{wxList<T>::push\_back}\label{wxlistpushback}
+
+\func{void}{push\_back}{\param{const\_reference }{v = value\_type()}}
+
+Adds an item to end of the list.
+
+\membersection{wxList<T>::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<T>::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<T>::remove}\label{wxlistremove}
+
+\func{void}{remove}{\param{const\_reference }{v}}
+
+Removes an item from the list.
+
+\membersection{wxList<T>::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<T>::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<T>::reverse}\label{wxlistreverse}
+
+\func{void}{reverse}{\void}
+
+Reverses the list.
+
+\membersection{wxList<T>::size}\label{wxlistsize}
+
+\constfunc{size\_type}{size}{\void}
+
+Returns the size of the list.
+
+\membersection{wxList<T>::splice}\label{wxlistsplice}
+
+\func{void}{splice}{\param{const iterator\& }{it}, \param{wxList<T>\& }{l}}
+
+\func{void}{splice}{\param{const iterator\& }{it}, \param{wxList<T>\& }{l}, \param{const iterator\& }{first}}
+
+\func{void}{splice}{\param{const iterator\& }{it}, \param{wxList<T>\& }{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.