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 variant 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 (instead 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 (basically, 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}}{}
Assignment operator.
+\membersection{wxArrayString::operator==}\label{wxarraystringoperatorequal}
+
+\constfunc{bool}{operator $==$}{\param{const wxArrayString\&}{ array}}
+
+Compares 2 arrays respecting the case. Returns true only if the arrays have
+the same number of elements and the same strings in the same order.
+
+\membersection{wxArrayString::operator!=}\label{wxarraystringoperatornotequal}
+
+\constfunc{bool}{operator $!=$}{\param{const wxArrayString\&}{ array}}
+
+Compares 2 arrays respecting the case. Returns true if the arrays have
+different number of elements or if the elements don't match pairwise.
+
\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}, \param{size\_t}{ copies = $1$}}
+
+Appends the given number of {\it copies} of the new item {\it str} to the
+array and returns the index of the first 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}
\membersection{wxArrayString::Index}\label{wxarraystringindex}
-\func{int}{Index}{\param{const char *}{ sz}, \param{bool}{ bCase = TRUE}, \param{bool}{ bFromEnd = FALSE}}
+\func{int}{Index}{\param{const char *}{ sz}, \param{bool}{ bCase = true}, \param{bool}{ bFromEnd = false}}
Search the element in the array, starting from the beginning if
-{\it bFromEnd} is FALSE or from end otherwise. If {\it bCase}, comparison is
+{\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}
-\func{void}{Insert}{\param{const wxString\& }{str}, \param{size\_t}{ nIndex}}
+\func{void}{Insert}{\param{const wxString\& }{str}, \param{size\_t}{ nIndex}, \param{size\_t }{copies = $1$}}
-Insert a new element in the array before the position {\it nIndex}. Thus, for
+Insert the given number of {\it copies} of the new element in the array before the position {\it nIndex}. Thus, for
example, to insert the string in the beginning of the array you would write
\begin{verbatim}
Insert("foo", 0);
\end{verbatim}
-If {\it nIndex} is equal to {\it GetCount() + 1} this function behaves as
+If {\it nIndex} is equal to {\it GetCount()} 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}{}
-Returns TRUE if the array is empty, FALSE otherwise. This function returns the
+Returns true if the array is empty, false otherwise. This function returns the
same result as {\it GetCount() == 0} but is probably easier to read.
\membersection{wxArrayString::Item}\label{wxarraystringitem}
an empty array will result in assert failure in debug build, however no checks
are done in release mode.
-\membersection{wxArrayString::Remove (by value)}\label{wxarraystringremoveval}
+\membersection{wxArrayString::Remove}\label{wxarraystringremove}
\func{void}{Remove}{\param{const char *}{ sz}}
Removes the first item matching this value. An assert failure is provoked by
an attempt to remove an element which does not exist in debug build.
-See also: \helpref{Index}{wxarraystringindex}, \helpref{Remove}{wxarraystringremove}
-
-\membersection{wxArrayString::Remove (by index)}\label{wxarraystringremove}
+See also: \helpref{Index}{wxarraystringindex}
-\func{void}{Remove}{\param{size\_t }{nIndex}}
+\func{void}{Remove}{\param{size\_t }{nIndex}, \param{size\_t }{count = $1$}}
-Removes the item at given position.
-
-See also: \helpref{Remove}{wxarraystringremoveval}
+Removes {\it count} items starting at position {\it nIndex} from the array.
\membersection{wxArrayString::Shrink}\label{wxarraystringshrink}
See also: \helpref{Alloc}{wxarraystringalloc}, \helpref{Dynamic array memory management}{wxarraymemorymanagement}
-\membersection{wxArrayString::Sort (alphabetically)}\label{wxarraystringsort}
-
-\func{void}{Sort}{\param{bool}{ reverseOrder = FALSE}}
+\membersection{wxArrayString::Sort}\label{wxarraystringsort}
-Sorts the array in alphabetical order or in reverse alphabetical order if
-{\it reverseOrder} is TRUE.
+\func{void}{Sort}{\param{bool}{ reverseOrder = false}}
-See also: \helpref{Sort}{wxarraystringsortcallback}
+Sorts the array in alphabetical order or in reverse alphabetical order if
+{\it reverseOrder} is true. The sort is case-sensitive.
-\membersection{wxArrayString::Sort (user defined)}\label{wxarraystringsortcallback}
+{\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!
\func{void}{Sort}{\param{CompareFunction }{compareFunction}}
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}
-See also: \helpref{Sort}{wxarraystringsort}
+{\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!
+
projects / wxWidgets.git / blobdiff