1 ///////////////////////////////////////////////////////////////////////////// 2 // Name: list.h 3 // Purpose: interface of wxList<T> 4 // Author: wxWidgets team 5 // Licence: wxWindows licence 6 ///////////////////////////////////////////////////////////////////////////// 7 8 /** 9 The wxList<T> class provides linked list functionality. 10 11 This class has been rewritten to be type safe and to provide the full API of 12 the STL std::list container and should be used like it. 13 The exception is that wxList<T> actually stores pointers and therefore its 14 iterators return pointers and not references to the actual objects in the list 15 (see example below) and @e value_type is defined as @e T*. 16 wxList<T> destroys an object after removing it only if wxList<T>::DeleteContents 17 has been called. 18 19 wxList<T> is not a real template and it requires that you declare and define 20 each wxList<T> class in your program. This is done with @e WX_DECLARE_LIST 21 and @e WX_DEFINE_LIST macros (see example). We hope that we'll be able to 22 provide a proper template class providing both the STL @c std::list and the old 23 wxList API in the future. 24 25 Please refer to the STL @c std::list documentation (see http://www.cppreference.com/wiki/stl/list/start) 26 for further information on how to use the class. 27 Below we documented both the supported STL and the legacy API 28 that originated from the old wxList class and which can still be used alternatively 29 for the same class. 30 31 Note that if you compile wxWidgets in STL mode (@c wxUSE_STL defined as 1) 32 then wxList<T> will actually derive from @c std::list and just add a legacy 33 compatibility layer for the old wxList class. 34 35 @code 36 // this part might be in a header or source (.cpp) file 37 class MyListElement 38 { 39 ... // whatever 40 }; 41 42 // this macro declares and partly implements MyList class 43 WX_DECLARE_LIST(MyListElement, MyList); 44 45 ... 46 47 // the only requirement for the rest is to be AFTER the full declaration of 48 // MyListElement (for WX_DECLARE_LIST forward declaration is enough), but 49 // usually it will be found in the source file and not in the header 50 51 #include <wx/listimpl.cpp> 52 WX_DEFINE_LIST(MyList); 53 54 55 MyList list; 56 MyListElement element; 57 list.Append(&element); // ok 58 list.Append(17); // error: incorrect type 59 60 // let's iterate over the list in STL syntax 61 MyList::iterator iter; 62 for (iter = list.begin(); iter != list.end(); ++iter) 63 { 64 MyListElement *current = *iter; 65 66 ...process the current element... 67 } 68 69 // the same with the legacy API from the old wxList class 70 MyList::compatibility_iterator node = list.GetFirst(); 71 while (node) 72 { 73 MyListElement *current = node->GetData(); 74 75 ...process the current element... 76 77 node = node->GetNext(); 78 } 79 @endcode 80 81 For compatibility with previous versions wxList and wxStringList classes are 82 still defined, but their usage is deprecated and they will disappear in the 83 future versions completely. 84 The use of the latter is especially discouraged as it is not only unsafe but 85 is also much less efficient than wxArrayString class. 86 87 @tparam T 88 The type stored in the wxList nodes. 89 90 @library{wxbase} 91 @category{containers} 92 93 @see wxArray<T>, wxVector<T>, wxNode<T> 94 */ 95 template<typename T> 96 class wxList<T> 97 { 98 public: 99 /** 100 Default constructor. 101 */ 102 wxList(); 103 104 /** 105 Constructor which initialized the list with an array of @a count elements. 106 */ 107 wxList(size_t count, T* elements[]); 108 109 /** 110 Destroys the list, but does not delete the objects stored in the list 111 unless you called DeleteContents(@true ). 112 */ 113 ~wxList(); 114 115 /** 116 Appends the pointer to @a object to the list. 117 */ 118 wxList<T>::compatibility_iterator Append(T* object); 119 120 /** 121 Clears the list. 122 Deletes the actual objects if DeleteContents( @true ) was called previously. 123 */ 124 void Clear(); 125 126 /** 127 If @a destroy is @true, instructs the list to call @e delete 128 on objects stored in the list whenever they are removed. 129 The default is @false. 130 */ 131 void DeleteContents(bool destroy); 132 133 /** 134 Deletes the given element referred to by @a iter from the list 135 if @a iter is a valid iterator. Returns @true if successful. 136 137 Deletes the actual object if DeleteContents( @true ) was called previously. 138 */ 139 bool DeleteNode(const compatibility_iterator& iter); 140 141 /** 142 Finds the given @a object and removes it from the list, returning 143 @true if successful. 144 145 Deletes @a object if DeleteContents( @true ) was called previously. 146 */ 147 bool DeleteObject(T* object); 148 149 /** 150 Removes element referred to be @a iter. 151 152 Deletes the actual object if DeleteContents( @true ) was called previously. 153 */ 154 void Erase(const compatibility_iterator& iter); 155 156 /** 157 Returns the iterator referring to @a object or @NULL if none found. 158 */ 159 wxList<T>::compatibility_iterator Find(T* object) const; 160 161 /** 162 Returns the number of elements in the list. 163 */ 164 size_t GetCount() const; 165 166 /** 167 Returns the first iterator in the list (@NULL if the list is empty). 168 */ 169 wxList<T>::compatibility_iterator GetFirst() const; 170 171 /** 172 Returns the last iterator in the list (@NULL if the list is empty). 173 */ 174 wxList<T>::compatibility_iterator GetLast() const; 175 176 /** 177 Returns the index of @a obj within the list or @c wxNOT_FOUND if 178 @a obj is not found in the list. 179 */ 180 int IndexOf(T* obj) const; 181 182 /** 183 Inserts @a object at the beginning of the list. 184 */ 185 wxList<T>::compatibility_iterator Insert(T* object); 186 187 /** 188 Inserts @a object at @a position. 189 */ 190 wxList<T>::compatibility_iterator Insert(size_t position, 191 T* object); 192 193 /** 194 Inserts @a object before the object referred to be @a iter. 195 */ 196 wxList<T>::compatibility_iterator Insert(compatibility_iterator iter, 197 T* object); 198 199 /** 200 Returns @true if the list is empty, @false otherwise. 201 */ 202 bool IsEmpty() const; 203 204 /** 205 Returns the iterator referring to the object at the given 206 @a index in the list. 207 */ 208 wxList<T>::compatibility_iterator Item(size_t index) const; 209 210 /** 211 Check if the object is present in the list. 212 213 @see Find() 214 */ 215 bool Member(T* object) const; 216 217 /** 218 @deprecated This function is deprecated, use Item() instead. 219 */ 220 wxList<T>::compatibility_iterator Nth(int n) const; 221 222 /** 223 @deprecated This function is deprecated, use wxList::GetCount instead. 224 Returns the number of elements in the list. 225 */ 226 int Number() const; 227 228 /** 229 Allows the sorting of arbitrary lists by giving a function to compare 230 two list elements. We use the system @b qsort function for the actual 231 sorting process. 232 */ 233 void Sort(wxSortCompareFunction compfunc); 234 235 /** 236 Clears the list and item from @a first to @a last from another list to it. 237 */ 238 void assign(const_iterator first, const const_iterator& last); 239 240 /** 241 Clears the list and adds @a n items with value @a v to it. 242 */ 243 void assign(size_type n, const_reference v = value_type()); 244 245 /** 246 Returns the last item of the list. 247 */ 248 reference back(); 249 250 /** 251 Returns the last item of the list as a const reference. 252 */ 253 const_reference back() const; 254 255 /** 256 Returns an iterator pointing to the beginning of the list. 257 */ 258 iterator begin(); 259 260 /** 261 Returns a const iterator pointing to the beginning of the list. 262 */ 263 const_iterator begin() const; 264 265 /** 266 Removes all items from the list. 267 */ 268 void clear(); 269 270 /** 271 Returns @e @true if the list is empty. 272 */ 273 bool empty() const; 274 275 /** 276 Returns a const iterator pointing at the end of the list. 277 */ 278 const_iterator end() const; 279 280 /** 281 Returns an iterator pointing at the end of the list. 282 */ 283 iterator end() const; 284 285 /** 286 Erases the given item 287 */ 288 iterator erase(const iterator& it); 289 290 /** 291 Erases the items from @e first to @e last. 292 */ 293 iterator erase(const iterator& first, 294 const iterator& last); 295 296 /** 297 Returns the first item in the list. 298 */ 299 reference front() const; 300 301 /** 302 Returns the first item in the list as a const reference. 303 */ 304 const_reference front() const; 305 306 /** 307 Inserts an item at the head of the list 308 */ 309 iterator insert(const iterator& it); 310 311 /** 312 Inserts an item at the given position 313 */ 314 void insert(const iterator& it, size_type n); 315 316 /** 317 Inserts several items at the given position. 318 */ 319 void insert(const iterator& it, const_iterator first, 320 const const_iterator& last); 321 322 /** 323 Returns the largest possible size of the list. 324 */ 325 size_type max_size() const; 326 327 /** 328 Removes the last item from the list. 329 */ 330 void pop_back(); 331 332 /** 333 Removes the first item from the list. 334 */ 335 void pop_front(); 336 337 /** 338 Adds an item to end of the list. 339 */ 340 void push_back(const_reference v = value_type()); 341 342 /** 343 Adds an item to the front of the list. 344 */ 345 void push_front(const_reference v = value_type()); 346 347 /** 348 Returns a reverse iterator pointing to the beginning of the 349 reversed list. 350 */ 351 reverse_iterator rbegin(); 352 353 /** 354 Returns a const reverse iterator pointing to the beginning of the 355 reversed list. 356 */ 357 const_reverse_iterator rbegin() const; 358 359 /** 360 Removes an item from the list. 361 */ 362 void remove(const_reference v); 363 364 /** 365 Returns a reverse iterator pointing to the end of the reversed list. 366 */ 367 reverse_iterator rend(); 368 369 /** 370 Returns a const reverse iterator pointing to the end of the reversed list. 371 */ 372 const_reverse_iterator rend() const; 373 374 /** 375 Resizes the list. 376 377 If the list is longer than @a n, then items are removed until the list 378 becomes long @a n. 379 If the list is shorter than @a n items with the value @a v are appended 380 to the list until the list becomes long @a n. 381 */ 382 void resize(size_type n, value_type v = value_type()); 383 384 /** 385 Reverses the list. 386 */ 387 void reverse(); 388 389 /** 390 Returns the size of the list. 391 */ 392 size_type size() const; 393 394 /** 395 Returns a wxVector holding the list elements. 396 397 @since 2.9.5 398 */ 399 wxVector<T> AsVector() const; 400 }; 401 402 403 404 /** 405 wxNode<T> is the node structure used in linked lists (see wxList) and derived 406 classes. You should never use wxNode<T> class directly, however, because it 407 works with untyped (@c void *) data and this is unsafe. 408 Use wxNode<T>-derived classes which are automatically defined by WX_DECLARE_LIST 409 and WX_DEFINE_LIST macros instead as described in wxList documentation 410 (see example there). 411 412 Also note that although there is a class called wxNode, it is defined for backwards 413 compatibility only and usage of this class is strongly deprecated. 414 415 In the documentation below, the type @c T should be thought of as a 416 "template" parameter: this is the type of data stored in the linked list or, 417 in other words, the first argument of WX_DECLARE_LIST macro. Also, wxNode is 418 written as wxNodeT even though it isn't really a template class -- but it 419 helps to think of it as if it were. 420 421 @tparam T 422 The type stored in the wxNode. 423 424 @library{wxbase} 425 @category{data} 426 427 @see wxList<T>, wxHashTable 428 */ 429 template<typename T> 430 class wxNode<T> 431 { 432 public: 433 /** 434 Retrieves the client data pointer associated with the node. 435 */ 436 T* GetData() const; 437 438 /** 439 Retrieves the next node or @NULL if this node is the last one. 440 */ 441 wxNode<T>* GetNext() const; 442 443 /** 444 Retrieves the previous node or @NULL if this node is the first one in the list. 445 */ 446 wxNode<T>* GetPrevious(); 447 448 /** 449 Returns the zero-based index of this node within the list. The return value 450 will be @c wxNOT_FOUND if the node has not been added to a list yet. 451 */ 452 int IndexOf(); 453 454 /** 455 Sets the data associated with the node (usually the pointer will have been 456 set when the node was created). 457 */ 458 void SetData(T* data); 459 }; 460 461