i2p/haiku-beta6
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Patch by David Weizades (thanks!):

Browse Source 
"Fixed the indentation and went over the cross references. Everything appears
to be in order and should be ready for committal. It adheres to the coding
guidelines and should be good to go."

git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@21206 a95241bf-73f2-0310-859d-f6bbb57e9c96
This commit is contained in:
Niels Sascha Reedijk
2007-05-22 13:58:43 +00:00
parent 96bde26d12
commit 02d0a2eab1
1 changed files with 62 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/user/support/List.dox
+62 -54
View File
@@ -2,8 +2,12 @@
* Copyright 2007, Haiku, Inc. All Rights Reserved. * Copyright 2007, Haiku, Inc. All Rights Reserved.
* Distributed under the terms of the MIT License. * Distributed under the terms of the MIT License.
* *
* Documentation by: * Authors:
* Niels Sascha Reedijk <[email protected]> * Niels Sascha Reedijk <[email protected]>
*
* Proofreading:
* David Weizades <[email protected]>
*
* Corresponds to: * Corresponds to:
* /trunk/headers/os/support/List.h rev 19972 * /trunk/headers/os/support/List.h rev 19972
* /trunk/src/kits/support/List.cpp rev 18649 * /trunk/src/kits/support/List.cpp rev 18649
@@ -22,27 +26,27 @@
objects. objects.
This class is designed to be used for a variety of tasks. Unlike similar This class is designed to be used for a variety of tasks. Unlike similar
implementations in other libraries, this class is not based on templates, implementations in other libraries, this class is not based on templates
and as such is inherently not typed. So it will be the job of the coder to and as such is inherently not typed. So it will be the job of the programmer
make sure proper data will be entered, since the compiler cannot check this. to make sure proper data is entered since the compiler cannot check this
itself.
BList contains a list of items that will grow and shrink depending on BList contains a list of items that will grow and shrink depending on how
how much items are in it. So you will not have to do any of the many items are in it. So you will not have to do any of the memory management
memory management. Furthermore, it's ordered. Those properties make it nor any ordering. These properties makes it useful in a whole range of
useful in a whole range of situations, for example in the interface kit in situations such as the interface kit within the BListView class.
the BListView class.
A note on ownership of the objects might come in handy. BList at no time A note on the ownership of the objects might come in handy. BList never
assumes ownership of the objects, so removing items from the list will assumes ownership of the objects, removing items from the list will
only remove those items from the list, it will not delete the item. In the only remove the entries from the list not delete the items themselves. In the
same spirit you should also make sure that before you might delete an same way you should also make sure that before you might delete an object
object that's in a list, you will remove it from the list first. that's in a list, you will have to remove it from the list first.
\warning This class is not thread-safe. \warning This class is not thread-safe.
The class implements methods to add and remove items, reorder items, The class implements methods to add, remove, reorder, retrieve, query
retrieve items, querying for items and some advanced methods which let items as well as some advanced methods which let you perform a task on all the
you perform a certain tasks to all the items of the list. items in the list.
*/ */
/*! /*!
@@ -50,21 +54,21 @@
\brief Create a new list with a number of empty slots. \brief Create a new list with a number of empty slots.
The memory management of this class allocates new memory per block. The The memory management of this class allocates new memory per block. The
\c count parameter can be tweaked to determine the size of those blocks. \c count parameter can be tweaked to determine the size of these blocks.
In general, if you know your list is only going to contain a fixed maximum In general, if you know your list is only going to contain a certain number of
number of items, pass that value. If you expect your list to have very few items at most, you can pass that value. If you expect your list to have very
items, it's probably safe to choose a low number. This is as to prevent the few items, it's safe to choose a low number. This is to prevent the list from
list from taking up unneccesary memory. If you expect the list to contain a taking up unneeded memory. If you expect the list to contain a large number
large number of items, choose a higher value, since every time the memory is of items, choose a higher value. Every time the memory is full, all the items
full, all the items have to be copied into a new piece of allocated memory have to be copied into a new piece of allocated memory which, in turn, is an
which is an expensive operation. expensive operation.
If you are unsure, you don't have to break your head over this. As long as If you are unsure, you don't have to overthink this. Just make sure you don't
you don't use a lot of lists or as long as the list isn't used in one of the use a lot of lists and as long as the list isn't used in one of the
performance critical parts of the code, you are safe to go with the default performance critical parts of the code, you are safe to go with the default
value. values.
\param count The size of the blocks of memory allocated. \param count The size of the blocks allocated in memory.
*/ */
/*! /*!
@@ -98,7 +102,7 @@
\param item The item to add. \param item The item to add.
\param index The place in the list. \param index The place in the list.
\retval true The item was added. \retval true The item was added.
\retval false Item was not added. Either the index was negative or invalid, \retval false Item was not added. Either the index is negative or invalid,
or resizing the list failed. or resizing the list failed.
\see AddItem(void *item) \see AddItem(void *item)
*/ */
@@ -133,12 +137,12 @@
\fn bool BList::AddList(const BList *list) \fn bool BList::AddList(const BList *list)
\brief Append a list to this list. \brief Append a list to this list.
Note that the \a list parameter is \c const, so the original list will not Note that the \a list parameter is a \c const, so the original list will not
be altered. be altered.
\param list The list to be appended. \param list The list to be appended.
\retval true The list was appended. \retval true The list was appended.
\retval false Failed to append the list, due to the fact that resizing our \retval false Failed to append the list, due to the resizing of our
list failed. list failed.
\see AddList(const BList *list, int32 index) \see AddList(const BList *list, int32 index)
*/ */
@@ -208,7 +212,7 @@
The function should take two \c const pointers as arguments and should return The function should take two \c const pointers as arguments and should return
an integer. an integer.
For an example, see the Compare(const BString *, const BString *) function. For an example, see the Compare(const BString *, const BString *) function.
*/ */
/*! /*!
@@ -225,13 +229,13 @@
\fn bool BList::MoveItem(int32 fromIndex, int32 toIndex) \fn bool BList::MoveItem(int32 fromIndex, int32 toIndex)
\brief Move an item to a new place \brief Move an item to a new place
This moves a list item from posititon a to position b, moving the appropriate This moves a list item from position A to position B, moving the appropriate
block of list elements to make up for the move. For example, in the array: block of list elements to make up for the move. For example, in the array:
\verbatim \verbatim
A B C D E F G H I J A B C D E F G H I J
\endverbatim \endverbatim
Moveing 1(B)->6(G) would result in this: Moving 1(B)->6(G) would result in this:
\verbatim \verbatim
A C D E F G B H I J A C D E F G B H I J
\endverbatim \endverbatim
@@ -239,7 +243,7 @@ A C D E F G B H I J
\param fromIndex The original location. \param fromIndex The original location.
\param toIndex The new location. \param toIndex The new location.
\retval true Move succeeded. \retval true Move succeeded.
\retval false Move failed since the indexes were invalid. \retval false Move failed due to the indexes being invalid.
*/ */
//! @} //! @}
@@ -264,7 +268,8 @@ A C D E F G B H I J
\fn void *BList::FirstItem() const \fn void *BList::FirstItem() const
\brief Get the first item. \brief Get the first item.
\return A pointer to the first item, or \c NULL if the list is empty. \return A pointer to the first item or \c NULL if the list is empty.
\see LastItem() const
*/ */
/*! /*!
@@ -281,7 +286,8 @@ A C D E F G B H I J
/*! /*!
\fn void *BList::LastItem() const \fn void *BList::LastItem() const
\brief Get the last item. \brief Get the last item.
\return A pointer to the last item, or \c NULL if the list is empty. \return A pointer to the last item or \c NULL if the list is empty.
\see FirstItem() const
*/ */
/*! /*!
@@ -289,16 +295,16 @@ A C D E F G B H I J
\brief Return the internal list of objects. \brief Return the internal list of objects.
This method will return a pointer to the internal pointer list. This means This method will return a pointer to the internal pointer list. This means
you should be careful what you are doing, since you are directly working that you should be careful what you are doing, since you are working with the
with the internals of the class. internals of the class directly.
It is definately not a good idea to make any changes to the list, since it It is not a good idea to make any changes to the list, since that will mess
will mess up the internal consistency. up the internal consistency.
\warning If there is anything you want for which you need the list of \warning If there is anything you want, for which you need the list of
objects, please realize that that probably means that what you want to do objects, please understand that that probably means that what you want to do
is a bad idea to begin with. Avoid this method. The list of objects doesn't is a bad idea to begin with and you should avoid this method. The list of
belong to you. Check if DoForEach() can help you. objects doesn't belong to you. See if DoForEach() can help you out instead.
\return The internal list of pointers. \return The internal list of pointers.
*/ */
@@ -344,23 +350,25 @@ A C D E F G B H I J
\fn void BList::DoForEach(bool (*func)(void* item)) \fn void BList::DoForEach(bool (*func)(void* item))
\brief Perform an action on every item in the list. \brief Perform an action on every item in the list.
If one of the actions on the items fails, meaning that the \a func function If one of the actions on the items fails it means that the \a func function
returned \c false, then the processing of the list will be stopped. returned \c false and the processing of the list will be stopped.
\param func A function that takes a \c void * argument and returns a boolean. \param func A function that takes a \c void * argument and returns a boolean.
\see DoForEach(bool (*func)(void* item, void* arg2), void *arg2)
*/ */
/*! /*!
\fn void BList::DoForEach(bool (*func)(void* item, void* arg2), void *arg2) \fn void BList::DoForEach(bool (*func)(void* item, void* arg2), void *arg2)
\brief Perform an action on every item in the list with an argument. \brief Perform an action on every item in the list with an argument.
If one of the actions on the items fails, meaning that the \a func function If one of the actions on the items fails it means that the \a func function
returned \c false, then the processing of the list will be stopped. returned \c false and the processing of the list will be stopped.
\param func A function with the first \c void * argument being the item, \param func A function with the first \c void * argument being the item
and the second \c void * being the argument that you supply. It should and the second \c void * being the argument that you supply. It should
return a boolean value on whether it succeeded or not. return a boolean value on whether it succeeded or not.
\param arg2 An argument to supply to \a func. \param arg2 An argument to supply to \a func.
\see DoForEach(bool (*func)(void* item))
*/ */
//! @} //! @}