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 sue 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{Specialization of}
  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
  46 overview}{wxstringoverview}
  47
  48 \latexignore{\rtfignore{\wxheading{Members}}}
  49
  50 \membersection{wxArrayString::wxArrayString}\label{wxarraystringctor}
  51
  52 \func{}{wxArrayString}{\void}
  53
  54 \func{}{wxArrayString}{\param{const wxArrayString\&}{ array}}
  55
  56 Default and copy constructors.
  57
  58 \membersection{wxArrayString::\destruct{wxArrayString}}\label{wxarraystringdtor}
  59
  60 \func{}{\destruct{wxArrayString}}{}
  61
  62 Destructor frees memory occupied by the array strings. For the performance
  63 reasons it is not virtual, so this class should not be derived from.
  64
  65 \membersection{wxArrayString::operator=}\label{wxarraystringoperatorassign}
  66
  67 \func{wxArrayString \&}{operator $=$}{\param{const wxArrayString\&}{ array}}
  68
  69 Assignment operator.
  70
  71 \membersection{wxArrayString::operator[]}\label{wxarraystringoperatorindex}
  72
  73 \func{wxString\&}{operatorp[]}{\param{size\_t }{nIndex}}
  74
  75 Return the array element at position {\it nIndex}. An assert failure will
  76 result from an attempt to access an element beyond the end of array in debug
  77 mode, but no check is done in release mode.
  78
  79 This is the operator version of \helpref{Item}{wxarraystringitem} method.
  80
  81 \membersection{wxArrayString::Add}\label{wxarraystringadd}
  82
  83 \func{void}{Add}{\param{const wxString\& }{str}}
  84
  85 Appends a new item to the array.
  86
  87 See also: \helpref{Insert}{wxarraystringinsert}
  88
  89 \membersection{wxArrayString::Alloc}\label{wxarraystringalloc}
  90
  91 \func{void}{Alloc}{\param{size\_t }{nCount}}
  92
  93 Preallocates enough memory to store {\it nCount} items. This function may be
  94 used to improve array class performance before adding a known number of items
  95 consecutively.
  96
  97 See also: \helpref{Dynamic array memory management}{wxarraymemorymanagement}
  98
  99 \membersection{wxArrayString::Clear}\label{wxarraystringclear}
 100
 101 \func{void}{Clear}{\void}
 102
 103 Clears the array contents and frees memory.
 104
 105 See also: \helpref{Empty}{wxarraystringempty}
 106
 107 \membersection{wxArrayString::Count}\label{wxarraystringcount}
 108
 109 \constfunc{size\_t}{Count}{\void}
 110
 111 Returns the number of items in the array. This function is deprecated and is
 112 for backwards compatibility only, please use
 113 \helpref{GetCount}{wxarraystringgetcount} instead.
 114
 115 \membersection{wxArrayString::Empty}\label{wxarraystringempty}
 116
 117 \func{void}{Empty}{\void}
 118
 119 Empties the array: after a call to this function
 120 \helpref{GetCount}{wxarraystringgetcount} will return $0$. However, this
 121 function does not free the memory used by the array and so should be used when
 122 the array is going to be reused for storing other strings. Otherwise, you
 123 should use \helpref{Clear}{wxarraystringclear} to empty the array and free
 124 memory.
 125
 126 \membersection{wxArrayString::GetCount}\label{wxarraystringgetcount}
 127
 128 \constfunc{size\_t}{GetCount}{\void}
 129
 130 Returns the number of items in the array.
 131
 132 \membersection{wxArrayString::Index}\label{wxarraystringindex}
 133
 134 \func{int}{Index}{\param{const char *}{ sz}, \param{bool}{ bCase = TRUE}, \param{bool}{ bFromEnd = FALSE}}
 135
 136 Search the element in the array, starting from the beginning if
 137 {\it bFromEnd} is FALSE or from end otherwise. If {\it bCase}, comparison is
 138 case sensitive (default), otherwise the case is ignored.
 139
 140 Returns index of the first item matched or wxNOT\_FOUND if there is no match.
 141
 142 \membersection{wxArrayString::Insert}\label{wxarraystringinsert}
 143
 144 \func{void}{Insert}{\param{const wxString\& }{str}, \param{size\_t}{ nIndex}}
 145
 146 Insert a new element in the array before the position {\it nIndex}. Thus, for
 147 example, to insert the string in the beginning of the array you would write
 148
 149 \begin{verbatim}
 150 Insert("foo", 0);
 151 \end{verbatim}
 152
 153 If {\it nIndex} is equal to {\it GetCount() + 1} this function behaves as
 154 \helpref{Add}{wxarraystringadd}.
 155
 156 \membersection{wxArrayString::IsEmpty}\label{wxarraystringisempty}
 157
 158 \func{}{IsEmpty}{}
 159
 160 Returns TRUE if the array is empty, FALSE otherwise. This function returns the
 161 same result as {\it GetCount() == 0} but is probably easier to read.
 162
 163 \membersection{wxArrayString::Item}\label{wxarraystringitem}
 164
 165 \constfunc{wxString\&}{Item}{\param{size\_t }{nIndex}}
 166
 167 Return the array element at position {\it nIndex}. An assert failure will
 168 result from an attempt to access an element beyond the end of array in debug
 169 mode, but no check is done in release mode.
 170
 171 See also \helpref{operator[]}{wxarraystringoperatorindex} for the operator
 172 version.
 173
 174 \membersection{wxArrayString::Last}\label{wxarraystringlast}
 175
 176 \func{}{Last}{}
 177
 178 Returns the last element of the array. Attempt to access the last element of
 179 an empty array will result in assert failure in debug build, however no checks
 180 are done in release mode.
 181
 182 \membersection{wxArrayString::Remove (by value)}\label{wxarraystringremoveval}
 183
 184 \func{void}{Remove}{\param{const char *}{ sz}}
 185
 186 Removes the first item matching this value. An assert failure is provoked by
 187 an attempt to remove an element which does not exist in debug build.
 188
 189 See also: \helpref{Index}{wxarraystringindex}, \helpref{Remove}{wxarraystringremove}
 190
 191 \membersection{wxArrayString::Remove (by index)}\label{wxarraystringremove}
 192
 193 \func{void}{Remove}{\param{size\_t }{nIndex}}
 194
 195 Removes the item at given position.
 196
 197 See also: \helpref{Remove}{wxarraystringremoveval}
 198
 199 \membersection{wxArrayString::Shrink}\label{wxarraystringshrink}
 200
 201 \func{void}{Shrink}{\void}
 202
 203 Releases the extra memory allocated by the array. This function is useful to
 204 minimize the array memory consumption.
 205
 206 See also: \helpref{Alloc}{wxarraystringalloc}, \helpref{Dynamic array memory management}{wxarraymemorymanagement}
 207
 208 \membersection{wxArrayString::Sort (alphabetically)}\label{wxarraystringsort}
 209
 210 \func{void}{Sort}{\param{bool}{ reverseOrder = FALSE}}
 211
 212 Sorts the array in alphabetical order or in reverse alphabetical order if
 213 {\it reverseOrder} is TRUE.
 214
 215 See also: \helpref{Sort}{wxarraystringsortcallback}
 216
 217 \membersection{wxArrayString::Sort (user defined)}\label{wxarraystringsortcallback}
 218
 219 \func{void}{Sort}{\param{CompareFunction }{compareFunction}}
 220
 221 Sorts the array using the specified {\it compareFunction} for item comparison.
 222 {\it CompareFunction} is defined as a function taking two {\it const
 223 wxString\&} parameters and returning {\it int} value less than, equal to or
 224 greater than 0 if the first string is less than, equal to or greater than the
 225 second one.
 226
 227 Example: sorting strings by their length:
 228
 229 \begin{verbatim}
 230
 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
 247 \end{verbatim}
 248
 249 See also: \helpref{Sort}{wxarraystringsort}