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