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).
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
\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}}}
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::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
\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}
{\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}
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}{}
\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.
+{\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}
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.
-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();
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 then not work!
+
See also: \helpref{Sort}{wxarraystringsort}
+
projects / wxWidgets.git / blobdiff