docs/latex/wx/arrstrng.tex

   1 \section{\class{wxArrayString}}\label{wxarraystring}
   2
   3 wxArrayString is an efficient container for storing
   4 \helpref{wxString}{wxstring} objects. It has the same features as all
   5 \helpref{wxArray}{wxarray} classes, i.e. it dynamically expands when new items
   6 are added to it (so it is as easy to use as a linked list), but the access
   7 time to the elements is constant, instead of being linear in number of
   8 elements as in the case of linked lists. It is also very size efficient and
   9 doesn't take more space than a C array {\it wxString[]} type. wxArrayString
  10 uses its knowledge of internals of wxString class to achieve this.
  11
  12 This class is used in the same way as other dynamic \helpref{arrays}{wxarray},
  13 except that no {\it WX\_DEFINE\_ARRAY} declaration is needed for it. When a
  14 string is added or inserted in the array, a copy of the string is created, so
  15 the original string may be safely deleted (e.g. if it was a {\it char *}
  16 pointer the memory it was using can be freed immediately after this). In
  17 general, there is no need to worry about string memory deallocation when using
  18 this class - it will always free the memory it uses itself.
  19
  20 The references returned by \helpref{Item}{wxarraystringitem},
  21 \helpref{Last}{wxarraystringlast} or
  22 \helpref{operator[]}{wxarraystringoperatorindex} are not constant, so the
  23 array elements may be modified in place like this
  24
  25 \begin{verbatim}
  26     array.Last().MakeUpper();
  27 \end{verbatim}
  28
  29 Finally, none of the methods of this class is virtual including its
  30 destructor, so this class should not be derived from.
  31
  32 \wxheading{Derived from}
  33
  34 Although this is not true strictly speaking, this class may be considered as a
  35 specialization of \helpref{wxArray}{wxarray} class for the wxString member
  36 data: it is not implemented like this, but it does have all of the wxArray
  37 functions.
  38
  39 \wxheading{Include files}
  40
  41 <wx/string.h>
  42
  43 \wxheading{See also}
  44
  45 \helpref{wxArray}{wxarray}, \helpref{wxString}{wxstring}, \helpref{wxString overview}{wxstringoverview}
  46
  47 \latexignore{\rtfignore{\wxheading{Members}}}
  48
  49 \membersection{wxArrayString::wxArrayString}\label{wxarraystringctor}
  50
  51 \func{}{wxArrayString}{\void}
  52
  53 \func{}{wxArrayString}{\param{const wxArrayString\&}{ array}}
  54
  55 Default and copy constructors.
  56
  57 \membersection{wxArrayString::\destruct{wxArrayString}}\label{wxarraystringdtor}
  58
  59 \func{}{\destruct{wxArrayString}}{}
  60
  61 Destructor frees memory occupied by the array strings. For the performance
  62 reasons it is not virtual, so this class should not be derived from.
  63
  64 \membersection{wxArrayString::operator=}\label{wxarraystringoperatorassign}
  65
  66 \func{wxArrayString \&}{operator $=$}{\param{const wxArrayString\&}{ array}}
  67
  68 Assignment operator.
  69
  70 \membersection{wxArrayString::operator[]}\label{wxarraystringoperatorindex}
  71
  72 \func{wxString\&}{operatorp[]}{\param{size\_t }{nIndex}}
  73
  74 Return the array element at position {\it nIndex}. An assert failure will
  75 result from an attempt to access an element beyond the end of array in debug
  76 mode, but no check is done in release mode.
  77
  78 This is the operator version of \helpref{Item}{wxarraystringitem} method.
  79
  80 \membersection{wxArrayString::Add}\label{wxarraystringadd}
  81
  82 \func{void}{Add}{\param{const wxString\& }{str}}
  83
  84 Appends a new item to the array.
  85
  86 See also: \helpref{Insert}{wxarraystringinsert}
  87
  88 \membersection{wxArrayString::Alloc}\label{wxarraystringalloc}
  89
  90 \func{void}{Alloc}{\param{size\_t }{nCount}}
  91
  92 Preallocates enough memory to store {\it nCount} items. This function may be
  93 used to improve array class performance before adding a known number of items
  94 consecutively.
  95
  96 See also: \helpref{Dynamic array memory management}{wxarraymemorymanagement}
  97
  98 \membersection{wxArrayString::Clear}\label{wxarraystringclear}
  99
 100 \func{void}{Clear}{\void}
 101
 102 Clears the array contents and frees memory.
 103
 104 See also: \helpref{Empty}{wxarraystringempty}
 105
 106 \membersection{wxArrayString::Count}\label{wxarraystringcount}
 107
 108 \constfunc{size\_t}{Count}{\void}
 109
 110 Returns the number of items in the array. This function is deprecated and is
 111 for backwards compatibility only, please use
 112 \helpref{GetCount}{wxarraystringgetcount} instead.
 113
 114 \membersection{wxArrayString::Empty}\label{wxarraystringempty}
 115
 116 \func{void}{Empty}{\void}
 117
 118 Empties the array: after a call to this function
 119 \helpref{GetCount}{wxarraystringgetcount} will return $0$. However, this
 120 function does not free the memory used by the array and so should be used when
 121 the array is going to be reused for storing other strings. Otherwise, you
 122 should use \helpref{Clear}{wxarraystringclear} to empty the array and free
 123 memory.
 124
 125 \membersection{wxArrayString::GetCount}\label{wxarraystringgetcount}
 126
 127 \constfunc{size\_t}{GetCount}{\void}
 128
 129 Returns the number of items in the array.
 130
 131 \membersection{wxArrayString::Index}\label{wxarraystringindex}
 132
 133 \func{int}{Index}{\param{const char *}{ sz}, \param{bool}{ bCase = TRUE}, \param{bool}{ bFromEnd = FALSE}}
 134
 135 Search the element in the array, starting from the beginning if
 136 {\it bFromEnd} is FALSE or from end otherwise. If {\it bCase}, comparison is
 137 case sensitive (default), otherwise the case is ignored.
 138
 139 Returns index of the first item matched or wxNOT\_FOUND if there is no match.
 140
 141 \membersection{wxArrayString::Insert}\label{wxarraystringinsert}
 142
 143 \func{void}{Insert}{\param{const wxString\& }{str}, \param{size\_t}{ nIndex}}
 144
 145 Insert a new element in the array before the position {\it nIndex}. Thus, for
 146 example, to insert the string in the beginning of the array you would write
 147
 148 \begin{verbatim}
 149 Insert("foo", 0);
 150 \end{verbatim}
 151
 152 If {\it nIndex} is equal to {\it GetCount() + 1} this function behaves as
 153 \helpref{Add}{wxarraystringadd}.
 154
 155 \membersection{wxArrayString::IsEmpty}\label{wxarraystringisempty}
 156
 157 \func{}{IsEmpty}{}
 158
 159 Returns TRUE if the array is empty, FALSE otherwise. This function returns the
 160 same result as {\it GetCount() == 0} but is probably easier to read.
 161
 162 \membersection{wxArrayString::Item}\label{wxarraystringitem}
 163
 164 \constfunc{wxString\&}{Item}{\param{size\_t }{nIndex}}
 165
 166 Return the array element at position {\it nIndex}. An assert failure will
 167 result from an attempt to access an element beyond the end of array in debug
 168 mode, but no check is done in release mode.
 169
 170 See also \helpref{operator[]}{wxarraystringoperatorindex} for the operator
 171 version.
 172
 173 \membersection{wxArrayString::Last}\label{wxarraystringlast}
 174
 175 \func{}{Last}{}
 176
 177 Returns the last element of the array. Attempt to access the last element of
 178 an empty array will result in assert failure in debug build, however no checks
 179 are done in release mode.
 180
 181 \membersection{wxArrayString::Remove (by value)}\label{wxarraystringremoveval}
 182
 183 \func{void}{Remove}{\param{const char *}{ sz}}
 184
 185 Removes the first item matching this value. An assert failure is provoked by
 186 an attempt to remove an element which does not exist in debug build.
 187
 188 See also: \helpref{Index}{wxarraystringindex}, \helpref{Remove}{wxarraystringremove}
 189
 190 \membersection{wxArrayString::Remove (by index)}\label{wxarraystringremove}
 191
 192 \func{void}{Remove}{\param{size\_t }{nIndex}}
 193
 194 Removes the item at given position.
 195
 196 See also: \helpref{Remove}{wxarraystringremoveval}
 197
 198 \membersection{wxArrayString::Shrink}\label{wxarraystringshrink}
 199
 200 \func{void}{Shrink}{\void}
 201
 202 Releases the extra memory allocated by the array. This function is useful to
 203 minimize the array memory consumption.
 204
 205 See also: \helpref{Alloc}{wxarraystringalloc}, \helpref{Dynamic array memory management}{wxarraymemorymanagement}
 206
 207 \membersection{wxArrayString::Sort (alphabetically)}\label{wxarraystringsort}
 208
 209 \func{void}{Sort}{\param{bool}{ reverseOrder = FALSE}}
 210
 211 Sorts the array in alphabetical order or in reverse alphabetical order if
 212 {\it reverseOrder} is TRUE.
 213
 214 See also: \helpref{Sort}{wxarraystringsortcallback}
 215
 216 \membersection{wxArrayString::Sort (user defined)}\label{wxarraystringsortcallback}
 217
 218 \func{void}{Sort}{\param{CompareFunction }{compareFunction}}
 219
 220 Sorts the array using the specified {\it compareFunction} for item comparison.
 221 {\it CompareFunction} is defined as a function taking two {\it const
 222 wxString\&} parameters and returning {\it int} value less than, equal to or
 223 greater than 0 if the first string is less than, equal to or greater than the
 224 second one.
 225
 226 \wxheading{Example}
 227
 228 The following example sorts strings by their length.
 229
 230 \begin{verbatim}
 231 static int CompareStringLen(const wxString& first, const wxString& second)
 232 {
 233     return first.length() - second.length();
 234 }
 235
 236 ...
 237
 238 wxArrayString array;
 239
 240 array.Add("one");
 241 array.Add("two");
 242 array.Add("three");
 243 array.Add("four");
 244
 245 array.Sort(CompareStringLen);
 246 \end{verbatim}
 247
 248 See also: \helpref{Sort}{wxarraystringsort}
 249