]>
Commit | Line | Data |
---|---|---|
23324ae1 FM |
1 | ///////////////////////////////////////////////////////////////////////////// |
2 | // Name: dynarray.h | |
e54c96f1 | 3 | // Purpose: interface of wxArray<T> |
23324ae1 FM |
4 | // Author: wxWidgets team |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows license | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
9 | /** | |
10 | @class wxArrayT | |
11 | @wxheader{dynarray.h} | |
7c913512 | 12 | |
23324ae1 FM |
13 | This section describes the so called @e dynamic arrays. This is a C |
14 | array-like type safe data structure i.e. the member access time is constant | |
15 | (and not | |
16 | linear according to the number of container elements as for linked lists). | |
17 | However, these | |
18 | arrays are dynamic in the sense that they will automatically allocate more | |
19 | memory if there is not enough of it for adding a new element. They also perform | |
20 | range checking on the index values but in debug mode only, so please be sure to | |
21 | compile your application in debug mode to use it (see @ref | |
22 | overview_debuggingoverview "debugging overview" for | |
23 | details). So, unlike the arrays in some other | |
24 | languages, attempt to access an element beyond the arrays bound doesn't | |
25 | automatically expand the array but provokes an assertion failure instead in | |
26 | debug build and does nothing (except possibly crashing your program) in the | |
27 | release build. | |
7c913512 | 28 | |
23324ae1 FM |
29 | The array classes were designed to be reasonably efficient, both in terms of |
30 | run-time speed and memory consumption and the executable size. The speed of | |
31 | array item access is, of course, constant (independent of the number of | |
32 | elements) | |
33 | making them much more efficient than linked lists (wxList). | |
34 | Adding items to the arrays is also implemented in more or less constant time - | |
35 | but the price is preallocating the memory in advance. In the @ref | |
36 | wxArray::memorymanagement "memory management" section | |
37 | you may find some useful hints about optimizing wxArray memory usage. As for | |
38 | executable size, all | |
39 | wxArray functions are inline, so they do not take @e any space at all. | |
7c913512 | 40 | |
23324ae1 FM |
41 | wxWidgets has three different kinds of array. All of them derive from |
42 | wxBaseArray class which works with untyped data and can not be used directly. | |
43 | The standard macros WX_DEFINE_ARRAY(), WX_DEFINE_SORTED_ARRAY() and | |
44 | WX_DEFINE_OBJARRAY() are used to define a new class deriving from it. The | |
45 | classes declared will be called in this documentation wxArray, wxSortedArray and | |
46 | wxObjArray but you should keep in mind that no classes with such names actually | |
47 | exist, each time you use one of WX_DEFINE_XXXARRAY macro you define a class | |
48 | with a new name. In fact, these names are "template" names and each usage of one | |
49 | of the macros mentioned above creates a template specialization for the given | |
50 | element type. | |
7c913512 | 51 | |
23324ae1 FM |
52 | wxArray is suitable for storing integer types and pointers which it does not |
53 | treat as objects in any way, i.e. the element pointed to by the pointer is not | |
54 | deleted when the element is removed from the array. It should be noted that | |
55 | all of wxArray's functions are inline, so it costs strictly nothing to define as | |
56 | many array types as you want (either in terms of the executable size or the | |
57 | speed) as long as at least one of them is defined and this is always the case | |
58 | because wxArrays are used by wxWidgets internally. This class has one serious | |
59 | limitation: it can only be used for storing integral types (bool, char, short, | |
60 | int, long and their unsigned variants) or pointers (of any kind). An attempt | |
61 | to use with objects of sizeof() greater than sizeof(long) will provoke a | |
62 | runtime assertion failure, however declaring a wxArray of floats will not (on | |
63 | the machines where sizeof(float) = sizeof(long)), yet it will @b not work, | |
64 | please use wxObjArray for storing floats and doubles. | |
7c913512 | 65 | |
23324ae1 FM |
66 | wxSortedArray is a wxArray variant which should be used when searching in the |
67 | array is a frequently used operation. It requires you to define an additional | |
68 | function for comparing two elements of the array element type and always stores | |
69 | its items in the sorted order (according to this function). Thus, it is | |
70 | wxArray::Index function execution time is O(log(N)) instead of | |
71 | O(N) for the usual arrays but the wxArray::Add method is | |
72 | slower: it is O(log(N)) instead of constant time (neglecting time spent in | |
73 | memory allocation routine). However, in a usual situation elements are added to | |
74 | an array much less often than searched inside it, so wxSortedArray may lead to | |
75 | huge performance improvements compared to wxArray. Finally, it should be | |
76 | noticed that, as wxArray, wxSortedArray can be only used for storing integral | |
77 | types or pointers. | |
7c913512 | 78 | |
23324ae1 FM |
79 | wxObjArray class treats its elements like "objects". It may delete them when |
80 | they are removed from the array (invoking the correct destructor) and copies | |
81 | them using the objects copy constructor. In order to implement this behaviour | |
82 | the definition of the wxObjArray arrays is split in two parts: first, you should | |
83 | declare the new wxObjArray class using WX_DECLARE_OBJARRAY() macro and then | |
84 | you must include the file defining the implementation of template type: | |
85 | wx/arrimpl.cpp and define the array class with WX_DEFINE_OBJARRAY() macro | |
86 | from a point where the full (as opposed to 'forward') declaration of the array | |
87 | elements class is in scope. As it probably sounds very complicated here is an | |
88 | example: | |
7c913512 | 89 | |
23324ae1 FM |
90 | @code |
91 | #include wx/dynarray.h | |
7c913512 | 92 | |
23324ae1 FM |
93 | // we must forward declare the array because it is used inside the class |
94 | // declaration | |
95 | class MyDirectory; | |
96 | class MyFile; | |
7c913512 | 97 | |
23324ae1 FM |
98 | // this defines two new types: ArrayOfDirectories and ArrayOfFiles which can be |
99 | // now used as shown below | |
100 | WX_DECLARE_OBJARRAY(MyDirectory, ArrayOfDirectories); | |
101 | WX_DECLARE_OBJARRAY(MyFile, ArrayOfFiles); | |
7c913512 | 102 | |
23324ae1 FM |
103 | class MyDirectory |
104 | { | |
105 | ... | |
106 | ArrayOfDirectories m_subdirectories; // all subdirectories | |
107 | ArrayOfFiles m_files; // all files in this directory | |
108 | }; | |
7c913512 | 109 | |
23324ae1 | 110 | ... |
7c913512 | 111 | |
23324ae1 FM |
112 | // now that we have MyDirectory declaration in scope we may finish the |
113 | // definition of ArrayOfDirectories -- note that this expands into some C++ | |
114 | // code and so should only be compiled once (i.e., don't put this in the | |
115 | // header, but into a source file or you will get linking errors) | |
116 | #include wx/arrimpl.cpp // this is a magic incantation which must be done! | |
117 | WX_DEFINE_OBJARRAY(ArrayOfDirectories); | |
7c913512 | 118 | |
23324ae1 FM |
119 | // that's all! |
120 | @endcode | |
7c913512 | 121 | |
23324ae1 | 122 | It is not as elegant as writing |
7c913512 | 123 | |
23324ae1 FM |
124 | @code |
125 | typedef std::vectorMyDirectory ArrayOfDirectories; | |
126 | @endcode | |
7c913512 | 127 | |
23324ae1 FM |
128 | but is not that complicated and allows the code to be compiled with any, however |
129 | dumb, C++ compiler in the world. | |
7c913512 FM |
130 | |
131 | Remember to include wx/arrimpl.cpp just before each WX_DEFINE_OBJARRAY | |
23324ae1 | 132 | ocurrence in your code, even if you have several in the same file. |
7c913512 | 133 | |
23324ae1 FM |
134 | Things are much simpler for wxArray and wxSortedArray however: it is enough |
135 | just to write | |
7c913512 | 136 | |
23324ae1 FM |
137 | @code |
138 | WX_DEFINE_ARRAY_INT(int, ArrayOfInts); | |
139 | WX_DEFINE_SORTED_ARRAY_INT(int, ArrayOfSortedInts); | |
140 | @endcode | |
7c913512 | 141 | |
23324ae1 | 142 | i.e. there is only one @c DEFINE macro and no need for separate |
7c913512 | 143 | @c DECLARE one. For the arrays of the primitive types, the macros |
23324ae1 FM |
144 | @c WX_DEFINE_ARRAY_CHAR/SHORT/INT/SIZE_T/LONG/DOUBLE should be used |
145 | depending on the sizeof of the values (notice that storing values of smaller | |
146 | type, e.g. shorts, in an array of larger one, e.g. @c ARRAY_INT, does | |
147 | not work on all architectures!). | |
7c913512 | 148 | |
23324ae1 FM |
149 | @library{wxbase} |
150 | @category{FIXME} | |
7c913512 | 151 | |
e54c96f1 | 152 | @see @ref overview_wxcontaineroverview, wxListT(), wxVectorT() |
23324ae1 | 153 | */ |
7c913512 | 154 | class wxArray<T> |
23324ae1 FM |
155 | { |
156 | public: | |
157 | //@{ | |
158 | /** | |
4cc4bfaf | 159 | Appends the given number of @a copies of the @a item to the array |
23324ae1 | 160 | consisting of the elements of type @e T. |
23324ae1 | 161 | The first version is used with wxArray. The second is used with wxSortedArray, |
4cc4bfaf | 162 | returning the index where @a item is stored. The third and the |
23324ae1 FM |
163 | fourth ones are used with wxObjArray. There is an important difference between |
164 | them: if you give a pointer to the array, it will take ownership of it, i.e. | |
165 | will delete it when the item is deleted from the array. If you give a reference | |
166 | to the array, however, the array will make a copy of the item and will not take | |
167 | ownership of the original item. Once again, it only makes sense for wxObjArrays | |
168 | because the other array types never take ownership of their elements. Also note | |
169 | that you cannot append more than one pointer as reusing it would lead to | |
170 | deleting it twice (or more) and hence to a crash. | |
e54c96f1 | 171 | You may also use WX_APPEND_ARRAY() macro to append all |
23324ae1 | 172 | elements of one array to another one but it is more efficient to use |
4cc4bfaf | 173 | @a copies parameter and modify the elements in place later if you plan to |
23324ae1 FM |
174 | append a lot of items. |
175 | */ | |
176 | void Add(T item, size_t copies = 1); | |
7c913512 | 177 | size_t Add(T item); |
4cc4bfaf FM |
178 | void Add(T* item); |
179 | void Add(T& item, size_t copies = 1); | |
23324ae1 FM |
180 | //@} |
181 | ||
182 | /** | |
4cc4bfaf | 183 | Inserts the given @a item into the array in the specified @e index |
23324ae1 | 184 | position. |
23324ae1 FM |
185 | Be aware that you will set out the order of the array if you give a wrong |
186 | position. | |
7c913512 | 187 | This function is useful in conjunction with |
23324ae1 FM |
188 | wxArray::IndexForInsert for a common operation |
189 | of "insert only if not found". | |
190 | */ | |
191 | void AddAt(T item, size_t index); | |
192 | ||
193 | /** | |
194 | wxArray::Add | |
3c4f71cc | 195 | |
23324ae1 | 196 | wxArray::AddAt |
3c4f71cc | 197 | |
23324ae1 | 198 | wxArray::Insert |
3c4f71cc | 199 | |
23324ae1 | 200 | wxArray::SetCount |
3c4f71cc | 201 | |
e54c96f1 | 202 | WX_APPEND_ARRAY() |
3c4f71cc | 203 | |
e54c96f1 | 204 | WX_PREPEND_ARRAY() |
23324ae1 FM |
205 | */ |
206 | ||
207 | ||
208 | /** | |
209 | Preallocates memory for a given number of array elements. It is worth calling | |
210 | when the number of items which are going to be added to the array is known in | |
211 | advance because it will save unneeded memory reallocation. If the array already | |
212 | has enough memory for the given number of items, nothing happens. In any case, | |
213 | the existing contents of the array is not modified. | |
214 | */ | |
215 | void Alloc(size_t count); | |
216 | ||
217 | /** | |
218 | This function does the same as wxArray::Empty and additionally | |
219 | frees the memory allocated to the array. | |
220 | */ | |
221 | void Clear(); | |
222 | ||
223 | /** | |
224 | Array classes are 100% C++ objects and as such they have the appropriate copy | |
225 | constructors and assignment operators. Copying wxArray just copies the elements | |
226 | but copying wxObjArray copies the arrays items. However, for memory-efficiency | |
227 | sake, neither of these classes has virtual destructor. It is not very important | |
228 | for wxArray which has trivial destructor anyhow, but it does mean that you | |
229 | should avoid deleting wxObjArray through a wxBaseArray pointer (as you would | |
230 | never use wxBaseArray anyhow it shouldn't be a problem) and that you should not | |
231 | derive your own classes from the array classes. | |
23324ae1 | 232 | @ref wxArray::ctordef "wxArray default constructor" |
3c4f71cc | 233 | |
23324ae1 | 234 | @ref wxArray::ctorcopy "wxArray copy constructors and assignment operators" |
3c4f71cc | 235 | |
23324ae1 FM |
236 | @ref wxArray::dtor ~wxArray |
237 | */ | |
238 | ||
239 | ||
240 | //@{ | |
241 | /** | |
242 | (T first, T second)@e compareFunction) | |
23324ae1 FM |
243 | There is no default constructor for wxSortedArray classes - you must initialize |
244 | it | |
245 | with a function to use for item comparison. It is a function which is passed | |
246 | two arguments of type @e T where @e T is the array element type and which | |
247 | should return a negative, zero or positive value according to whether the first | |
248 | element passed to it is less than, equal to or greater than the second one. | |
249 | */ | |
7c913512 FM |
250 | wxArray(); |
251 | wxObjArray(); | |
252 | wxSortedArray(); | |
23324ae1 FM |
253 | //@} |
254 | ||
255 | /** | |
256 | Removes the element from the array, but, unlike, | |
257 | wxArray::Remove doesn't delete it. The function returns the | |
258 | pointer to the removed element. | |
259 | */ | |
4cc4bfaf | 260 | T* Detach(size_t index); |
23324ae1 FM |
261 | |
262 | /** | |
263 | Empties the array. For wxObjArray classes, this destroys all of the array | |
264 | elements. For wxArray and wxSortedArray this does nothing except marking the | |
265 | array of being empty - this function does not free the allocated memory, use | |
266 | wxArray::Clear for this. | |
267 | */ | |
268 | void Empty(); | |
269 | ||
270 | /** | |
271 | Return the number of items in the array. | |
272 | */ | |
328f5751 | 273 | size_t GetCount() const; |
23324ae1 FM |
274 | |
275 | //@{ | |
276 | /** | |
277 | The first version of the function is for wxArray and wxObjArray, the second is | |
278 | for wxSortedArray only. | |
23324ae1 | 279 | Searches the element in the array, starting from either beginning or the end |
4cc4bfaf | 280 | depending on the value of @a searchFromEnd parameter. @c wxNOT_FOUND is |
23324ae1 FM |
281 | returned if the element is not found, otherwise the index of the element is |
282 | returned. | |
23324ae1 FM |
283 | Linear search is used for the wxArray and wxObjArray classes but binary search |
284 | in the sorted array is used for wxSortedArray (this is why searchFromEnd | |
285 | parameter doesn't make sense for it). | |
23324ae1 FM |
286 | @b NB: even for wxObjArray classes, the operator==() of the elements in the |
287 | array is @b not used by this function. It searches exactly the given | |
288 | element in the array and so will only succeed if this element had been | |
289 | previously added to the array, but fail even if another, identical, element is | |
290 | in the array. | |
291 | */ | |
328f5751 FM |
292 | int Index(T& item, bool searchFromEnd = false) const; |
293 | const int Index(T& item) const; | |
23324ae1 FM |
294 | //@} |
295 | ||
296 | /** | |
4cc4bfaf | 297 | Search for a place to insert @a item into the sorted array (binary search). |
23324ae1 FM |
298 | The index returned is just before the first existing item that is greater or |
299 | equal | |
300 | (according to the compare function) to the given @e item. | |
4cc4bfaf | 301 | You have to do extra work to know if the @a item already exists in array. |
7c913512 | 302 | This function is useful in conjunction with |
23324ae1 FM |
303 | wxArray::AddAt for a common operation |
304 | of "insert only if not found". | |
305 | */ | |
328f5751 | 306 | size_t IndexForInsert(T item) const; |
23324ae1 FM |
307 | |
308 | //@{ | |
309 | /** | |
4cc4bfaf FM |
310 | Insert the given number of @a copies of the @a item into the array before |
311 | the existing item @a n - thus, @e Insert(something, 0u) will insert an | |
23324ae1 | 312 | item in such way that it will become the first array element. |
23324ae1 FM |
313 | wxSortedArray doesn't have this function because inserting in wrong place |
314 | would break its sorted condition. | |
23324ae1 FM |
315 | Please see wxArray::Add for explanation of the differences |
316 | between the overloaded versions of this function. | |
317 | */ | |
318 | void Insert(T item, size_t n, size_t copies = 1); | |
4cc4bfaf FM |
319 | void Insert(T* item, size_t n); |
320 | void Insert(T& item, size_t n, size_t copies = 1); | |
23324ae1 FM |
321 | //@} |
322 | ||
323 | /** | |
324 | Returns @true if the array is empty, @false otherwise. | |
325 | */ | |
328f5751 | 326 | bool IsEmpty() const; |
23324ae1 FM |
327 | |
328 | /** | |
4cc4bfaf | 329 | Returns the item at the given position in the array. If @a index is out of |
23324ae1 FM |
330 | bounds, an assert failure is raised in the debug builds but nothing special is |
331 | done in the release build. | |
23324ae1 FM |
332 | The returned value is of type "reference to the array element type" for all of |
333 | the array classes. | |
334 | */ | |
328f5751 | 335 | T Item(size_t index) const; |
23324ae1 FM |
336 | |
337 | /** | |
338 | Returns the last element in the array, i.e. is the same as Item(GetCount() - 1). | |
339 | An assert failure is raised in the debug mode if the array is empty. | |
23324ae1 FM |
340 | The returned value is of type "reference to the array element type" for all of |
341 | the array classes. | |
342 | */ | |
328f5751 | 343 | T Last() const; |
23324ae1 FM |
344 | |
345 | /** | |
346 | To use an array you must first define the array class. This is done with the | |
347 | help of the macros in this section. The class of array elements must be (at | |
348 | least) forward declared for WX_DEFINE_ARRAY, WX_DEFINE_SORTED_ARRAY and | |
349 | WX_DECLARE_OBJARRAY macros and must be fully declared before you use | |
350 | WX_DEFINE_OBJARRAY macro. | |
e54c96f1 | 351 | WX_DEFINE_ARRAY() |
3c4f71cc | 352 | |
e54c96f1 | 353 | WX_DEFINE_EXPORTED_ARRAY() |
3c4f71cc | 354 | |
e54c96f1 | 355 | WX_DEFINE_USER_EXPORTED_ARRAY() |
3c4f71cc | 356 | |
e54c96f1 | 357 | WX_DEFINE_SORTED_ARRAY() |
3c4f71cc | 358 | |
e54c96f1 | 359 | WX_DEFINE_SORTED_EXPORTED_ARRAY() |
3c4f71cc | 360 | |
e54c96f1 | 361 | WX_DEFINE_SORTED_USER_EXPORTED_ARRAY() |
3c4f71cc | 362 | |
e54c96f1 | 363 | WX_DECLARE_EXPORTED_OBJARRAY() |
3c4f71cc | 364 | |
e54c96f1 | 365 | WX_DECLARE_USER_EXPORTED_OBJARRAY() |
3c4f71cc | 366 | |
e54c96f1 | 367 | WX_DEFINE_OBJARRAY() |
3c4f71cc | 368 | |
e54c96f1 | 369 | WX_DEFINE_EXPORTED_OBJARRAY() |
3c4f71cc | 370 | |
e54c96f1 | 371 | WX_DEFINE_USER_EXPORTED_OBJARRAY() |
23324ae1 FM |
372 | To slightly complicate the matters even further, the operator - defined by |
373 | default for the array iterators by these macros only makes sense if the array | |
374 | element type is not a pointer itself and, although it still works, this | |
375 | provokes warnings from some compilers and to avoid them you should use the | |
376 | @c _PTR versions of the macros above. For example, to define an array of | |
377 | pointers to @c double you should use: | |
3c4f71cc | 378 | |
23324ae1 FM |
379 | Note that the above macros are generally only useful for |
380 | wxObject types. There are separate macros for declaring an array of a simple | |
381 | type, | |
382 | such as an int. | |
23324ae1 | 383 | The following simple types are supported: |
3c4f71cc | 384 | |
23324ae1 | 385 | int |
3c4f71cc | 386 | |
23324ae1 | 387 | long |
3c4f71cc | 388 | |
23324ae1 | 389 | size_t |
3c4f71cc | 390 | |
23324ae1 | 391 | double |
23324ae1 FM |
392 | To create an array of a simple type, simply append the type you want in CAPS to |
393 | the array definition. | |
23324ae1 | 394 | For example, for an integer array, you'd use one of the following variants: |
e54c96f1 | 395 | WX_DEFINE_ARRAY_INT() |
3c4f71cc | 396 | |
e54c96f1 | 397 | WX_DEFINE_EXPORTED_ARRAY_INT() |
3c4f71cc | 398 | |
e54c96f1 | 399 | WX_DEFINE_USER_EXPORTED_ARRAY_INT() |
3c4f71cc | 400 | |
e54c96f1 | 401 | WX_DEFINE_SORTED_ARRAY_INT() |
3c4f71cc | 402 | |
e54c96f1 | 403 | WX_DEFINE_SORTED_EXPORTED_ARRAY_INT() |
3c4f71cc | 404 | |
e54c96f1 | 405 | WX_DEFINE_SORTED_USER_EXPORTED_ARRAY_INT() |
23324ae1 FM |
406 | */ |
407 | ||
408 | ||
409 | /** | |
410 | Automatic array memory management is quite trivial: the array starts by | |
411 | preallocating some minimal amount of memory (defined by | |
412 | WX_ARRAY_DEFAULT_INITIAL_SIZE) and when further new items exhaust already | |
413 | allocated memory it reallocates it adding 50% of the currently allocated | |
414 | amount, but no more than some maximal number which is defined by | |
415 | ARRAY_MAXSIZE_INCREMENT constant. Of course, this may lead to some memory | |
416 | being wasted (ARRAY_MAXSIZE_INCREMENT in the worst case, i.e. 4Kb in the | |
417 | current implementation), so the wxArray::Shrink function is | |
418 | provided to deallocate the extra memory. The wxArray::Alloc | |
419 | function can also be quite useful if you know in advance how many items you are | |
420 | going to put in the array and will prevent the array code from reallocating the | |
421 | memory more times than needed. | |
23324ae1 | 422 | wxArray::Alloc |
3c4f71cc | 423 | |
23324ae1 FM |
424 | wxArray::Shrink |
425 | */ | |
426 | ||
427 | ||
428 | /** | |
429 | Functions in this section return the total number of array elements and allow to | |
430 | retrieve them - possibly using just the C array indexing [] operator which | |
431 | does exactly the same as wxArray::Item method. | |
23324ae1 | 432 | wxArray::GetCount |
3c4f71cc | 433 | |
23324ae1 | 434 | wxArray::IsEmpty |
3c4f71cc | 435 | |
23324ae1 | 436 | wxArray::Item |
3c4f71cc | 437 | |
23324ae1 FM |
438 | wxArray::Last |
439 | */ | |
440 | ||
441 | ||
442 | /** | |
443 | Removes an element from the array by value: the first item of the | |
4cc4bfaf | 444 | array equal to @a item is removed, an assert failure will result from an |
23324ae1 | 445 | attempt to remove an item which doesn't exist in the array. |
23324ae1 | 446 | When an element is removed from wxObjArray it is deleted by the array - use |
e54c96f1 | 447 | Detach() if you don't want this to happen. On the |
23324ae1 FM |
448 | other hand, when an object is removed from a wxArray nothing happens - you |
449 | should delete it manually if required: | |
3c4f71cc | 450 | |
e54c96f1 | 451 | See also WX_CLEAR_ARRAY() macro which deletes all |
23324ae1 FM |
452 | elements of a wxArray (supposed to contain pointers). |
453 | */ | |
7c913512 | 454 | Remove(T item); |
23324ae1 FM |
455 | |
456 | /** | |
4cc4bfaf | 457 | Removes @a count elements starting at @a index from the array. When an |
23324ae1 | 458 | element is removed from wxObjArray it is deleted by the array - use |
e54c96f1 | 459 | Detach() if you don't want this to happen. On |
23324ae1 FM |
460 | the other hand, when an object is removed from a wxArray nothing happens - |
461 | you should delete it manually if required: | |
3c4f71cc | 462 | |
e54c96f1 | 463 | See also WX_CLEAR_ARRAY() macro which deletes all |
23324ae1 FM |
464 | elements of a wxArray (supposed to contain pointers). |
465 | */ | |
7c913512 | 466 | RemoveAt(size_t index, size_t count = 1); |
23324ae1 FM |
467 | |
468 | /** | |
e54c96f1 | 469 | WX_CLEAR_ARRAY() |
3c4f71cc | 470 | |
23324ae1 | 471 | wxArray::Empty |
3c4f71cc | 472 | |
23324ae1 | 473 | wxArray::Clear |
3c4f71cc | 474 | |
23324ae1 | 475 | wxArray::RemoveAt |
3c4f71cc | 476 | |
23324ae1 FM |
477 | wxArray::Remove |
478 | */ | |
479 | ||
480 | ||
481 | /** | |
482 | wxArray::Index | |
3c4f71cc | 483 | |
23324ae1 | 484 | wxArray::IndexForInsert |
3c4f71cc | 485 | |
23324ae1 FM |
486 | wxArray::Sort |
487 | */ | |
488 | ||
489 | ||
490 | /** | |
491 | ) | |
23324ae1 | 492 | This function ensures that the number of array elements is at least |
4cc4bfaf | 493 | @e count. If the array has already @a count or more items, nothing is |
23324ae1 FM |
494 | done. Otherwise, @c count - GetCount() elements are added and initialized to |
495 | the value @e defval. | |
3c4f71cc | 496 | |
4cc4bfaf | 497 | @see wxArray::GetCount |
23324ae1 FM |
498 | */ |
499 | void SetCount(size_t count); | |
500 | ||
501 | /** | |
502 | Frees all memory unused by the array. If the program knows that no new items | |
503 | will be added to the array it may call Shrink() to reduce its memory usage. | |
504 | However, if a new item is added to the array, some extra memory will be | |
505 | allocated again. | |
506 | */ | |
507 | void Shrink(); | |
508 | ||
509 | /** | |
510 | The notation CMPFUNCT should be read as if we had the following declaration: | |
3c4f71cc | 511 | |
23324ae1 FM |
512 | where @e T is the type of the array elements. I.e. it is a function returning |
513 | @e int which is passed two arguments of type @e T *. | |
23324ae1 FM |
514 | Sorts the array using the specified compare function: this function should |
515 | return a negative, zero or positive value according to whether the first element | |
516 | passed to it is less than, equal to or greater than the second one. | |
23324ae1 FM |
517 | wxSortedArray doesn't have this function because it is always sorted. |
518 | */ | |
519 | void Sort(CMPFUNC<T> compareFunction); | |
520 | ||
521 | /** | |
4cc4bfaf | 522 | This macro may be used to append all elements of the @a other array to the |
23324ae1 FM |
523 | @e array. The two arrays must be of the same type. |
524 | */ | |
525 | #define void WX_APPEND_ARRAY(wxArray& array, wxArray& other) /* implementation is private */ | |
526 | ||
527 | /** | |
528 | This macro may be used to delete all elements of the array before emptying it. | |
529 | It can not be used with wxObjArrays - but they will delete their elements anyhow | |
530 | when you call Empty(). | |
531 | */ | |
532 | #define void WX_CLEAR_ARRAY(wxArray& array) /* implementation is private */ | |
533 | ||
534 | //@{ | |
535 | /** | |
4cc4bfaf | 536 | This macro declares a new object array class named @a name and containing |
23324ae1 FM |
537 | the elements of type @e T. The second form is used when compiling wxWidgets as |
538 | a DLL under Windows and array needs to be visible outside the DLL. The third is | |
539 | needed for exporting an array from a user DLL. | |
23324ae1 | 540 | Example: |
3c4f71cc | 541 | |
e54c96f1 | 542 | You must use WX_DEFINE_OBJARRAY() macro to define |
23324ae1 FM |
543 | the array class - otherwise you would get link errors. |
544 | */ | |
4cc4bfaf FM |
545 | WX_DECLARE_OBJARRAY(T, name); |
546 | WX_DECLARE_EXPORTED_OBJARRAY(T, name); | |
547 | WX_DECLARE_USER_EXPORTED_OBJARRAY(T, name); | |
23324ae1 FM |
548 | //@} |
549 | ||
550 | //@{ | |
551 | /** | |
4cc4bfaf | 552 | This macro defines a new array class named @a name and containing the |
23324ae1 FM |
553 | elements of type @e T. The second form is used when compiling wxWidgets as |
554 | a DLL under Windows and array needs to be visible outside the DLL. The third is | |
555 | needed for exporting an array from a user DLL. | |
23324ae1 | 556 | Example: |
3c4f71cc | 557 | |
23324ae1 FM |
558 | Note that wxWidgets predefines the following standard array classes: @b |
559 | wxArrayInt, | |
560 | @b wxArrayLong, @b wxArrayShort, @b wxArrayDouble, @b wxArrayPtrVoid. | |
561 | */ | |
4cc4bfaf FM |
562 | WX_DEFINE_ARRAY(T, name); |
563 | WX_DEFINE_EXPORTED_ARRAY(T, name); | |
564 | WX_DEFINE_USER_EXPORTED_ARRAY(T, name, exportspec); | |
23324ae1 FM |
565 | //@} |
566 | ||
567 | //@{ | |
568 | /** | |
4cc4bfaf | 569 | This macro defines the methods of the array class @a name not defined by the |
e54c96f1 | 570 | WX_DECLARE_OBJARRAY() macro. You must include the |
23324ae1 FM |
571 | file wx/arrimpl.cpp before using this macro and you must have the full |
572 | declaration of the class of array elements in scope! If you forget to do the | |
573 | first, the error will be caught by the compiler, but, unfortunately, many | |
574 | compilers will not give any warnings if you forget to do the second - but the | |
575 | objects of the class will not be copied correctly and their real destructor will | |
576 | not be called. The latter two forms are merely aliases of the first to satisfy | |
577 | some people's sense of symmetry when using the exported declarations. | |
23324ae1 FM |
578 | Example of usage: |
579 | */ | |
7c913512 FM |
580 | WX_DEFINE_OBJARRAY(name); |
581 | WX_DEFINE_EXPORTED_OBJARRAY(name); | |
582 | WX_DEFINE_USER_EXPORTED_OBJARRAY(name); | |
23324ae1 FM |
583 | //@} |
584 | ||
585 | //@{ | |
586 | /** | |
4cc4bfaf | 587 | This macro defines a new sorted array class named @a name and containing |
23324ae1 FM |
588 | the elements of type @e T. The second form is used when compiling wxWidgets as |
589 | a DLL under Windows and array needs to be visible outside the DLL. The third is | |
590 | needed for exporting an array from a user DLL. | |
23324ae1 | 591 | Example: |
3c4f71cc | 592 | |
23324ae1 FM |
593 | You will have to initialize the objects of this class by passing a comparison |
594 | function to the array object constructor like this: | |
595 | */ | |
4cc4bfaf FM |
596 | WX_DEFINE_SORTED_ARRAY(T, name); |
597 | WX_DEFINE_SORTED_EXPORTED_ARRAY(T, name); | |
598 | WX_DEFINE_SORTED_USER_EXPORTED_ARRAY(T, name); | |
23324ae1 FM |
599 | //@} |
600 | ||
601 | /** | |
4cc4bfaf | 602 | This macro may be used to prepend all elements of the @a other array to the |
23324ae1 FM |
603 | @e array. The two arrays must be of the same type. |
604 | */ | |
605 | #define void WX_PREPEND_ARRAY(wxArray& array, wxArray& other) /* implementation is private */ | |
606 | ||
607 | //@{ | |
608 | /** | |
609 | The copy constructors and assignment operators perform a shallow array copy | |
610 | (i.e. they don't copy the objects pointed to even if the source array contains | |
611 | the items of pointer type) for wxArray and wxSortedArray and a deep copy (i.e. | |
612 | the array element are copied too) for wxObjArray. | |
613 | */ | |
7c913512 FM |
614 | wxArray(const wxArray& array); |
615 | wxSortedArray(const wxSortedArray& array); | |
616 | wxObjArray(const wxObjArray& array); | |
617 | wxArray operator=(const wxArray& array); | |
618 | wxSortedArray operator=(const wxSortedArray& array); | |
619 | wxObjArray operator=(const wxObjArray& array); | |
23324ae1 FM |
620 | //@} |
621 | ||
622 | //@{ | |
623 | /** | |
624 | The wxObjArray destructor deletes all the items owned by the array. This is not | |
625 | done by wxArray and wxSortedArray versions - you may use | |
e54c96f1 | 626 | WX_CLEAR_ARRAY() macro for this. |
23324ae1 | 627 | */ |
7c913512 FM |
628 | ~wxArray(); |
629 | ~wxSortedArray(); | |
630 | ~wxObjArray(); | |
23324ae1 FM |
631 | //@} |
632 | }; | |
e54c96f1 | 633 |