X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/9e2be6f02e5ca80575067f26138ca001fabfbeea..154f22b3facdbca2cb89e091ae2ea1398bfad9d1:/docs/latex/wx/arrstrng.tex

diff --git a/docs/latex/wx/arrstrng.tex b/docs/latex/wx/arrstrng.tex
index e41d6102ed..9750e4e7ad 100644
--- 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
-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).
 
@@ -26,10 +26,20 @@ array elements may be modified in place like this
     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
@@ -42,8 +52,7 @@ functions.
 
 \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}}}
 
@@ -55,6 +64,9 @@ overview}{wxstringoverview}
 
 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}}{}
@@ -70,7 +82,7 @@ Assignment operator.
 
 \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
@@ -80,9 +92,15 @@ This is the operator version of \helpref{Item}{wxarraystringitem} method.
 
 \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}
 
@@ -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.
 
+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}
@@ -153,6 +175,10 @@ Insert("foo", 0);
 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 array because it
+could break the order of items and, for example, subsequent calls to 
+\helpref{Index()}{wxarraystringindex} would not work then!
+
 \membersection{wxArrayString::IsEmpty}\label{wxarraystringisempty}
 
 \func{}{IsEmpty}{}
@@ -212,6 +238,10 @@ See also: \helpref{Alloc}{wxarraystringalloc}, \helpref{Dynamic array memory man
 Sorts the array in alphabetical order or in reverse alphabetical order if
 {\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 not work then!
+
 See also: \helpref{Sort}{wxarraystringsortcallback}
 
 \membersection{wxArrayString::Sort (user defined)}\label{wxarraystringsortcallback}
@@ -224,10 +254,11 @@ wxString\&} parameters and returning {\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.
 
-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();
@@ -243,7 +274,11 @@ array.Add("three");
 array.Add("four");
 
 array.Sort(CompareStringLen);
-
 \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 not work then!
+
 See also: \helpref{Sort}{wxarraystringsort}
+