]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/array.tex
Added missing files to listing
[wxWidgets.git] / docs / latex / wx / array.tex
1 \section{\class{wxArray}}\label{wxarray}
2
3 This section describes the so called {\it dynamic arrays}. This is a C
4 array-like data structure i.e. the member access time is constant (and not
5 linear according to the number of container elements as for linked lists). However, these
6 arrays are dynamic in the sense that they will automatically allocate more
7 memory if there is not enough of it for adding a new element. They also perform
8 range checking on the index values but in debug mode only, so please be sure to
9 compile your application in debug mode to use it (see \helpref{debugging overview}{debuggingoverview} for
10 details). So, unlike the arrays in some other
11 languages, attempt to access an element beyond the arrays bound doesn't
12 automatically expand the array but provokes an assertion failure instead in
13 debug build and does nothing (except possibly crashing your program) in the
14 release build.
15
16 The array classes were designed to be reasonably efficient, both in terms of
17 run-time speed and memory consumption and the executable size. The speed of
18 array item access is, of course, constant (independent of the number of elements)
19 making them much more efficient than linked lists (\helpref{wxList}{wxlist}).
20 Adding items to the arrays is also implemented in more or less constant time -
21 but the price is preallocating the memory in advance. In the \helpref{memory management}{wxarraymemorymanagement} section
22 you may find some useful hints about optimizing wxArray memory usage. As for executable size, all
23 wxArray functions are inline, so they do not take {\it any space at all}.
24
25 wxWindows has three different kinds of array. All of them derive from
26 wxBaseArray class which works with untyped data and can not be used directly.
27 The standard macros WX\_DEFINE\_ARRAY(), WX\_DEFINE\_SORTED\_ARRAY() and
28 WX\_DEFINE\_OBJARRAY() are used to define a new class deriving from it. The
29 classes declared will be called in this documentation wxArray, wxSortedArray and
30 wxObjArray but you should keep in mind that no classes with such names actually
31 exist, each time you use one of WX\_DEFINE\_XXXARRAY macro you define a class
32 with a new name. In fact, these names are "template" names and each usage of one
33 of the macros mentioned above creates a template specialization for the given
34 element type.
35
36 wxArray is suitable for storing integer types and pointers which it does not
37 treat as objects in any way, i.e. the element pointed to by the pointer is not
38 deleted when the element is removed from the array. It should be noted that
39 all of wxArray's functions are inline, so it costs strictly nothing to define as
40 many array types as you want (either in terms of the executable size or the
41 speed) as long as at least one of them is defined and this is always the case
42 because wxArrays are used by wxWindows internally. This class has one serious
43 limitation: it can only be used for storing integral types (bool, char, short,
44 int, long and their unsigned variants) or pointers (of any kind). An attempt
45 to use with objects of sizeof() greater than sizeof(long) will provoke a
46 runtime assertion failure, however declaring a wxArray of floats will not (on
47 the machines where sizeof(float) <= sizeof(long)), yet it will {\bf not} work,
48 please use wxObjArray for storing floats and doubles (NB: a more efficient
49 wxArrayDouble class is scheduled for the next release of wxWindows).
50
51 wxSortedArray is a wxArray variant which should be used when searching in the
52 array is a frequently used operation. It requires you to define an additional
53 function for comparing two elements of the array element type and always stores
54 its items in the sorted order (according to this function). Thus, it is
55 \helpref{Index()}{wxarrayindex} function execution time is $O(log(N))$ instead of
56 $O(N)$ for the usual arrays but the \helpref{Add()}{wxarrayadd} method is
57 slower: it is $O(log(N))$ instead of constant time (neglecting time spent in
58 memory allocation routine). However, in a usual situation elements are added to
59 an array much less often than searched inside it, so wxSortedArray may lead to
60 huge performance improvements compared to wxArray. Finally, it should be
61 noticed that, as wxArray, wxSortedArray can be only used for storing integral
62 types or pointers.
63
64 wxObjArray class treats its elements like "objects". It may delete them when
65 they are removed from the array (invoking the correct destructor) and copies
66 them using the objects copy constructor. In order to implement this behaviour
67 the definition of the wxObjArray arrays is split in two parts: first, you should
68 declare the new wxObjArray class using WX\_DECLARE\_OBJARRAY() macro and then
69 you must include the file defining the implementation of template type:
70 <wx/arrimpl.cpp> and define the array class with WX\_DEFINE\_OBJARRAY() macro
71 from a point where the full (as opposed to `forward') declaration of the array
72 elements class is in scope. As it probably sounds very complicated here is an
73 example:
74
75 \begin{verbatim}
76 #include <wx/dynarray.h>
77
78 // we must forward declare the array because it is used inside the class
79 // declaration
80 class MyDirectory;
81 class MyFile;
82
83 // this defines two new types: ArrayOfDirectories and ArrayOfFiles which can be
84 // now used as shown below
85 WX_DECLARE_OBJARRAY(MyDirectory, ArrayOfDirectories);
86 WX_DECLARE_OBJARRAY(MyFile, ArrayOfFiles);
87
88 class MyDirectory
89 {
90 ...
91 ArrayOfDirectories m_subdirectories; // all subdirectories
92 ArrayOfFiles m_files; // all files in this directory
93 };
94
95 ...
96
97 // now that we have MyDirectory declaration in scope we may finish the
98 // definition of ArrayOfDirectories -- note that this expands into some C++
99 // code and so should only be compiled once (i.e., don't put this in the
100 // header, but into a source file or you will get linkin errors)
101 #include <wx/arrimpl.cpp> // this is a magic incantation which must be done!
102 WX_DEFINE_OBJARRAY(ArrayOfDirectories);
103
104 // that's all!
105 \end{verbatim}
106
107 It is not as elegant as writing
108
109 \begin{verbatim}
110 typedef std::vector<MyDirectory> ArrayOfDirectories;
111 \end{verbatim}
112
113 but is not that complicated and allows the code to be compiled with any, however
114 dumb, C++ compiler in the world.
115
116 Things are much simpler for wxArray and wxSortedArray however: it is enough
117 just to write
118
119 \begin{verbatim}
120 WX_DEFINE_ARRAY(MyDirectory *, ArrayOfDirectories);
121 WX_DEFINE_SORTED_ARRAY(MyFile *, ArrayOfFiles);
122 \end{verbatim}
123
124 \wxheading{See also:}
125
126 \helpref{Container classes overview}{wxcontaineroverview}, \helpref{wxList}{wxlist}
127
128 \wxheading{Include files}
129
130 <wx/dynarray.h> for wxArray and wxSortedArray and additionally <wx/arrimpl.cpp>
131 for wxObjArray.
132
133 \latexignore{\rtfignore{\wxheading{Function groups}}}
134
135 \membersection{Macros for template array definition}
136
137 To use an array you must first define the array class. This is done with the
138 help of the macros in this section. The class of array elements must be (at
139 least) forward declared for WX\_DEFINE\_ARRAY, WX\_DEFINE\_SORTED\_ARRAY and
140 WX\_DECLARE\_OBJARRAY macros and must be fully declared before you use
141 WX\_DEFINE\_OBJARRAY macro.
142
143 \helpref{WX\_DEFINE\_ARRAY}{wxdefinearray}\\
144 \helpref{WX\_DEFINE\_EXPORTED\_ARRAY}{wxdefinearray}\\
145 \helpref{WX\_DEFINE\_SORTED\_ARRAY}{wxdefinesortedarray}\\
146 \helpref{WX\_DEFINE\_SORTED\_EXPORTED\_ARRAY}{wxdefinesortedarray}\\
147 \helpref{WX\_DECLARE\_EXPORTED\_OBJARRAY}{wxdeclareobjarray}\\
148 \helpref{WX\_DEFINE\_OBJARRAY}{wxdefineobjarray}
149
150 \membersection{Constructors and destructors}
151
152 Array classes are 100\% C++ objects and as such they have the appropriate copy
153 constructors and assignment operators. Copying wxArray just copies the elements
154 but copying wxObjArray copies the arrays items. However, for memory-efficiency
155 sake, neither of these classes has virtual destructor. It is not very important
156 for wxArray which has trivial destructor anyhow, but it does mean that you
157 should avoid deleting wxObjArray through a wxBaseArray pointer (as you would
158 never use wxBaseArray anyhow it shouldn't be a problem) and that you should not
159 derive your own classes from the array classes.
160
161 \helpref{wxArray default constructor}{wxarrayctordef}\\
162 \helpref{wxArray copy constructors and assignment operators}{wxarrayctorcopy}\\
163 \helpref{\destruct{wxArray}}{wxarraydtor}
164
165 \membersection{Memory management}\label{wxarraymemorymanagement}
166
167 Automatic array memory management is quite trivial: the array starts by
168 preallocating some minimal amount of memory (defined by
169 WX\_ARRAY\_DEFAULT\_INITIAL\_SIZE) and when further new items exhaust already
170 allocated memory it reallocates it adding 50\% of the currently allocated
171 amount, but no more than some maximal number which is defined by
172 ARRAY\_MAXSIZE\_INCREMENT constant. Of course, this may lead to some memory
173 being wasted (ARRAY\_MAXSIZE\_INCREMENT in the worst case, i.e. 4Kb in the
174 current implementation), so the \helpref{Shrink()}{wxarrayshrink} function is
175 provided to unallocate the extra memory. The \helpref{Alloc()}{wxarrayalloc}
176 function can also be quite useful if you know in advance how many items you are
177 going to put in the array and will prevent the array code from reallocating the
178 memory more times than needed.
179
180 \helpref{Alloc}{wxarrayalloc}\\
181 \helpref{Shrink}{wxarrayshrink}
182
183 \membersection{Number of elements and simple item access}
184
185 Functions in this section return the total number of array elements and allow to
186 retrieve them - possibly using just the C array indexing $[]$ operator which
187 does exactly the same as \helpref{Item()}{wxarrayitem} method.
188
189 \helpref{Count}{wxarraycount}\\
190 \helpref{GetCount}{wxarraygetcount}\\
191 \helpref{IsEmpty}{wxarrayisempty}\\
192 \helpref{Item}{wxarrayitem}\\
193 \helpref{Last}{wxarraylast}
194
195 \membersection{Adding items}
196
197 \helpref{Add}{wxarrayadd}\\
198 \helpref{Insert}{wxarrayinsert}\\
199 \helpref{WX\_APPEND\_ARRAY}{wxappendarray}
200
201 \membersection{Removing items}
202
203 \helpref{WX\_CLEAR\_ARRAY}{wxcleararray}\\
204 \helpref{Empty}{wxarrayempty}\\
205 \helpref{Clear}{wxarrayclear}\\
206 \helpref{RemoveAt}{wxarrayremoveat}\\
207 \helpref{Remove}{wxarrayremove}
208
209 \membersection{Searching and sorting}
210
211 \helpref{Index}{wxarrayindex}\\
212 \helpref{Sort}{wxarraysort}
213
214 %%%%% MEMBERS HERE %%%%%
215 \helponly{\insertatlevel{2}{
216
217 \wxheading{Members}
218
219 }}
220
221 \membersection{WX\_DEFINE\_ARRAY}\label{wxdefinearray}
222
223 \func{}{WX\_DEFINE\_ARRAY}{\param{}{T}, \param{}{name}}
224
225 \func{}{WX\_DEFINE\_EXPORTED\_ARRAY}{\param{}{T}, \param{}{name}}
226
227 This macro defines a new array class named {\it name} and containing the
228 elements of type {\it T}. The second form is used when compiling DLL
229 under Windows and array needs to be visible outside the DLL.
230 Example:
231
232 \begin{verbatim}
233 WX_DEFINE_ARRAY(int, wxArrayInt);
234
235 class MyClass;
236 WX_DEFINE_ARRAY(MyClass *, wxArrayOfMyClass);
237 \end{verbatim}
238
239 Note that wxWindows predefines the following standard array classes: wxArrayInt,
240 wxArrayLong and wxArrayPtrVoid.
241
242 \membersection{WX\_DEFINE\_SORTED\_ARRAY}\label{wxdefinesortedarray}
243
244 \func{}{WX\_DEFINE\_SORTED\_ARRAY}{\param{}{T}, \param{}{name}}
245
246 \func{}{WX\_DEFINE\_SORTED\_EXPORTED\_ARRAY}{\param{}{T}, \param{}{name}}
247
248 This macro defines a new sorted array class named {\it name} and containing
249 the elements of type {\it T}. The second form is used when compiling DLL
250 under Windows and array needs to be visible outside the DLL.
251
252 Example:
253
254 \begin{verbatim}
255 WX_DEFINE_SORTED_ARRAY(int, wxSortedArrayInt);
256
257 class MyClass;
258 WX_DEFINE_SORTED_ARRAY(MyClass *, wxArrayOfMyClass);
259 \end{verbatim}
260
261 You will have to initialize the objects of this class by passing a comparison
262 function to the array object constructor like this:
263
264 \begin{verbatim}
265 int CompareInts(int n1, int n2)
266 {
267 return n1 - n2;
268 }
269
270 wxSortedArrayInt sorted(CompareInts);
271
272 int CompareMyClassObjects(MyClass *item1, MyClass *item2)
273 {
274 // sort the items by their address...
275 return Stricmp(item1->GetAddress(), item2->GetAddress());
276 }
277
278 wxArrayOfMyClass another(CompareMyClassObjects);
279 \end{verbatim}
280
281 \membersection{WX\_DECLARE\_OBJARRAY}\label{wxdeclareobjarray}
282
283 \func{}{WX\_DECLARE\_OBJARRAY}{\param{}{T}, \param{}{name}}
284
285 \func{}{WX\_DECLARE\_EXPORTED\_OBJARRAY}{\param{}{T}, \param{}{name}}
286
287 This macro declares a new object array class named {\it name} and containing
288 the elements of type {\it T}. The second form is used when compiling DLL
289 under Windows and array needs to be visible outside the DLL.
290
291 Example:
292
293 \begin{verbatim}
294 class MyClass;
295 WX_DEFINE_OBJARRAY(MyClass, wxArrayOfMyClass); // note: not "MyClass *"!
296 \end{verbatim}
297
298 You must use \helpref{WX\_DEFINE\_OBJARRAY()}{wxdefineobjarray} macro to define
299 the array class - otherwise you would get link errors.
300
301 \membersection{WX\_DEFINE\_OBJARRAY}\label{wxdefineobjarray}
302
303 \func{}{WX\_DEFINE\_OBJARRAY}{\param{}{name}}
304
305 This macro defines the methods of the array class {\it name} not defined by the
306 \helpref{WX\_DECLARE\_OBJARRAY()}{wxdeclareobjarray} macro. You must include the
307 file <wx/arrimpl.cpp> before using this macro and you must have the full
308 declaration of the class of array elements in scope! If you forget to do the
309 first, the error will be caught by the compiler, but, unfortunately, many
310 compilers will not give any warnings if you forget to do the second - but the
311 objects of the class will not be copied correctly and their real destructor will
312 not be called.
313
314 Example of usage:
315
316 \begin{verbatim}
317 // first declare the class!
318 class MyClass
319 {
320 public:
321 MyClass(const MyClass&);
322
323 ...
324
325 virtual ~MyClass();
326 };
327
328 #include <wx/arrimpl.cpp>
329 WX_DEFINE_OBJARRAY(wxArrayOfMyClass);
330 \end{verbatim}
331
332 \membersection{WX\_APPEND\_ARRAY}\label{wxappendarray}
333
334 \func{void}{WX\_APPEND\_ARRAY}{\param{wxArray\& }{array}, \param{wxArray\& }{other}}
335
336 This macro may be used to append all elements of the {\it other} array to the
337 {\it array}. The two arrays must be of the same type.
338
339 \membersection{WX\_CLEAR\_ARRAY}\label{wxcleararray}
340
341 \func{void}{WX\_CLEAR\_ARRAY}{\param{wxArray\& }{array}}
342
343 This macro may be used to delete all elements of the array before emptying it.
344 It can not be used with wxObjArrays - but they will delete their elements anyhow
345 when you call Empty().
346
347 \membersection{Default constructors}\label{wxarrayctordef}
348
349 \func{}{wxArray}{\void}
350
351 \func{}{wxObjArray}{\void}
352
353 Default constructor initializes an empty array object.
354
355 \func{}{wxSortedArray}{\param{int (*)(T first, T second)}{compareFunction}}
356
357 There is no default constructor for wxSortedArray classes - you must initialize it
358 with a function to use for item comparison. It is a function which is passed
359 two arguments of type {\it T} where {\it T} is the array element type and which
360 should return a negative, zero or positive value according to whether the first
361 element passed to it is less than, equal to or greater than the second one.
362
363 \membersection{wxArray copy constructor and assignment operator}\label{wxarrayctorcopy}
364
365 \func{}{wxArray}{\param{const wxArray\& }{array}}
366
367 \func{}{wxSortedArray}{\param{const wxSortedArray\& }{array}}
368
369 \func{}{wxObjArray}{\param{const wxObjArray\& }{array}}
370
371 \func{wxArray\&}{operator$=$}{\param{const wxArray\& }{array}}
372
373 \func{wxSortedArray\&}{operator$=$}{\param{const wxSortedArray\& }{array}}
374
375 \func{wxObjArray\&}{operator$=$}{\param{const wxObjArray\& }{array}}
376
377 The copy constructors and assignment operators perform a shallow array copy
378 (i.e. they don't copy the objects pointed to even if the source array contains
379 the items of pointer type) for wxArray and wxSortedArray and a deep copy (i.e.
380 the array element are copied too) for wxObjArray.
381
382 \membersection{wxArray::\destruct{wxArray}}\label{wxarraydtor}
383
384 \func{}{\destruct{wxArray}}{\void}
385
386 \func{}{\destruct{wxSortedArray}}{\void}
387
388 \func{}{\destruct{wxObjArray}}{\void}
389
390 The wxObjArray destructor deletes all the items owned by the array. This is not
391 done by wxArray and wxSortedArray versions - you may use
392 \helpref{WX\_CLEAR\_ARRAY}{wxcleararray} macro for this.
393
394 \membersection{wxArray::Add}\label{wxarrayadd}
395
396 \func{void}{Add}{\param{T }{item}}
397
398 \func{void}{Add}{\param{T *}{item}}
399
400 \func{void}{Add}{\param{T \&}{item}}
401
402 Appends a new element to the array (where {\it T} is the type of the array
403 elements.)
404
405 The first version is used with wxArray and wxSortedArray. The second and the
406 third are used with wxObjArray. There is an important difference between
407 them: if you give a pointer to the array, it will take ownership of it, i.e.
408 will delete it when the item is deleted from the array. If you give a reference
409 to the array, however, the array will make a copy of the item and will not take
410 ownership of the original item. Once again, it only makes sense for wxObjArrays
411 because the other array types never take ownership of their elements.
412
413 You may also use \helpref{WX\_APPEND\_ARRAY}{wxappendarray} macro to append all
414 elements of one array to another one.
415
416 \membersection{wxArray::Alloc}\label{wxarrayalloc}
417
418 \func{void}{Alloc}{\param{size\_t }{count}}
419
420 Preallocates memory for a given number of array elements. It is worth calling
421 when the number of items which are going to be added to the array is known in
422 advance because it will save unneeded memory reallocation. If the array already
423 has enough memory for the given number of items, nothing happens.
424
425 \membersection{wxArray::Clear}\label{wxarrayclear}
426
427 \func{void}{Clear}{\void}
428
429 This function does the same as \helpref{Empty()}{wxarrayempty} and additionally
430 frees the memory allocated to the array.
431
432 \membersection{wxArray::Count}\label{wxarraycount}
433
434 \constfunc{size\_t}{Count}{\void}
435
436 Same as \helpref{GetCount()}{wxarraygetcount}. This function is deprecated -
437 it exists only for compatibility.
438
439 \membersection{wxObjArray::Detach}\label{wxobjarraydetach}
440
441 \func{T *}{Detach}{\param{size\_t }{index}}
442
443 Removes the element from the array, but, unlike,
444 \helpref{Remove()}{wxarrayremove} doesn't delete it. The function returns the
445 pointer to the removed element.
446
447 \membersection{wxArray::Empty}\label{wxarrayempty}
448
449 \func{void}{Empty}{\void}
450
451 Empties the array. For wxObjArray classes, this destroys all of the array
452 elements. For wxArray and wxSortedArray this does nothing except marking the
453 array of being empty - this function does not free the allocated memory, use
454 \helpref{Clear()}{wxarrayclear} for this.
455
456 \membersection{wxArray::GetCount}\label{wxarraygetcount}
457
458 \constfunc{size\_t}{GetCount}{\void}
459
460 Return the number of items in the array.
461
462 \membersection{wxArray::Index}\label{wxarrayindex}
463
464 \func{int}{Index}{\param{T\& }{item}, \param{bool }{searchFromEnd = FALSE}}
465
466 \func{int}{Index}{\param{T\& }{item}}
467
468 The first version of the function is for wxArray and wxObjArray, the second is
469 for wxSortedArray only.
470
471 Searches the element in the array, starting from either beginning or the end
472 depending on the value of {\it searchFromEnd} parameter. wxNOT\_FOUND is
473 returned if the element is not found, otherwise the index of the element is
474 returned.
475
476 Linear search is used for the wxArray and wxObjArray classes but binary search
477 in the sorted array is used for wxSortedArray (this is why searchFromEnd
478 parameter doesn't make sense for it).
479
480 {\bf NB:} even for wxObjArray classes, the operator==() of the elements in the
481 array is {\bf not} used by this function. It searches exactly the given
482 element in the array and so will only succeed if this element had been
483 previously added to the array, but fail even if another, identical, element is
484 in the array.
485
486 \membersection{wxArray::Insert}\label{wxarrayinsert}
487
488 \func{void}{Insert}{\param{T }{item}, \param{size\_t }{n}}
489
490 \func{void}{Insert}{\param{T *}{item}, \param{size\_t }{n}}
491
492 \func{void}{Insert}{\param{T \&}{item}, \param{size\_t }{n}}
493
494 Insert a new item into the array before the item {\it n} - thus, {\it Insert(something, 0u)} will
495 insert an item in such way that it will become the
496 first array element.
497
498 Please see \helpref{Add()}{wxarrayadd} for explanation of the differences
499 between the overloaded versions of this function.
500
501 \membersection{wxArray::IsEmpty}\label{wxarrayisempty}
502
503 \constfunc{bool}{IsEmpty}{\void}
504
505 Returns TRUE if the array is empty, FALSE otherwise.
506
507 \membersection{wxArray::Item}\label{wxarrayitem}
508
509 \constfunc{T\&}{Item}{\param{size\_t }{index}}
510
511 Returns the item at the given position in the array. If {\it index} is out of
512 bounds, an assert failure is raised in the debug builds but nothing special is
513 done in the release build.
514
515 The returned value is of type "reference to the array element type" for all of
516 the array classes.
517
518 \membersection{wxArray::Last}\label{wxarraylast}
519
520 \constfunc{T\&}{Last}{\void}
521
522 Returns the last element in the array, i.e. is the same as Item(GetCount() - 1).
523 An assert failure is raised in the debug mode if the array is empty.
524
525 The returned value is of type "reference to the array element type" for all of
526 the array classes.
527
528 \membersection{wxArray::Remove}\label{wxarrayremove}
529
530 \func{\void}{Remove}{\param{T }{item}}
531
532 Removes an element from the array by value: the first item of the
533 array equal to {\it item} is removed, an assert failure will result from an
534 attempt to remove an item which doesn't exist in the array.
535
536 When an element is removed from wxObjArray it is deleted by the array - use
537 \helpref{Detach()}{wxobjarraydetach} if you don't want this to happen. On the
538 other hand, when an object is removed from a wxArray nothing happens - you
539 should delete it manually if required:
540
541 \begin{verbatim}
542 T *item = array[n];
543 delete item;
544 array.Remove(n)
545 \end{verbatim}
546
547 See also \helpref{WX\_CLEAR\_ARRAY}{wxcleararray} macro which deletes all
548 elements of a wxArray (supposed to contain pointers).
549
550 \membersection{wxArray::RemoveAt}\label{wxarrayremoveat}
551
552 \func{\void}{RemoveAt}{\param{size\_t }{index}}
553
554 Removes an element from the array by index. When an element
555 is removed from wxObjArray it is deleted by the array - use
556 \helpref{Detach()}{wxobjarraydetach} if you don't want this to happen. On the
557 other hand, when an object is removed from a wxArray nothing happens - you
558 should delete it manually if required:
559
560 \begin{verbatim}
561 T *item = array[n];
562 delete item;
563 array.RemoveAt(n)
564 \end{verbatim}
565
566 See also \helpref{WX\_CLEAR\_ARRAY}{wxcleararray} macro which deletes all
567 elements of a wxArray (supposed to contain pointers).
568
569 \membersection{wxArray::Shrink}\label{wxarrayshrink}
570
571 \func{void}{Shrink}{\void}
572
573 Frees all memory unused by the array. If the program knows that no new items
574 will be added to the array it may call Shrink() to reduce its memory usage.
575 However, if a new item is added to the array, some extra memory will be
576 allocated again.
577
578 \membersection{wxArray::Sort}\label{wxarraysort}
579
580 \func{void}{Sort}{\param{CMPFUNC<T> }{compareFunction}}
581
582 The notation CMPFUNC<T> should be read as if we had the following declaration:
583
584 \begin{verbatim}
585 template int CMPFUNC(T *first, T *second);
586 \end{verbatim}
587
588 where {\it T} is the type of the array elements. I.e. it is a function returning
589 {\it int} which is passed two arguments of type {\it T *}.
590
591 Sorts the array using the specified compare function: this function should
592 return a negative, zero or positive value according to whether the first element
593 passed to it is less than, equal to or greater than the second one.
594
595 wxSortedArray doesn't have this function because it is always sorted.
596