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