]>
Commit | Line | Data |
---|---|---|
23324ae1 FM |
1 | ///////////////////////////////////////////////////////////////////////////// |
2 | // Name: arrstr.h | |
e54c96f1 | 3 | // Purpose: interface of wxArrayString |
23324ae1 FM |
4 | // Author: wxWidgets team |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows license | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
b7c50e37 FM |
9 | /** |
10 | @todo | |
11 | the following functions are not documented; do they need to be? | |
12 | WXDLLIMPEXP_BASE int wxCMPFUNC_CONV wxStringSortAscending(wxString*, wxString*); | |
13 | WXDLLIMPEXP_BASE int wxCMPFUNC_CONV wxStringSortDescending(wxString*, wxString*); | |
14 | */ | |
15 | ||
23324ae1 FM |
16 | /** |
17 | @class wxArrayString | |
18 | @wxheader{arrstr.h} | |
7c913512 | 19 | |
39fb8056 FM |
20 | wxArrayString is an efficient container for storing wxString objects. |
21 | ||
22 | It has the same features as all wxArray classes, i.e. it dynamically expands | |
23 | when new items are added to it (so it is as easy to use as a linked list), | |
24 | but the access time to the elements is constant, instead of being linear in | |
25 | number of elements as in the case of linked lists. It is also very size | |
26 | efficient and doesn't take more space than a C array @e wxString[] type | |
27 | (wxArrayString uses its knowledge of internals of wxString class to achieve this). | |
28 | ||
29 | This class is used in the same way as other dynamic arrays(), except that no | |
30 | @e WX_DEFINE_ARRAY declaration is needed for it. | |
31 | When a string is added or inserted in the array, a copy of the string is created, | |
32 | so the original string may be safely deleted (e.g. if it was a @e wxChar * | |
33 | pointer the memory it was using can be freed immediately after this). | |
34 | In general, there is no need to worry about string memory deallocation when using | |
23324ae1 | 35 | this class - it will always free the memory it uses itself. |
7c913512 | 36 | |
39fb8056 FM |
37 | The references returned by wxArrayString::Item, wxArrayString::Last or |
38 | wxArrayString::operator[] are not constant, so the array elements may | |
39 | be modified in place like this: | |
7c913512 | 40 | |
23324ae1 FM |
41 | @code |
42 | array.Last().MakeUpper(); | |
43 | @endcode | |
7c913512 | 44 | |
39fb8056 FM |
45 | @note none of the methods of wxArrayString is virtual including its |
46 | destructor, so this class should not be used as a base class. | |
47 | ||
48 | Although this is not true strictly speaking, this class may be considered as | |
49 | a specialization of wxArray class for the wxString member data: it is not | |
50 | implemented like this, but it does have all of the wxArray functions. | |
7c913512 | 51 | |
b7c50e37 FM |
52 | @todo what about stl? how does it integrate? |
53 | ||
23324ae1 FM |
54 | @library{wxbase} |
55 | @category{containers} | |
7c913512 | 56 | |
39fb8056 | 57 | @see wxArray, wxString, @ref overview_string |
23324ae1 FM |
58 | */ |
59 | class wxArrayString : public wxArray | |
60 | { | |
61 | public: | |
23324ae1 | 62 | /** |
39fb8056 | 63 | Default constructor. |
23324ae1 FM |
64 | */ |
65 | wxArrayString(); | |
39fb8056 FM |
66 | |
67 | /** | |
b7c50e37 | 68 | Copy constructor. |
39fb8056 | 69 | */ |
7c913512 | 70 | wxArrayString(const wxArrayString& array); |
39fb8056 FM |
71 | |
72 | //@{ | |
73 | /** | |
74 | Constructor from a C string array. Pass a size sz and array arr. | |
75 | **/ | |
7c913512 FM |
76 | wxArrayString(size_t sz, const char** arr); |
77 | wxArrayString(size_t sz, const wchar_t** arr); | |
23324ae1 FM |
78 | //@} |
79 | ||
80 | /** | |
39fb8056 FM |
81 | Constructor from a wxString array. Pass a size @a sz and array @e arr. |
82 | */ | |
83 | wxArrayString(size_t sz, const wxString* arr); | |
84 | ||
85 | /** | |
86 | Destructor frees memory occupied by the array strings. For performance | |
23324ae1 FM |
87 | reasons it is not virtual, so this class should not be derived from. |
88 | */ | |
89 | ~wxArrayString(); | |
90 | ||
91 | /** | |
4cc4bfaf | 92 | Appends the given number of @a copies of the new item @a str to the |
23324ae1 | 93 | array and returns the index of the first new item in the array. |
39fb8056 | 94 | |
39fb8056 | 95 | @see Insert() |
23324ae1 | 96 | */ |
4cc4bfaf | 97 | size_t Add(const wxString& str, size_t copies = 1); |
23324ae1 FM |
98 | |
99 | /** | |
4cc4bfaf | 100 | Preallocates enough memory to store @a nCount items. This function may be |
23324ae1 FM |
101 | used to improve array class performance before adding a known number of items |
102 | consecutively. | |
39fb8056 FM |
103 | |
104 | @todo FIX THIS LINK | |
105 | ||
106 | @see @ref wxArray::memorymanagement "Dynamic array memory management" | |
23324ae1 FM |
107 | */ |
108 | void Alloc(size_t nCount); | |
109 | ||
110 | /** | |
111 | Clears the array contents and frees memory. | |
39fb8056 FM |
112 | |
113 | @see Empty() | |
23324ae1 FM |
114 | */ |
115 | void Clear(); | |
116 | ||
117 | /** | |
39fb8056 | 118 | Empties the array: after a call to this function GetCount() will return 0. |
3c4f71cc | 119 | However, this function does not free the memory used by the array and so |
39fb8056 FM |
120 | should be used when the array is going to be reused for storing other strings. |
121 | Otherwise, you should use Clear() to empty the array and free memory. | |
23324ae1 FM |
122 | */ |
123 | void Empty(); | |
124 | ||
125 | /** | |
126 | Returns the number of items in the array. | |
127 | */ | |
328f5751 | 128 | size_t GetCount() const; |
23324ae1 FM |
129 | |
130 | /** | |
39fb8056 FM |
131 | Search the element in the array, starting from the beginning if @a bFromEnd |
132 | is @false or from end otherwise. If @e bCase, comparison is case sensitive | |
133 | (default), otherwise the case is ignored. | |
134 | ||
b7c50e37 | 135 | This function uses linear search for wxArrayString. |
23324ae1 FM |
136 | Returns index of the first item matched or @c wxNOT_FOUND if there is no match. |
137 | */ | |
4cc4bfaf FM |
138 | int Index(const wxString& sz, bool bCase = true, |
139 | bool bFromEnd = false); | |
23324ae1 FM |
140 | |
141 | /** | |
4cc4bfaf | 142 | Insert the given number of @a copies of the new element in the array before the |
39fb8056 FM |
143 | position @e nIndex. Thus, for example, to insert the string in the beginning of |
144 | the array you would write: | |
145 | ||
146 | @code | |
147 | Insert("foo", 0); | |
148 | @endcode | |
3c4f71cc | 149 | |
39fb8056 | 150 | If @a nIndex is equal to @e GetCount() this function behaves as Add(). |
23324ae1 FM |
151 | */ |
152 | void Insert(const wxString& str, size_t nIndex, | |
153 | size_t copies = 1); | |
154 | ||
155 | /** | |
156 | Returns @true if the array is empty, @false otherwise. This function returns the | |
157 | same result as @e GetCount() == 0 but is probably easier to read. | |
158 | */ | |
159 | bool IsEmpty(); | |
160 | ||
161 | /** | |
162 | Return the array element at position @e nIndex. An assert failure will | |
163 | result from an attempt to access an element beyond the end of array in debug | |
164 | mode, but no check is done in release mode. | |
39fb8056 FM |
165 | |
166 | @see operator[] for the operator version. | |
23324ae1 | 167 | */ |
328f5751 | 168 | wxString Item(size_t nIndex) const; |
23324ae1 FM |
169 | |
170 | /** | |
171 | Returns the last element of the array. Attempt to access the last element of | |
172 | an empty array will result in assert failure in debug build, however no checks | |
173 | are done in release mode. | |
174 | */ | |
175 | wxString Last(); | |
176 | ||
177 | /** | |
178 | Removes the first item matching this value. An assert failure is provoked by | |
179 | an attempt to remove an element which does not exist in debug build. | |
39fb8056 FM |
180 | |
181 | @see Index() | |
23324ae1 FM |
182 | */ |
183 | void Remove(const wxString& sz); | |
184 | ||
185 | /** | |
4cc4bfaf | 186 | Removes @a count items starting at position @a nIndex from the array. |
23324ae1 FM |
187 | */ |
188 | void RemoveAt(size_t nIndex, size_t count = 1); | |
189 | ||
190 | /** | |
191 | Releases the extra memory allocated by the array. This function is useful to | |
192 | minimize the array memory consumption. | |
39fb8056 FM |
193 | |
194 | @todo FIX THIS LINK | |
195 | ||
196 | @see Alloc(), @ref wxArray::memorymanagement "Dynamic array memory | |
23324ae1 FM |
197 | management" |
198 | */ | |
199 | void Shrink(); | |
200 | ||
39fb8056 FM |
201 | /** |
202 | Sorts the array in alphabetical order or in reverse alphabetical order if | |
203 | @a reverseOrder is @true. The sort is case-sensitive. | |
39fb8056 | 204 | */ |
39fb8056 FM |
205 | void Sort(bool reverseOrder = false); |
206 | ||
23324ae1 | 207 | /** |
4cc4bfaf | 208 | Sorts the array using the specified @a compareFunction for item comparison. |
39fb8056 | 209 | @e CompareFunction is defined as a function taking two @e const wxString |
3c4f71cc | 210 | parameters and returning an @e int value less than, equal to or greater |
39fb8056 | 211 | than 0 if the first string is less than, equal to or greater than the |
23324ae1 | 212 | second one. |
39fb8056 FM |
213 | |
214 | Example: | |
215 | The following example sorts strings by their length. | |
216 | ||
217 | @code | |
218 | static int CompareStringLen(const wxString& first, const wxString& second) | |
219 | { | |
220 | return first.length() - second.length(); | |
221 | } | |
3c4f71cc | 222 | |
39fb8056 | 223 | ... |
3c4f71cc | 224 | |
39fb8056 | 225 | wxArrayString array; |
3c4f71cc | 226 | |
39fb8056 FM |
227 | array.Add("one"); |
228 | array.Add("two"); | |
229 | array.Add("three"); | |
230 | array.Add("four"); | |
3c4f71cc | 231 | |
39fb8056 FM |
232 | array.Sort(CompareStringLen); |
233 | @endcode | |
23324ae1 | 234 | */ |
7c913512 | 235 | void Sort(CompareFunction compareFunction); |
23324ae1 FM |
236 | |
237 | /** | |
238 | Compares 2 arrays respecting the case. Returns @true if the arrays have | |
239 | different number of elements or if the elements don't match pairwise. | |
240 | */ | |
328f5751 | 241 | bool operator !=(const wxArrayString& array) const; |
23324ae1 FM |
242 | |
243 | /** | |
244 | Assignment operator. | |
245 | */ | |
246 | wxArrayString operator =(const wxArrayString& array); | |
247 | ||
248 | /** | |
249 | Compares 2 arrays respecting the case. Returns @true only if the arrays have | |
250 | the same number of elements and the same strings in the same order. | |
251 | */ | |
328f5751 | 252 | bool operator ==(const wxArrayString& array) const; |
23324ae1 FM |
253 | |
254 | /** | |
255 | Return the array element at position @e nIndex. An assert failure will | |
39fb8056 FM |
256 | result from an attempt to access an element beyond the end of array in |
257 | debug mode, but no check is done in release mode. | |
258 | ||
259 | This is the operator version of the Item() method. | |
23324ae1 FM |
260 | */ |
261 | wxString operator[](size_t nIndex); | |
262 | }; | |
263 | ||
264 | ||
b7c50e37 FM |
265 | /** |
266 | @class wxSortedArrayString | |
267 | @wxheader{arrstr.h} | |
268 | ||
269 | wxSortedArrayString is an efficient container for storing wxString objects | |
270 | which always keeps the string in alphabetical order. | |
271 | ||
272 | wxSortedArrayString uses binary search in its wxArrayString::Index() function | |
273 | (instead of linear search for wxArrayString::Index()) which makes it much more | |
274 | efficient if you add strings to the array rarely (because, of course, you have | |
275 | to pay for Index() efficiency by having Add() be slower) but search for them | |
276 | often. Several methods should not be used with sorted array (basically, all | |
277 | those which break the order of items) which is mentioned in their description. | |
278 | ||
279 | @todo what about STL? who does it integrates? | |
280 | ||
281 | @library{wxbase} | |
282 | @category{containers} | |
283 | ||
284 | @see wxArray, wxString, @ref overview_string | |
285 | */ | |
286 | class wxSortedArrayString : public wxArrayString | |
287 | { | |
288 | public: | |
289 | ||
290 | /** | |
291 | Copy constructor. Note that when an array is assigned to a sorted array, | |
292 | its contents is automatically sorted during construction. | |
293 | */ | |
294 | wxArrayString(const wxArrayString& array); | |
295 | ||
296 | /** | |
297 | @copydoc wxArrayString::Add() | |
298 | ||
299 | @warning | |
300 | For sorted arrays, the index of the inserted item will not be, in general, | |
301 | equal to GetCount() - 1 because the item is inserted at the correct position | |
302 | to keep the array sorted and not appended. | |
303 | */ | |
304 | size_t Add(const wxString& str, size_t copies = 1); | |
305 | ||
306 | ||
307 | /** | |
308 | @copydoc wxArrayString::Index() | |
309 | ||
3c4f71cc | 310 | This function uses binary search for wxSortedArrayString, but it ignores |
b7c50e37 FM |
311 | the @a bCase and @a bFromEnd parameters. |
312 | */ | |
313 | int Index(const wxString& sz, bool bCase = true, | |
314 | bool bFromEnd = false); | |
315 | ||
316 | /** | |
317 | @warning this function should not be used with sorted arrays because it | |
318 | could break the order of items and, for example, subsequent calls | |
319 | to Index() would then not work! | |
320 | */ | |
321 | void Insert(const wxString& str, size_t nIndex, | |
322 | size_t copies = 1); | |
323 | ||
b02f1c86 | 324 | //@{ |
b7c50e37 FM |
325 | /** |
326 | @warning this function should not be used with sorted array because it could | |
327 | break the order of items and, for example, subsequent calls to Index() | |
b02f1c86 FM |
328 | would then not work! Also, sorting a wxSortedArrayString doesn't make |
329 | sense because its elements are always already sorted. | |
b7c50e37 FM |
330 | */ |
331 | void Sort(bool reverseOrder = false); | |
b7c50e37 | 332 | void Sort(CompareFunction compareFunction); |
b02f1c86 | 333 | //@} |
b7c50e37 FM |
334 | }; |
335 | ||
e54c96f1 | 336 | |
23324ae1 FM |
337 | // ============================================================================ |
338 | // Global functions/macros | |
339 | // ============================================================================ | |
340 | ||
39fb8056 FM |
341 | /** @ingroup group_funcmacro_string */ |
342 | //@{ | |
343 | ||
23324ae1 | 344 | /** |
4cc4bfaf | 345 | Splits the given wxString object using the separator @a sep and returns the |
23324ae1 | 346 | result as a wxArrayString. |
39fb8056 | 347 | |
4cc4bfaf | 348 | If the @a escape character is non-@NULL, then the occurrences of @a sep |
39fb8056 | 349 | immediately prefixed with @a escape are not considered as separators. |
23324ae1 FM |
350 | Note that empty tokens will be generated if there are two or more adjacent |
351 | separators. | |
7c913512 | 352 | |
e54c96f1 | 353 | @see wxJoin() |
23324ae1 FM |
354 | */ |
355 | wxArrayString wxSplit(const wxString& str, const wxChar sep, | |
39fb8056 | 356 | const wxChar escape = '\\'); |
23324ae1 FM |
357 | |
358 | /** | |
39fb8056 FM |
359 | Concatenate all lines of the given wxArrayString object using the separator |
360 | @a sep and returns the result as a wxString. | |
361 | ||
4cc4bfaf | 362 | If the @a escape character is non-@NULL, then it's used as prefix for each |
39fb8056 FM |
363 | occurrence of @e sep in the strings contained in @a arr before joining them |
364 | which is necessary in order to be able to recover the original array contents | |
365 | from the string later using wxSplit(). | |
366 | ||
367 | @see wxSplit() | |
23324ae1 FM |
368 | */ |
369 | wxString wxJoin(const wxArrayString& arr, const wxChar sep, | |
39fb8056 | 370 | const wxChar escape = '\\'); |
23324ae1 | 371 | |
39fb8056 | 372 | //@} |