--- /dev/null
+\section{\class{wxArrayString}}\label{wxarraystring}
+
+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
+doesn't take more space than a C array {\it wxString[]} type (wxArrayString
+uses its knowledge of internals of wxString class to achieve this).
+
+This class is used in the same way as other dynamic \helpref{arrays}{wxarray},
+except that no {\it WX\_DEFINE\_ARRAY} declaration is needed for it. When a
+string is added or inserted in the array, a copy of the string is created, so
+the original string may be safely deleted (e.g. if it was a {\it char *}
+pointer the memory it was using can be freed immediately after this). In
+general, there is no need to worry about string memory deallocation when using
+this class - it will always free the memory it uses itself.
+
+The references returned by \helpref{Item}{wxarraystringitem},
+\helpref{Last}{wxarraystringlast} or
+\helpref{operator[]}{wxarraystringoperatorindex} are not constant, so the
+array elements may be modified in place like this
+
+\begin{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.
+
+\wxheading{Specialization of}
+
+Although this is not true strictly speaking, this class may be considered as a
+specialization of \helpref{wxArray}{wxarray} class for the wxString member
+data: it is not implemented like this, but it does have all of the wxArray
+functions.
+
+\wxheading{Include files}
+
+<wx/string.h>
+
+\wxheading{See also}
+
+\helpref{wxArray}{wxarray}, \helpref{wxString}{wxstring}, \helpref{wxString
+overview}{wxstringoverview}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxArrayString::wxArrayString}\label{wxarraystringctor}
+
+\func{}{wxArrayString}{\void}
+
+\func{}{wxArrayString}{\param{const wxArrayString\&}{ array}}
+
+Default and copy constructors.
+
+\membersection{wxArrayString::\destruct{wxArrayString}}\label{wxarraystringdtor}
+
+\func{}{\destruct{wxArrayString}}{}
+
+Destructor frees memory occupied by the array strings. For the performance
+reasons it is not virtual, so this class should not be derived from.
+
+\membersection{wxArrayString::operator=}\label{wxarraystringoperatorassign}
+
+\func{wxArrayString \&}{operator $=$}{\param{const wxArrayString\&}{ array}}
+
+Assignment operator.
+
+\membersection{wxArrayString::operator[]}\label{wxarraystringoperatorindex}
+
+\func{wxString\&}{operatorp[]}{\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
+mode, but no check is done in release mode.
+
+This is the operator version of \helpref{Item}{wxarraystringitem} method.
+
+\membersection{wxArrayString::Add}\label{wxarraystringadd}
+
+\func{void}{Add}{\param{const wxString\& }{str}}
+
+Appends a new item to the array.
+
+See also: \helpref{Insert}{wxarraystringinsert}
+
+\membersection{wxArrayString::Alloc}\label{wxarraystringalloc}
+
+\func{void}{Alloc}{\param{size\_t }{nCount}}
+
+Preallocates enough memory to store {\it nCount} items. This function may be
+used to improve array class performance before adding a known number of items
+consecutively.
+
+See also: \helpref{Dynamic array memory management}{wxarraymemorymanagement}
+
+\membersection{wxArrayString::Clear}\label{wxarraystringclear}
+
+\func{void}{Clear}{\void}
+
+Clears the array contents and frees memory.
+
+See also: \helpref{Empty}{wxarraystringempty}
+
+\membersection{wxArrayString::Count}\label{wxarraystringcount}
+
+\constfunc{size\_t}{Count}{\void}
+
+Returns the number of items in the array. This function is deprecated and is
+for backwards compatibility only, please use
+\helpref{GetCount}{wxarraystringgetcount} instead.
+
+\membersection{wxArrayString::Empty}\label{wxarraystringempty}
+
+\func{void}{Empty}{\void}
+
+Empties the array: after a call to this function
+\helpref{GetCount}{wxarraystringgetcount} will return $0$. However, this
+function does not free the memory used by the array and so should be used when
+the array is going to be reused for storing other strings. Otherwise, you
+should use \helpref{Clear}{wxarraystringclear} to empty the array and free
+memory.
+
+\membersection{wxArrayString::GetCount}\label{wxarraystringgetcount}
+
+\constfunc{size\_t}{GetCount}{\void}
+
+Returns the number of items in the array.
+
+\membersection{wxArrayString::Index}\label{wxarraystringindex}
+
+\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
+case sensitive (default), otherwise the case is ignored.
+
+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}}
+
+Insert a 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
+\helpref{Add}{wxarraystringadd}.
+
+\membersection{wxArrayString::IsEmpty}\label{wxarraystringisempty}
+
+\func{}{IsEmpty}{}
+
+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}
+
+\constfunc{wxString\&}{Item}{\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
+mode, but no check is done in release mode.
+
+See also \helpref{operator[]}{wxarraystringoperatorindex} for the operator
+version.
+
+\membersection{wxArrayString::Last}\label{wxarraystringlast}
+
+\func{}{Last}{}
+
+Returns the last element of the array. Attempt to access the last element of
+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}
+
+\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}
+
+\func{void}{Remove}{\param{size\_t }{nIndex}}
+
+Removes the item at given position.
+
+See also: \helpref{Remove}{wxarraystringremoveval}
+
+\membersection{wxArrayString::Shrink}\label{wxarraystringshrink}
+
+\func{void}{Shrink}{\void}
+
+Releases the extra memory allocated by the array. This function is useful to
+minimize the array memory consumption.
+
+See also: \helpref{Alloc}{wxarraystringalloc}, \helpref{Dynamic array memory management}{wxarraymemorymanagement}
+
+\membersection{wxArrayString::Sort (alphabetically)}\label{wxarraystringsort}
+
+\func{void}{Sort}{\param{bool}{ reverseOrder = FALSE}}
+
+Sorts the array in alphabetical order or in reverse alphabetical order if
+{\it reverseOrder} is TRUE.
+
+See also: \helpref{Sort}{wxarraystringsortcallback}
+
+\membersection{wxArrayString::Sort (user defined)}\label{wxarraystringsortcallback}
+
+\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
+greater than 0 if the first string is less than, equal to or greater than the
+second one.
+
+Example: sorting strings by their length:
+
+\begin{verbatim}
+
+static int CompareStringLen(const wxString& first, const wxString& second)
+{
+ return first.length() - second.length();
+}
+
+...
+
+wxArrayString array;
+
+array.Add("one");
+array.Add("two");
+array.Add("three");
+array.Add("four");
+
+array.Sort(CompareStringLen);
+
+\end{verbatim}
+
+See also: \helpref{Sort}{wxarraystringsort}
projects / wxWidgets.git / commitdiff
