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