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