docs/user/support/ObjectList.dox

   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 //! @}