Chnaged includes to work without precompiled headers

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

diff --git a/docs/latex/wx/arrstrng.tex b/docs/latex/wx/arrstrng.tex
index e41d6102ed304bfb19dd21cf8cb425b8d076facd..dc15f1dd0f0c0c15c79e82d931f28abe2613dc82 100644 (file)
--- a/docs/latex/wx/arrstrng.tex
+++ b/docs/latex/wx/arrstrng.tex
@@ -3,9 +3,9 @@
 wxArrayString is an efficient container for storing 
 \helpref{wxString}{wxstring} objects. It has the same features as all 
 \helpref{wxArray}{wxarray} classes, i.e. it dynamically expands when new items
 wxArrayString is an efficient container for storing 
 \helpref{wxString}{wxstring} objects. It has the same features as all 
 \helpref{wxArray}{wxarray} classes, i.e. it dynamically expands when new items

-are added to it (so it is as easy to sue as a linked list), but the access
-time to the elements is constant (instead of being linear in number of
-elements as in the case of linked lists). It is also very size efficient and
+are added to it (so it is as easy to use as a linked list), but the access
+time to the elements is constant, instead of being linear in number of
+elements as in the case of linked lists. It is also very size efficient and

 doesn't take more space than a C array {\it wxString[]} type (wxArrayString
 uses its knowledge of internals of wxString class to achieve this).
 
 doesn't take more space than a C array {\it wxString[]} type (wxArrayString
 uses its knowledge of internals of wxString class to achieve this).
 


@@ -26,10 +26,20 @@ array elements may be modified in place like this
     array.Last().MakeUpper();
 \end{verbatim}
 
     array.Last().MakeUpper();
 \end{verbatim}
 

-Finally, none of the methods of this class is virtual including its
-destructor, so this class should not be derived from.
+There is also a varian of wxArrayString called wxSortedArrayString which has
+exactly the same methods as wxArrayString, but which always keeps the string
+in it in (alphabetical) order. wxSortedArrayString uses binary search in its 
+\helpref{Index}{wxarraystringindex} function (insteadf of linear search for
+wxArrayString::Index) which makes it much more efficient if you add strings to
+the array rarely (because, of course, you have to pay for Index() efficiency
+by having Add() be slower) but search for them often. Several methods should
+not be used with sorted array (basicly, all which break the order of items)
+which is mentioned in their description.

 
 

-\wxheading{Specialization of}
+Final word: none of the methods of wxArrayString is virtual including its
+destructor, so this class should not be used as a base class.
+
+\wxheading{Derived from}

 
 Although this is not true strictly speaking, this class may be considered as a
 specialization of \helpref{wxArray}{wxarray} class for the wxString member
 
 Although this is not true strictly speaking, this class may be considered as a
 specialization of \helpref{wxArray}{wxarray} class for the wxString member


@@ -42,8 +52,7 @@ functions.
 
 \wxheading{See also}
 
 
 \wxheading{See also}
 

-\helpref{wxArray}{wxarray}, \helpref{wxString}{wxstring}, \helpref{wxString
-overview}{wxstringoverview}
+\helpref{wxArray}{wxarray}, \helpref{wxString}{wxstring}, \helpref{wxString overview}{wxstringoverview}

 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 


@@ -55,6 +64,9 @@ overview}{wxstringoverview}
 
 Default and copy constructors.
 
 
 Default and copy constructors.
 

+Note that when an array is assigned to a sorted array, its contents is
+automatically sorted during construction.
+

 \membersection{wxArrayString::\destruct{wxArrayString}}\label{wxarraystringdtor}
 
 \func{}{\destruct{wxArrayString}}{}
 \membersection{wxArrayString::\destruct{wxArrayString}}\label{wxarraystringdtor}
 
 \func{}{\destruct{wxArrayString}}{}


@@ -70,7 +82,7 @@ Assignment operator.
 
 \membersection{wxArrayString::operator[]}\label{wxarraystringoperatorindex}
 
 
 \membersection{wxArrayString::operator[]}\label{wxarraystringoperatorindex}
 

-\func{wxString\&}{operatorp[]}{\param{size\_t }{nIndex}}
+\func{wxString\&}{operator[]}{\param{size\_t }{nIndex}}

 
 Return the array element at position {\it nIndex}. An assert failure will
 result from an attempt to access an element beyond the end of array in debug
 
 Return the array element at position {\it nIndex}. An assert failure will
 result from an attempt to access an element beyond the end of array in debug


@@ -80,9 +92,15 @@ This is the operator version of \helpref{Item}{wxarraystringitem} method.
 
 \membersection{wxArrayString::Add}\label{wxarraystringadd}
 
 
 \membersection{wxArrayString::Add}\label{wxarraystringadd}
 

-\func{void}{Add}{\param{const wxString\& }{str}}
+\func{size\_t}{Add}{\param{const wxString\& }{str}}
+
+Appends a new item to the array and return the index of th new item in the
+array.

 
 

