1/* 2 * Copyright 2014 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * John Scipione, jscipione@gmail.com 7 * 8 * Corresponds to: 9 * headers/os/support/ObjectList.h hrev40252 10 */ 11 12 13/*! 14 \file ObjectList.h 15 \ingroup support 16 \ingroup libbe 17 \brief Defines the BObjectList class. 18*/ 19 20 21/*! 22 \class BObjectList 23 \ingroup support 24 \ingroup libbe 25 \brief BObjectList is a wrapper around BList that adds type safety, 26 optional object ownership, search, and insert operations. 27 28 \since Haiku R1 29*/ 30 31 32/*! 33 \fn template<class T> BObjectList<T>::BObjectList(int32 itemsPerBlock, 34 bool owning) 35 \brief Creates a new BObjectList. 36 37 \param itemsPerBlock The number of items per block to allocate. 38 \param owning Whether or not the BObjectList deletes its items when 39 it is emptied or deleted. 40 41 \since Haiku R1 42*/ 43 44 45/*! 46 \fn template<class T> BObjectList<T>::BObjectList( 47 const BObjectList<T>& list) 48 \brief Creates a new BObjectList as a copy of another \a list. 49 50 \param list The \a list to copy from. 51 52 \since Haiku R1 53*/ 54 55 56/*! 57 \fn template<class T> BObjectList<T>::~BObjectList() 58 \brief Deletes the list. 59 60 If the list owns its items they are deleted too. 61 62 \since Haiku R1 63*/ 64 65 66/*! 67 \name Operators 68*/ 69 70 71//! @{ 72 73 74/*! 75 \fn template<class T> BObjectList<T>& BObjectList<T>::operator=( 76 const BObjectList<T>& list) 77 \brief Creates a new BObjectList as a copy of another \a list by 78 overloading the = operator. 79 80 \param list The \a list to copy from. 81 82 \since Haiku R1 83*/ 84 85 86//! @} 87 88 89/*! 90 \name Adding and Removing Items 91*/ 92 93 94//! @{ 95 96 97/*! 98 \fn template<class T> bool BObjectList<T>::AddItem(T* item) 99 \brief Append the \a item to the end of the list. 100 101 \param item The \a item to append. 102 103 \return Whether or not the \a item was appended. 104 \retval true The \a item was appended. 105 \retval false \a item was not appended, since resizing the BObjectList 106 failed. 107 108 \since Haiku R1 109*/ 110 111 112/*! 113 \fn template<class T> bool BObjectList<T>::AddItem(T* item, int32 index) 114 \brief Add \a item at the specified \a index. 115 116 \param item The \a item to add. 117 \param index The place in the list to add the \a item. 118 119 \return Whether or not the item was added. 120 \retval true The item was added. 121 \retval false Item was not added. Either the index is negative or invalid, 122 or resizing the BObjectList failed. 123 124 \since Haiku R1 125*/ 126 127 128/*! 129 \fn template<class T> bool BObjectList<T>::AddList(BObjectList<T>* list) 130 \brief Append a \a list of items to this list. 131 132 The original list is not altered. 133 134 \param list The \a list to be added. 135 136 \return Whether or not the \a list was added. 137 \retval true The \a list was added. 138 \retval false Failed to append the list, resizing failed. 139 140 \since Haiku R1 141*/ 142 143 144/*! 145 \fn template<class T> bool BObjectList<T>::AddList(BObjectList<T>* list, 146 int32 index) 147 \brief Add a \a list of items to this list at the specified \a index. 148 149 The original list is not altered. 150 151 \param list The \a list to be added. 152 \param index The position in the current \a list where the new item(s) are 153 added. 154 155 \return Whether or not the \a list was added. 156 \retval true The \a list was added. 157 \retval false Failed to insert the \a list resizing failed. 158 159 \since Haiku R1 160*/ 161 162 163/*! 164 \fn template<class T> bool BObjectList<T>::RemoveItem(T* item, 165 bool deleteIfOwning) 166 \brief Remove \a item from the list. 167 168 \param item The \a item to be removed. 169 \param deleteIfOwning Also delete the \a item if owned. 170 171 \return Whether or not the \a item was removed. 172 \retval true The \a item was found and removed. 173 \retval false The \a item was not in this list and thus not removed. 174 175 \since Haiku R1 176*/ 177 178 179/*! 180 \fn template<class T> T* BObjectList<T>::RemoveItemAt(int32 index) 181 \brief Remove the item at \a index from the list. 182 183 \param index The \a index of the item to be removed. 184 185 \return The pointer to the item that was removed, or \c NULL if the 186 \a index was invalid. 187 188 \since Haiku R1 189*/ 190 191 192/*! 193 \fn template<class T> inline T* BObjectList<T>::ItemAt(int32 index) const 194 \brief Return a pointer to the item at the given \a index. 195 196 \param index The item to retrieve. 197 198 \return A pointer to the item in that position, or \c NULL if the 199 \a index is out of bounds. 200 201 \since Haiku R1 202*/ 203 204 205/*! 206 \fn template<class T> bool BObjectList<T>::ReplaceItem(int32 index, T* item) 207 \brief Replace an item with another one. 208 209 \param index The offset in the list where to put the \a item. 210 \param item The new \a item to put in the list. 211 212 \return Whether or not the item was replaced. 213 \retval true The item was replaced. 214 \retval false The \a index was invalid. 215 216 \since Haiku R1 217*/ 218 219 220/*! 221 \fn template<class T> void BObjectList<T>::MakeEmpty(bool deleteIfOwning) 222 \brief Clear all the items from the list. 223 224 \param deleteIfOwning Also deletes items if owned. 225 226 \since Haiku R1 227*/ 228 229 230//! @} 231 232 233/*! 234 \name Reordering Items 235*/ 236 237 238//! @{ 239 240 241/*! 242 \fn template<class T> T* BObjectList<T>::SwapWithItem(int32 index, T* item) 243 \brief Swap the \a item with the item at \a index. 244 245 \param index The offset in the list where to put the \a item. 246 \param item The new \a item to put in the list. 247 248 \return A pointer to the item in that position, or \c NULL if the 249 \a index is out of bounds. 250 251 \since Haiku R1 252*/ 253 254 255/*! 256 \fn template<class T> bool BObjectList<T>::MoveItem(int32 from, int32 to) 257 \brief Move the item at \a from to the position of \a to. 258 259 \param from The index to move the item \a from. 260 \param to The index to move the item \a to. 261 262 \return Whether or not the items were moved. 263 \retval true The items were moved. 264 \retval false The \a from or \a to index was invalid. 265 266 \see BList::MoveItem() 267 268 \since Haiku R1 269*/ 270 271 272//! @} 273 274 275/*! 276 \name Querying Items 277*/ 278 279 280//! @{ 281 282 283/*! 284 \fn template<class T> int32 BObjectList<T>::IndexOf(const T* item) const 285 \brief Return the index of \a item. 286 287 \return The index of the item, or -1 when the item is not in the list. 288 289 \since Haiku R1 290*/ 291 292 293/*! 294 \fn template<class T> T* BObjectList<T>::FirstItem() const 295 \brief Return a pointer to the first item in the list. 296 297 \return A pointer to the first item or \c NULL if the list is empty. 298 299 \see BObjectList<T>::LastItem() const 300 301 \since Haiku R1 302*/ 303 304 305/*! 306 \fn template<class T> T* BObjectList<T>::LastItem() const 307 \brief Return a pointer to the last item in the list. 308 309 \return A pointer to the last item or \c NULL if the list is empty. 310 311 \see BObjectList<T>::FirstItem() const 312 313 \since Haiku R1 314*/ 315 316 317/*! 318 \fn template<class T> bool BObjectList<T>::HasItem(const T* item) const 319 \brief Return whether or not \a item is in the list. 320 321 \return \c true if the \a item was in the list, \c false otherwise. 322 323 \since Haiku R1 324*/ 325 326 327/*! 328 \fn template<class T> bool BObjectList<T>::IsEmpty() const 329 \brief Return whether or not there are items in the list. 330 331 \return \c true if the list was empty, \c false otherwise. 332 333 \since Haiku R1 334*/ 335 336 337/*! 338 \fn template<class T> int32 BObjectList<T>::CountItems() const 339 \brief Returns the number of items in the list. 340 341 \return The number of items in the list as an int32. 342 343 \since Haiku R1 344*/ 345 346 347//! @} 348 349 350/*! 351 \name Iterating Over Items 352*/ 353 354 355//! @{ 356 357 358/*! 359 \fn template<class T> T* BObjectList<T>::EachElement(EachFunction func, 360 void* params) 361 \brief Perform an action on each item in the list. 362 363 \param func A function that takes a \c void* argument and returns a 364 boolean. 365 \param params parameters for \a func. 366 367 \return A pointer to the item. 368 369 \since Haiku R1 370*/ 371 372 373/*! 374 \fn template<class T> const T* BObjectList<T>::EachElement( 375 ConstEachFunction func, void* params) const 376 \brief Perform an action on each item in the list. 377 378 \param func A function that takes a \c void* argument and returns a 379 boolean. 380 \param params parameters for \a func. 381 382 \return A pointer to the item. 383 384 \since Haiku R1 385*/ 386 387 388//! @} 389 390 391/*! 392 \name Finding Items 393*/ 394 395 396//! @{ 397 398 399/*! 400 \fn template<class T> const T* BObjectList<T>::FindIf( 401 const UnaryPredicate<T>& predicate) const 402 \brief Find items that match \a predicate. 403 404 \return A const pointer to T. 405 406 \since Haiku R1 407*/ 408 409 410/*! 411 \fn template<class T> T* BObjectList<T>::FindIf( 412 const UnaryPredicate<T>& predicate) 413 \brief Find items that match \a predicate. 414 415 \return A pointer to T. 416 417 \since Haiku R1 418*/ 419 420 421/*! 422 \fn template<class T> T* BObjectList<T>::BinarySearch(const T& key, 423 CompareFunction func) const 424 \brief Search for \a key in the list of items using the supplied comparison 425 function via a binary search algorithm. 426 427 \param key The \a key to search for. 428 \param func The comparison function to use. 429 430 \return A pointer to T. 431 432 \since Haiku R1 433*/ 434 435 436/*! 437 \fn template<class T> T* BObjectList<T>::BinarySearch(const T& key, 438 CompareFunctionWithState func, void* state) const 439 \brief Search for \a key in the list of items using the supplied comparison 440 function via a binary search algorithm. 441 442 \param key The \a key to search for. 443 \param func The comparison function to use. 444 \param state Additional information used to search for the item. 445 446 \return A pointer to T. 447 448 \since Haiku R1 449*/ 450 451 452//! @} 453 454 455/*! 456 \name Reordering Items 457*/ 458 459 460//! @{ 461 462 463/*! 464 \fn template<class T> void BObjectList<T>::SortItems( 465 CompareFunction function) 466 \brief Sort the items with the use of a supplied comparison \a function. 467 468 \param function The \a function used to sort the items. 469 470 \since Haiku R1 471*/ 472 473 474/*! 475 \fn template<class T> void BObjectList<T>::SortItems( 476 CompareFunctionWithState function, void* state) 477 \brief Sort the items with the use of a supplied comparison \a function and 478 addtional \a state. 479 480 \param function The \a function used to sort the items. 481 \param state Additional information used to sort the items. 482 483 \since Haiku R1 484*/ 485 486 487/*! 488 \fn template<class T> void BObjectList<T>::HSortItems( 489 CompareFunction function) 490 \brief Sort the items with the use of a supplied comparison \a function. 491 492 \param function The \a function used to sort the items. 493 494 \since Haiku R1 495*/ 496 497 498/* 499 \fn template<class T> void BObjectList<T>::HSortItems( 500 CompareFunctionWithState function, void* state) 501 502 \param function The \a function used to sort the items. 503 \param state Additional information used to sort the items. 504 505 \since Haiku R1 506*/ 507 508 509//! @} 510