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