-Appends a new item to the array.
+{\bf Warning:} For sorted arrays, the index of the inserted item will not be,
+in general, equal to \helpref{GetCount()}{wxarraystringgetcount} - 1 because
+the item is inserted at the correct position to keep the array sorted and not
+appended.

 
 See also: \helpref{Insert}{wxarraystringinsert}
 
 
 See also: \helpref{Insert}{wxarraystringinsert}
 


@@ -137,6 +155,10 @@ Search the element in the array, starting from the beginning if
 {\it bFromEnd} is FALSE or from end otherwise. If {\it bCase}, comparison is
 case sensitive (default), otherwise the case is ignored.
 
 {\it bFromEnd} is FALSE or from end otherwise. If {\it bCase}, comparison is
 case sensitive (default), otherwise the case is ignored.
 

+This function uses linear search for wxArrayString and binary search for
+wxSortedArrayString, but it ignores the {\it bCase} and {\it bFromEnd} 
+parameters in the latter case.
+

 Returns index of the first item matched or wxNOT\_FOUND if there is no match.
 
 \membersection{wxArrayString::Insert}\label{wxarraystringinsert}
 Returns index of the first item matched or wxNOT\_FOUND if there is no match.
 
 \membersection{wxArrayString::Insert}\label{wxarraystringinsert}


@@ -153,6 +175,10 @@ Insert("foo", 0);
 If {\it nIndex} is equal to {\it GetCount() + 1} this function behaves as 
 \helpref{Add}{wxarraystringadd}.
 
 If {\it nIndex} is equal to {\it GetCount() + 1} this function behaves as 
 \helpref{Add}{wxarraystringadd}.
 

+{\bf Warning:} this function should not be used with sorted arrays because it
+could break the order of items and, for example, subsequent calls to 
+\helpref{Index()}{wxarraystringindex} would then not work!
+

 \membersection{wxArrayString::IsEmpty}\label{wxarraystringisempty}
 
 \func{}{IsEmpty}{}
 \membersection{wxArrayString::IsEmpty}\label{wxarraystringisempty}
 
 \func{}{IsEmpty}{}


@@ -209,9 +235,13 @@ See also: \helpref{Alloc}{wxarraystringalloc}, \helpref{Dynamic array memory man
 
 \func{void}{Sort}{\param{bool}{ reverseOrder = FALSE}}
 
 
 \func{void}{Sort}{\param{bool}{ reverseOrder = FALSE}}
 

-Sorts the array in alphabetical order or in reverse alphabetical order if
+Sorts the array in alphabetical order or in reverse alphabetical order if 

 {\it reverseOrder} is TRUE.
 
 {\it reverseOrder} is TRUE.
 

+{\bf Warning:} this function should not be used with sorted array because it
+could break the order of items and, for example, subsequent calls to 
+\helpref{Index()}{wxarraystringindex} would then not work!
+

 See also: \helpref{Sort}{wxarraystringsortcallback}
 
 \membersection{wxArrayString::Sort (user defined)}\label{wxarraystringsortcallback}
 See also: \helpref{Sort}{wxarraystringsortcallback}
 
 \membersection{wxArrayString::Sort (user defined)}\label{wxarraystringsortcallback}


@@ -220,14 +250,15 @@ See also: \helpref{Sort}{wxarraystringsortcallback}
 
 Sorts the array using the specified {\it compareFunction} for item comparison.
 {\it CompareFunction} is defined as a function taking two {\it const
 
 Sorts the array using the specified {\it compareFunction} for item comparison.
 {\it CompareFunction} is defined as a function taking two {\it const

-wxString\&} parameters and returning {\it int} value less than, equal to or
+wxString\&} parameters and returning an {\it int} value less than, equal to or

 greater than 0 if the first string is less than, equal to or greater than the
 second one.
 
 greater than 0 if the first string is less than, equal to or greater than the
 second one.
 

-Example: sorting strings by their length:
+\wxheading{Example}

 
 

-\begin{verbatim}
+The following example sorts strings by their length.

 
 

+\begin{verbatim}

 static int CompareStringLen(const wxString& first, const wxString& second)
 {
     return first.length() - second.length();
 static int CompareStringLen(const wxString& first, const wxString& second)
 {
     return first.length() - second.length();


@@ -243,7 +274,11 @@ array.Add("three");
 array.Add("four");
 
 array.Sort(CompareStringLen);
 array.Add("four");
 
 array.Sort(CompareStringLen);

-

 \end{verbatim}
 
 \end{verbatim}
 

+{\bf Warning:} this function should not be used with sorted array because it
+could break the order of items and, for example, subsequent calls to 
+\helpref{Index()}{wxarraystringindex} would then not work!
+

 See also: \helpref{Sort}{wxarraystringsort}
 See also: \helpref{Sort}{wxarraystringsort}

+