| 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 | There is also a variant of wxArrayString called wxSortedArrayString which has |
| 30 | exactly the same methods as wxArrayString, but which always keeps the string |
| 31 | in it in (alphabetical) order. wxSortedArrayString uses binary search in its |
| 32 | \helpref{Index}{wxarraystringindex} function (instead of linear search for |
| 33 | wxArrayString::Index) which makes it much more efficient if you add strings to |
| 34 | the array rarely (because, of course, you have to pay for Index() efficiency |
| 35 | by having Add() be slower) but search for them often. Several methods should |
| 36 | not be used with sorted array (basically, all which break the order of items) |
| 37 | which is mentioned in their description. |
| 38 | |
| 39 | Final word: none of the methods of wxArrayString is virtual including its |
| 40 | destructor, so this class should not be used as a base class. |
| 41 | |
| 42 | \wxheading{Derived from} |
| 43 | |
| 44 | Although this is not true strictly speaking, this class may be considered as a |
| 45 | specialization of \helpref{wxArray}{wxarray} class for the wxString member |
| 46 | data: it is not implemented like this, but it does have all of the wxArray |
| 47 | functions. |
| 48 | |
| 49 | \wxheading{Include files} |
| 50 | |
| 51 | <wx/arrstr.h> |
| 52 | |
| 53 | \wxheading{See also} |
| 54 | |
| 55 | \helpref{wxArray}{wxarray}, \helpref{wxString}{wxstring}, \helpref{wxString overview}{wxstringoverview} |
| 56 | |
| 57 | \latexignore{\rtfignore{\wxheading{Members}}} |
| 58 | |
| 59 | \membersection{wxArrayString::wxArrayString}\label{wxarraystringctor} |
| 60 | |
| 61 | \func{}{wxArrayString}{\void} |
| 62 | |
| 63 | Default constructor. |
| 64 | |
| 65 | \func{}{wxArrayString}{\param{const wxArrayString\&}{ array}} |
| 66 | |
| 67 | Copy constructor. Note that when an array is assigned to a sorted array, its contents is |
| 68 | automatically sorted during construction. |
| 69 | |
| 70 | \func{}{wxArrayString}{\param{size\_t}{ sz}, \param{const wxChar**}{ arr}} |
| 71 | |
| 72 | Constructor from a C string array. Pass a size {\it sz} and array {\it arr}. |
| 73 | |
| 74 | \func{}{wxArrayString}{\param{size\_t}{ sz}, \param{const wxString*}{ arr}} |
| 75 | |
| 76 | Constructor from a wxString array. Pass a size {\it sz} and array {\it arr}. |
| 77 | |
| 78 | \membersection{wxArrayString::\destruct{wxArrayString}}\label{wxarraystringdtor} |
| 79 | |
| 80 | \func{}{\destruct{wxArrayString}}{} |
| 81 | |
| 82 | Destructor frees memory occupied by the array strings. For the performance |
| 83 | reasons it is not virtual, so this class should not be derived from. |
| 84 | |
| 85 | \membersection{wxArrayString::operator=}\label{wxarraystringoperatorassign} |
| 86 | |
| 87 | \func{wxArrayString \&}{operator $=$}{\param{const wxArrayString\&}{ array}} |
| 88 | |
| 89 | Assignment operator. |
| 90 | |
| 91 | \membersection{wxArrayString::operator==}\label{wxarraystringoperatorequal} |
| 92 | |
| 93 | \constfunc{bool}{operator $==$}{\param{const wxArrayString\&}{ array}} |
| 94 | |
| 95 | Compares 2 arrays respecting the case. Returns true only if the arrays have |
| 96 | the same number of elements and the same strings in the same order. |
| 97 | |
| 98 | \membersection{wxArrayString::operator!=}\label{wxarraystringoperatornotequal} |
| 99 | |
| 100 | \constfunc{bool}{operator $!=$}{\param{const wxArrayString\&}{ array}} |
| 101 | |
| 102 | Compares 2 arrays respecting the case. Returns true if the arrays have |
| 103 | different number of elements or if the elements don't match pairwise. |
| 104 | |
| 105 | \membersection{wxArrayString::operator[]}\label{wxarraystringoperatorindex} |
| 106 | |
| 107 | \func{wxString\&}{operator[]}{\param{size\_t }{nIndex}} |
| 108 | |
| 109 | Return the array element at position {\it nIndex}. An assert failure will |
| 110 | result from an attempt to access an element beyond the end of array in debug |
| 111 | mode, but no check is done in release mode. |
| 112 | |
| 113 | This is the operator version of \helpref{Item}{wxarraystringitem} method. |
| 114 | |
| 115 | \membersection{wxArrayString::Add}\label{wxarraystringadd} |
| 116 | |
| 117 | \func{size\_t}{Add}{\param{const wxString\& }{str}, \param{size\_t}{ copies = $1$}} |
| 118 | |
| 119 | Appends the given number of {\it copies} of the new item {\it str} to the |
| 120 | array and returns the index of the first new item in the array. |
| 121 | |
| 122 | {\bf Warning:} For sorted arrays, the index of the inserted item will not be, |
| 123 | in general, equal to \helpref{GetCount()}{wxarraystringgetcount} - 1 because |
| 124 | the item is inserted at the correct position to keep the array sorted and not |
| 125 | appended. |
| 126 | |
| 127 | See also: \helpref{Insert}{wxarraystringinsert} |
| 128 | |
| 129 | \membersection{wxArrayString::Alloc}\label{wxarraystringalloc} |
| 130 | |
| 131 | \func{void}{Alloc}{\param{size\_t }{nCount}} |
| 132 | |
| 133 | Preallocates enough memory to store {\it nCount} items. This function may be |
| 134 | used to improve array class performance before adding a known number of items |
| 135 | consecutively. |
| 136 | |
| 137 | See also: \helpref{Dynamic array memory management}{wxarraymemorymanagement} |
| 138 | |
| 139 | \membersection{wxArrayString::Clear}\label{wxarraystringclear} |
| 140 | |
| 141 | \func{void}{Clear}{\void} |
| 142 | |
| 143 | Clears the array contents and frees memory. |
| 144 | |
| 145 | See also: \helpref{Empty}{wxarraystringempty} |
| 146 | |
| 147 | \membersection{wxArrayString::Count}\label{wxarraystringcount} |
| 148 | |
| 149 | \constfunc{size\_t}{Count}{\void} |
| 150 | |
| 151 | Returns the number of items in the array. This function is deprecated and is |
| 152 | for backwards compatibility only, please use |
| 153 | \helpref{GetCount}{wxarraystringgetcount} instead. |
| 154 | |
| 155 | \membersection{wxArrayString::Empty}\label{wxarraystringempty} |
| 156 | |
| 157 | \func{void}{Empty}{\void} |
| 158 | |
| 159 | Empties the array: after a call to this function |
| 160 | \helpref{GetCount}{wxarraystringgetcount} will return $0$. However, this |
| 161 | function does not free the memory used by the array and so should be used when |
| 162 | the array is going to be reused for storing other strings. Otherwise, you |
| 163 | should use \helpref{Clear}{wxarraystringclear} to empty the array and free |
| 164 | memory. |
| 165 | |
| 166 | \membersection{wxArrayString::GetCount}\label{wxarraystringgetcount} |
| 167 | |
| 168 | \constfunc{size\_t}{GetCount}{\void} |
| 169 | |
| 170 | Returns the number of items in the array. |
| 171 | |
| 172 | \membersection{wxArrayString::Index}\label{wxarraystringindex} |
| 173 | |
| 174 | \func{int}{Index}{\param{const char *}{ sz}, \param{bool}{ bCase = true}, \param{bool}{ bFromEnd = false}} |
| 175 | |
| 176 | Search the element in the array, starting from the beginning if |
| 177 | {\it bFromEnd} is false or from end otherwise. If {\it bCase}, comparison is |
| 178 | case sensitive (default), otherwise the case is ignored. |
| 179 | |
| 180 | This function uses linear search for wxArrayString and binary search for |
| 181 | wxSortedArrayString, but it ignores the {\it bCase} and {\it bFromEnd} |
| 182 | parameters in the latter case. |
| 183 | |
| 184 | Returns index of the first item matched or {\tt wxNOT\_FOUND} if there is no match. |
| 185 | |
| 186 | \membersection{wxArrayString::Insert}\label{wxarraystringinsert} |
| 187 | |
| 188 | \func{void}{Insert}{\param{const wxString\& }{str}, \param{size\_t}{ nIndex}, \param{size\_t }{copies = $1$}} |
| 189 | |
| 190 | Insert the given number of {\it copies} of the new element in the array before the position {\it nIndex}. Thus, for |
| 191 | example, to insert the string in the beginning of the array you would write |
| 192 | |
| 193 | \begin{verbatim} |
| 194 | Insert("foo", 0); |
| 195 | \end{verbatim} |
| 196 | |
| 197 | If {\it nIndex} is equal to {\it GetCount()} this function behaves as |
| 198 | \helpref{Add}{wxarraystringadd}. |
| 199 | |
| 200 | {\bf Warning:} this function should not be used with sorted arrays because it |
| 201 | could break the order of items and, for example, subsequent calls to |
| 202 | \helpref{Index()}{wxarraystringindex} would then not work! |
| 203 | |
| 204 | \membersection{wxArrayString::IsEmpty}\label{wxarraystringisempty} |
| 205 | |
| 206 | \func{bool}{IsEmpty}{} |
| 207 | |
| 208 | Returns true if the array is empty, false otherwise. This function returns the |
| 209 | same result as {\it GetCount() == 0} but is probably easier to read. |
| 210 | |
| 211 | \membersection{wxArrayString::Item}\label{wxarraystringitem} |
| 212 | |
| 213 | \constfunc{wxString\&}{Item}{\param{size\_t }{nIndex}} |
| 214 | |
| 215 | Return the array element at position {\it nIndex}. An assert failure will |
| 216 | result from an attempt to access an element beyond the end of array in debug |
| 217 | mode, but no check is done in release mode. |
| 218 | |
| 219 | See also \helpref{operator[]}{wxarraystringoperatorindex} for the operator |
| 220 | version. |
| 221 | |
| 222 | \membersection{wxArrayString::Last}\label{wxarraystringlast} |
| 223 | |
| 224 | \func{wxString&}{Last}{} |
| 225 | |
| 226 | Returns the last element of the array. Attempt to access the last element of |
| 227 | an empty array will result in assert failure in debug build, however no checks |
| 228 | are done in release mode. |
| 229 | |
| 230 | \membersection{wxArrayString::Remove}\label{wxarraystringremove} |
| 231 | |
| 232 | \func{void}{Remove}{\param{const char *}{ sz}} |
| 233 | |
| 234 | Removes the first item matching this value. An assert failure is provoked by |
| 235 | an attempt to remove an element which does not exist in debug build. |
| 236 | |
| 237 | See also: \helpref{Index}{wxarraystringindex} |
| 238 | |
| 239 | \membersection{wxArrayString::RemoveAt}\label{wxarraystringremoveat} |
| 240 | |
| 241 | \func{void}{RemoveAt}{\param{size\_t }{nIndex}, \param{size\_t }{count = $1$}} |
| 242 | |
| 243 | Removes {\it count} items starting at position {\it nIndex} from the array. |
| 244 | |
| 245 | \membersection{wxArrayString::Shrink}\label{wxarraystringshrink} |
| 246 | |
| 247 | \func{void}{Shrink}{\void} |
| 248 | |
| 249 | Releases the extra memory allocated by the array. This function is useful to |
| 250 | minimize the array memory consumption. |
| 251 | |
| 252 | See also: \helpref{Alloc}{wxarraystringalloc}, \helpref{Dynamic array memory management}{wxarraymemorymanagement} |
| 253 | |
| 254 | \membersection{wxArrayString::Sort}\label{wxarraystringsort} |
| 255 | |
| 256 | \func{void}{Sort}{\param{bool}{ reverseOrder = false}} |
| 257 | |
| 258 | Sorts the array in alphabetical order or in reverse alphabetical order if |
| 259 | {\it reverseOrder} is true. The sort is case-sensitive. |
| 260 | |
| 261 | {\bf Warning:} this function should not be used with sorted array because it |
| 262 | could break the order of items and, for example, subsequent calls to |
| 263 | \helpref{Index()}{wxarraystringindex} would then not work! |
| 264 | |
| 265 | \func{void}{Sort}{\param{CompareFunction }{compareFunction}} |
| 266 | |
| 267 | Sorts the array using the specified {\it compareFunction} for item comparison. |
| 268 | {\it CompareFunction} is defined as a function taking two {\it const |
| 269 | wxString\&} parameters and returning an {\it int} value less than, equal to or |
| 270 | greater than 0 if the first string is less than, equal to or greater than the |
| 271 | second one. |
| 272 | |
| 273 | \wxheading{Example} |
| 274 | |
| 275 | The following example sorts strings by their length. |
| 276 | |
| 277 | \begin{verbatim} |
| 278 | static int CompareStringLen(const wxString& first, const wxString& second) |
| 279 | { |
| 280 | return first.length() - second.length(); |
| 281 | } |
| 282 | |
| 283 | ... |
| 284 | |
| 285 | wxArrayString array; |
| 286 | |
| 287 | array.Add("one"); |
| 288 | array.Add("two"); |
| 289 | array.Add("three"); |
| 290 | array.Add("four"); |
| 291 | |
| 292 | array.Sort(CompareStringLen); |
| 293 | \end{verbatim} |
| 294 | |
| 295 | {\bf Warning:} this function should not be used with sorted array because it |
| 296 | could break the order of items and, for example, subsequent calls to |
| 297 | \helpref{Index()}{wxarraystringindex} would then not work! |
| 298 | |