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

Update according to the latest guideline changes. These files already

Browse Source 
passed phase 3, so they wouldn't be updated during the regular process. 
I guess the other files will get that update.


git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@21833 a95241bf-73f2-0310-859d-f6bbb57e9c96
This commit is contained in:
Niels Sascha Reedijk
2007-08-06 09:32:27 +00:00
parent ff3d9bfa2a
commit 55f7db1bd9
3 changed files with 595 additions and 520 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/user/support/Archivable.dox
+130 -110
View File
@@ -3,174 +3,194 @@
* Distributed under the terms of the MIT License. * Distributed under the terms of the MIT License.
* *
* Author: * Author:
* Niels Sascha Reedijk <[email protected]> * Niels Sascha Reedijk, [email protected]
* *
* Proofreader: * Proofreader:
* David Weizades <[email protected]> * David Weizades, [email protected]
* Thom Holwerda <[email protected]> * Thom Holwerda, [email protected]
* *
* Corresponds to: * Corresponds to:
* /trunk/headers/os/support/Archivable.h rev 19972 * /trunk/headers/os/support/Archivable.h rev 19972
* /trunk/src/kits/support/Archivable.cpp rev 19095 * /trunk/src/kits/support/Archivable.cpp rev 19095
*/ */
/*!
\file Archivable.h
\brief Provides the BArchivable interface.
*/
/*! /*!
\class BArchivable \file Archivable.h
\ingroup support \brief Provides the BArchivable interface.
\ingroup libbe
\brief Interface for objects that can be archived into a BMessage.
BArchivable provides an interface for objects that can be put into message
archives and extracted into objects in another location. Using this you are
able to send objects between applications, or even between computers across
networks.
BArchivable differs from BFlattenable in that BFlattenable is designed to
store objects into flat streams of data, the main objective being storage to
disk. The objective of this interface, however, is to store objects that will
be restored to other objects. To illustrate this point, BArchivable messages
know how to restore themselves whereas BFlattenables have a datatype which
you need to map to classes manually.
Archiving is done with the Archive() method. If your class supports it, the
caller can request it to store into a deep archive, meaning that all child
objects in it will be stored. Extracting the archive works with the
Instantiate() method, which is static. Since the interface is designed to
extract objects without the caller knowing what kind of object it actually is,
the global function #instantiate_object() instantiates a message without you
manually having to determine the class the message is from. This adds
considerable flexibility and allows BArchivable to be used in combination with
other add-ons.
To provide this interface in your classes you should publicly inherit this
class. You should implement Archive() and Instantiate(), and provide one
constructor that takes one BMessage argument.
*/ */
/*! /*!
\fn BArchivable::BArchivable(BMessage* from) \class BArchivable
\brief Constructor. Does nothing. \ingroup support
\ingroup libbe
\brief Interface for objects that can be archived into a BMessage.
If you inherit this interface you should provide at least one constructor that BArchivable provides an interface for objects that can be put into message
takes one BMessage argument. archives and extracted into objects in another location. Using this you are
able to send objects between applications, or even between computers across
networks.
BArchivable differs from BFlattenable in that BFlattenable is designed to
store objects into flat streams of data, the main objective being storage to
disk. The objective of this interface, however, is to store objects that
will be restored to other objects. To illustrate this point, BArchivable
messages know how to restore themselves whereas BFlattenables have a
datatype which you need to map to classes manually.
Archiving is done with the Archive() method. If your class supports it, the
caller can request it to store into a deep archive, meaning that all child
objects in it will be stored. Extracting the archive works with the
Instantiate() method, which is static. Since the interface is designed to
extract objects without the caller knowing what kind of object it actually
is, the global function #instantiate_object() instantiates a message without
you manually having to determine the class the message is from. This adds
considerable flexibility and allows BArchivable to be used in combination
with other add-ons.
To provide this interface in your classes you should publicly inherit this
class. You should implement Archive() and Instantiate(), and provide one
constructor that takes one BMessage argument.
*/ */
/*! /*!
\fn BArchivable::BArchivable() \fn BArchivable::BArchivable(BMessage* from)
\brief Constructor. Does nothing. \brief Constructor. Does nothing.
If you inherit this interface you should provide at least one constructor
that takes one BMessage argument.
*/ */
/*! /*!
\fn BArchivable::~BArchivable() \fn BArchivable::BArchivable()
\brief Destructor. Does nothing. \brief Constructor. Does nothing.
*/ */
/*! /*!
\fn virtual status_t BArchivable::Archive(BMessage* into, bool deep = true) const \fn BArchivable::~BArchivable()
\brief Archive the object into a BMessage. \brief Destructor. Does nothing.
You should call this method from your derived implementation as it adds the
data needed to instantiate your object to the message.
\param into The message you store your object in.
\param deep If \c true, all children of this object should be stored as well.
Only pay attention to this parameter if you actually have child objects.
\retval B_OK The archiving succeeded.
\retval "error codes" The archiving did not succeed.
*/ */
/*! /*!
\fn static BArchivable* BArchivable::Instantiate(BMessage* archive) \fn virtual status_t BArchivable::Archive(BMessage* into,
\brief Static member to restore objects from messages. bool deep = true) const
\brief Archive the object into a BMessage.
You should always check that the \a archive argument actually corresponds to You should call this method from your derived implementation as it adds the
your class. The automatic functions, such as #instantiate_object() will not data needed to instantiate your object to the message.
choose the wrong class but manual calls to this member might be faulty.
\param archive The message with the data of the object to restore. \param into The message you store your object in.
\retval You should return a pointer to your object, or \c NULL if you \param deep If \c true, all children of this object should be stored as
fail. well. Only pay attention to this parameter if you actually have child
\warning The default implementation will always return \c NULL. Even though objects.
it is possible to store plain BArchive objects, it is impossible to restore \retval B_OK The archiving succeeded.
them. \retval "error codes" The archiving did not succeed.
\see instantiate_object(BMessage *from)
*/ */
/*! /*!
\fn virtual status_t BArchivable::Perform(perform_code d, void* arg) \fn static BArchivable* BArchivable::Instantiate(BMessage* archive)
\brief Internal method. \brief Static member to restore objects from messages.
\internal This method is defined in case of unforeseen binary compatibility
API issues. Currently nothing of interest is implemented. You should always check that the \a archive argument actually corresponds to
your class. The automatic functions, such as #instantiate_object() will not
choose the wrong class but manual calls to this member might be faulty.
\param archive The message with the data of the object to restore.
\retval You should return a pointer to your object, or \c NULL if you
fail.
\warning The default implementation will always return \c NULL. Even though
it is possible to store plain BArchive objects, it is impossible to
restore them.
\see instantiate_object(BMessage *from)
*/ */
/*!
\fn virtual status_t BArchivable::Perform(perform_code d, void* arg)
\brief Internal method.
\internal This method is defined in case of unforeseen binary compatibility
API issues. Currently nothing of interest is implemented.
*/
///// Global methods ///// ///// Global methods /////
/*! /*!
\addtogroup support_globals \addtogroup support_globals
@{ @{
*/ */
/*! /*!
\typedef typedef BArchivable* (*instantiation_func)(BMessage*) \typedef typedef BArchivable* (*instantiation_func)(BMessage*)
\brief Internal definition of a function that can instantiate objects that \brief Internal definition of a function that can instantiate objects that
have been created with the BArchivable API. have been created with the BArchivable API.
*/ */
/*! /*!
\fn BArchivable* instantiate_object(BMessage *from, image_id *id) \fn BArchivable* instantiate_object(BMessage *from, image_id *id)
\brief Instantiate an archived object with the object being defined in a \brief Instantiate an archived object with the object being defined in a
different application or library. different application or library.
This function is similar to instantiate_object(BMessage *from), except that This function is similar to instantiate_object(BMessage *from), except that
it takes the \a id argument referring to an image where the object might be it takes the \a id argument referring to an image where the object might be
stored. stored.
\note Images are names for executable files. Image id's refer to these \note Images are names for executable files. Image id's refer to these
executable files that have been loaded by your application. Have a look executable files that have been loaded by your application. Have a look
at the kernel API for further information. at the kernel API for further information.
*/ */
/*! /*!
\fn BArchivable* instantiate_object(BMessage *from) \fn BArchivable* instantiate_object(BMessage *from)
\brief Instantiate an archived object. \brief Instantiate an archived object.
This global function will determine the base class, based on the \a from This global function will determine the base class, based on the \a from
argument, and it will call the Instantiate() function of that object to argument, and it will call the Instantiate() function of that object to
restore it. restore it.
\param from The archived object. \param from The archived object.
\return The object returns a pointer to the instantiated object, or \c NULL \return The object returns a pointer to the instantiated object, or \c NULL
if the instantiation failed. The global \c errno variable will contain the if the instantiation failed. The global \c errno variable will contain
reason why it failed. the reason why it failed.
\see instantiate_object(BMessage *from, image_id *id) \see instantiate_object(BMessage *from, image_id *id)
*/ */
/*! /*!
\fn bool validate_instantiation(BMessage* from, const char* className) \fn bool validate_instantiation(BMessage* from, const char* className)
\brief Internal function that checks if the \a className is the same as the \brief Internal function that checks if the \a className is the same as the
one stored in the \a from message. one stored in the \a from message.
*/ */
/*!
\fn instantiation_func find_instantiation_func(const char* className, const char* signature)
\brief Internal function that searches for the instantiation func with a
specific signature. Use instantiate_object() instead.
*/
/*! /*!
\fn instantiation_func find_instantiation_func(const char* className) \fn instantiation_func find_instantiation_func(const char* className,
\brief Internal function that searches for the instantiation func of a const char* signature)
specific class. Use instantiate_object() instead. \brief Internal function that searches for the instantiation func with a
specific signature. Use instantiate_object() instead.
*/ */
/*! /*!
\fn instantiation_func find_instantiation_func(BMessage* archive) \fn instantiation_func find_instantiation_func(const char* className)
\brief Internal function that searches for the instantiation func that \brief Internal function that searches for the instantiation func of a
works on the specified \a archive. Use instantiate_object() instead. specific class. Use instantiate_object() instead.
*/ */
/*!
\fn instantiation_func find_instantiation_func(BMessage* archive)
\brief Internal function that searches for the instantiation func that
works on the specified \a archive. Use instantiate_object() instead.
*/
//! @} //! @}
docs/user/support/BlockCache.dox
+88 -79
View File
@@ -3,124 +3,133 @@
* Distributed under the terms of the MIT License. * Distributed under the terms of the MIT License.
* *
* Authors: * Authors:
* Niels Sascha Reedijk <[email protected]> * Niels Sascha Reedijk, [email protected]
* *
* Proofreading: * Proofreading:
* David Weizades <[email protected]> * David Weizades, [email protected]
* Thom Holwerda <[email protected]> * Thom Holwerda, [email protected]
* *
* Corresponds to: * Corresponds to:
* /trunk/headers/os/support/BlockCache.h rev 19972 * /trunk/headers/os/support/BlockCache.h rev 19972
* /trunk/src/kits/support/BlockCache.cpp rev 4568 * /trunk/src/kits/support/BlockCache.cpp rev 4568
*/ */
/*! /*!
\file BlockCache.h \file BlockCache.h
\brief Implements a mechanism to store and retrieve memory blocks. \brief Implements a mechanism to store and retrieve memory blocks.
*/ */
/*! /*!
\var B_OBJECT_CACHE \var B_OBJECT_CACHE
\brief Used in the constructor of BBlockCache. Determines that objects will \brief Used in the constructor of BBlockCache. Determines that objects will
be created using \c new[] and \c delete[]. be created using \c new[] and \c delete[].
*/ */
/*! /*!
\var B_MALLOC_CACHE \var B_MALLOC_CACHE
\brief Used in the constructor of BBlockCache. Determines that objects will \brief Used in the constructor of BBlockCache. Determines that objects will
be created using \c malloc() and \c free(). be created using \c malloc() and \c free().
*/ */
/*! /*!
\class BBlockCache \class BBlockCache
\ingroup support \ingroup support
\ingroup libbe \ingroup libbe
\brief A class that creates and maintains a pool of memory blocks. \brief A class that creates and maintains a pool of memory blocks.
In some performance critical code there might come a time where you require a In some performance critical code there might come a time where you require
lot of little blocks of memory that you want to access and dispose of a lot of little blocks of memory that you want to access and dispose of
continuously. Since allocating and freeing memory are 'expensive' operations, continuously. Since allocating and freeing memory are 'expensive'
it is better to have a pool of memory blocks at your disposal. Luckily, the operations, it is better to have a pool of memory blocks at your disposal.
Haiku API provides a class that will act as the administrator of your memory Luckily, the Haiku API provides a class that will act as the administrator
pool, so you will not have to reinvent the wheel every time. of your memory pool, so you will not have to reinvent the wheel every time.
The principle is easy. The constructor takes the number of blocks you The principle is easy. The constructor takes the number of blocks you
want to create beforehand, the size of the blocks, and the method of want to create beforehand, the size of the blocks, and the method of
allocation. This can either be #B_OBJECT_CACHE or #B_MALLOC_CACHE. allocation. This can either be #B_OBJECT_CACHE or #B_MALLOC_CACHE.
The first one uses C++ operators \c new[] and \c delete[], while the second The first one uses C++ operators \c new[] and \c delete[], while the second
one uses \c malloc() and \c free(). Unless you have specific demands on one uses \c malloc() and \c free(). Unless you have specific demands on
performance or you want to take care of freeing the objects yourself, either performance or you want to take care of freeing the objects yourself, either
way works fine. way works fine.
As soon as you have the memory pool, you can Get() blocks. If the As soon as you have the memory pool, you can Get() blocks. If the
pre-allocated memory blocks run out, BBlockCache will allocate new ones, so pre-allocated memory blocks run out, BBlockCache will allocate new ones, so
you will not have to worry about availability. As soon as you are done you can you will not have to worry about availability. As soon as you are done you
Save() the memory back into the pool. BBlockCache will make sure that no more can Save() the memory back into the pool. BBlockCache will make sure that no
blocks will be saved than the initial number you requested when you created more blocks will be saved than the initial number you requested when you
the object, so be aware of that. created the object, so be aware of that.
As soon as you got a pointer from the Get() method, you own that block of As soon as you got a pointer from the Get() method, you own that block of
memory; this means that you have the liberty to dispose of it yourself. It memory; this means that you have the liberty to dispose of it yourself. It
also means that when you delete your BBlockCache instance, any blocks of also means that when you delete your BBlockCache instance, any blocks of
memory that are checked out will not be destroyed. In case you might want to memory that are checked out will not be destroyed. In case you might want to
delete your objects yourself, make sure you free the memory the right way. If delete your objects yourself, make sure you free the memory the right way.
you created the object as #B_OBJECT_CACHE, use \c delete[] to free your If you created the object as #B_OBJECT_CACHE, use \c delete[] to free your
object. If you created the object as #B_MALLOC_CACHE, use \c free(). Please object. If you created the object as #B_MALLOC_CACHE, use \c free(). Please
note that it defeats the purpose of this class if your are going to free all note that it defeats the purpose of this class if your are going to free all
the objects yourself since it basically means that when the pool runs out, the objects yourself since it basically means that when the pool runs out,
Get() will be allocating the objects by itself. Get() will be allocating the objects by itself.
\note BBlockCache is thread-safe. \note BBlockCache is thread-safe.
*/ */
/*! /*!
\fn BBlockCache::BBlockCache(uint32 blockCount, size_t blockSize, uint32 allocationType) \fn BBlockCache::BBlockCache(uint32 blockCount, size_t blockSize, uint32
\brief Allocate a new memory pool. allocationType)
\brief Allocate a new memory pool.
\param blockCount The number of free memory blocks you want to allocate \param blockCount The number of free memory blocks you want to allocate
initially. This number is also used as the maximum number of free blocks initially. This number is also used as the maximum number of free blocks
that will be kept. that will be kept.
\param blockSize The size of the blocks. \param blockSize The size of the blocks.
\param allocationType Either #B_OBJECT_CACHE for using \c new[] and \param allocationType Either #B_OBJECT_CACHE for using \c new[] and
\c delete[] or #B_MALLOC_CACHE for \c malloc() and \c free(). \c delete[] or #B_MALLOC_CACHE for \c malloc() and \c free().
*/ */
/*! /*!
\fn BBlockCache::~BBlockCache() \fn BBlockCache::~BBlockCache()
\brief Destroy the empty blocks in the free list. \brief Destroy the empty blocks in the free list.
Note that the blocks you checked out with Get() and not checked back in with Note that the blocks you checked out with Get() and not checked back in with
Save() will not be freed, since ownership belongs to you. Make sure you clean Save() will not be freed, since ownership belongs to you. Make sure you
up after yourself. clean up after yourself.
*/ */
/*! /*!
\fn void *BBlockCache::Get(size_t blockSize) \fn void *BBlockCache::Get(size_t blockSize)
\brief Get a block from the pool of free blocks. \brief Get a block from the pool of free blocks.
If the pool runs out of free blocks, a new one will be allocated. Please note If the pool runs out of free blocks, a new one will be allocated. Please
that if the size given in the \c blockSize parameter is different from the note that if the size given in the \c blockSize parameter is different from
size given in the constructor, a new block of memory will be created. Only the size given in the constructor, a new block of memory will be created.
sizes that match the blocks in the memory pool will come from the pool. Only sizes that match the blocks in the memory pool will come from the pool.
\param blockSize The required size of the memory block. \param blockSize The required size of the memory block.
\return Returns a pointer to a memory block, or \c NULL if locking the object \return Returns a pointer to a memory block, or \c NULL if locking the
failed. object failed.
*/ */
/*! /*!
\fn void BBlockCache::Save(void *pointer, size_t blockSize) \fn void BBlockCache::Save(void *pointer, size_t blockSize)
\brief Save a block of memory to the memory pool. \brief Save a block of memory to the memory pool.
The block of memory will only be added to the pool if the \c blockSize is The block of memory will only be added to the pool if the \c blockSize is
equal to the size the object was created with and if the maximum number of equal to the size the object was created with and if the maximum number of
free blocks in the list will not be exceeded. If not, the memory will be free blocks in the list will not be exceeded. If not, the memory will be
freed. freed.
Note that it is perfectly valid to pass objects other than those you got from Note that it is perfectly valid to pass objects other than those you got
Get(), but please note that the way it was created conforms to the way memory from Get(), but please note that the way it was created conforms to the way
is allocated and freed in this pool. Therefore, only feed blocks that were memory is allocated and freed in this pool. Therefore, only feed blocks that
created with \c new[] if the allocation type is #B_OBJECT_CACHE. Likewise, were created with \c new[] if the allocation type is #B_OBJECT_CACHE.
you should only use objects allocated with \c malloc() when the allocation Likewise, you should only use objects allocated with \c malloc() when the
type is #B_MALLOC_CACHE. allocation type is #B_MALLOC_CACHE.
*/ */
docs/user/support/List.dox
+277 -231
View File
@@ -3,375 +3,421 @@
* Distributed under the terms of the MIT License. * Distributed under the terms of the MIT License.
* *
* Authors: * Authors:
* Niels Sascha Reedijk <[email protected]> * Niels Sascha Reedijk, [email protected]
* *
* Proofreading: * Proofreading:
* David Weizades <[email protected]> * David Weizades, [email protected]
* Thom Holwerda <[email protected]> * Thom Holwerda, [email protected]
* John Drinkwater <[email protected]> * John Drinkwater, [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
*/ */
/*!
\file List.h
\brief Defines the BList class.
*/
/*! /*!
\class BList \file List.h
\ingroup support \brief Defines the BList class.
\ingroup libbe
\brief An ordered container that is designed to hold generic \c void *
objects.
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
and as such is inherently not typed. So it will be the job of the programmer
to make sure proper data is entered since the compiler cannot check this by
itself.
BList contains a list of items that will grow and shrink depending on how
many items are in it. So you will not have to do any of the memory management
nor any ordering. These properties makes it useful in a whole range of
situations such as the interface kit within the BListView class.
A note on the ownership of the objects might come in handy. BList never
assumes ownership of the objects. As such, removing items from the list will
only remove the entries from the list; it will not delete the items
themselves. Similarly, you should also make sure that before you might delete
an object that is in a list, you will have to remove it from the list first.
\warning This class is not thread-safe.
The class implements methods to add, remove, reorder, retrieve, and query
items as well as some advanced methods which let you perform a task on all the
items in the list.
*/ */
/*! /*!
\fn BList::BList(int32 count = 20) \class BList
\brief Create a new list with a number of empty slots. \ingroup support
\ingroup libbe
\brief An ordered container that is designed to hold generic \c void *
objects.
The memory management of this class allocates new memory per block. The This class is designed to be used for a variety of tasks. Unlike similar
\c count parameter can be tweaked to determine the size of these blocks. implementations in other libraries, this class is not based on templates
In general, if you know your list is only going to contain a certain number of and as such is inherently not typed. So it will be the job of the programmer
items at most, you can pass that value. If you expect your list to have very to make sure proper data is entered since the compiler cannot check this by
few items, it is safe to choose a low number. This is to prevent the list from itself.
taking up unneeded memory. If you expect the list to contain a large number
of items, choose a higher value. Every time the memory is full, all the items
have to be copied into a new piece of allocated memory, which is an expensive
operation.
If you are unsure, you do not have to worry too much. Just make sure you do BList contains a list of items that will grow and shrink depending on how
not use a lot of lists, and as long as the list is not used in one of the many items are in it. So you will not have to do any of the memory
performance critical parts of the code, you are safe to go with the default management nor any ordering. These properties makes it useful in a whole
values. range of situations such as the interface kit within the BListView class.
\param count The size of the blocks allocated in memory. A note on the ownership of the objects might come in handy. BList never
assumes ownership of the objects. As such, removing items from the list will
only remove the entries from the list; it will not delete the items
themselves. Similarly, you should also make sure that before you might
delete an object that is in a list, you will have to remove it from the list
first.
\warning This class is not thread-safe.
The class implements methods to add, remove, reorder, retrieve, and query
items as well as some advanced methods which let you perform a task on all
the items in the list.
*/ */
/*! /*!
\fn BList::BList(const BList& anotherList) \fn BList::BList(int32 count = 20)
\brief Copy constructor. Copy a complete list into this one. \brief Create a new list with a number of empty slots.
The memory management of this class allocates new memory per block. The
\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 certain number
of items at most, you can pass that value. If you expect your list to have
very few items, it is safe to choose a low number. This is to prevent the
list from taking up unneeded memory. If you expect the list to contain a
large number of items, choose a higher value. Every time the memory is full,
all the items have to be copied into a new piece of allocated memory, which
is an expensive operation.
If you are unsure, you do not have to worry too much. Just make sure you do
not use a lot of lists, and as long as the list is not used in one of the
performance critical parts of the code, you are safe to go with the default
values.
\param count The size of the blocks allocated in memory.
*/ */
/*! /*!
\fn BList::~BList() \fn BList::BList(const BList& anotherList)
\brief Destroy the list. \brief Copy constructor. Copy a complete list into this one.
Please note that as BList does not assume ownership of the objects,
only the list will be freed, not the objects that are held in it.
*/ */
/*! /*!
\fn BList& BList::operator=(const BList &list) \fn BList::~BList()
\brief Copy another list into this object. \brief Destroy the list.
Please note that as BList does not assume ownership of the objects,
only the list will be freed, not the objects that are held in it.
*/ */
/*! /*!
\name Adding and Removing Items \fn BList& BList::operator=(const BList &list)
\brief Copy another list into this object.
*/ */
/*!
\name Adding and Removing Items
*/
//! @{ //! @{
/*!
\fn bool BList::AddItem(void *item, int32 index)
\brief Add an item at a certain position.
\param item The item to add.
\param index The place in the list.
\retval true The item was added.
\retval false Item was not added. Either the index is negative or invalid,
or resizing the list failed.
\see AddItem(void *item)
*/
/*! /*!
\fn bool BList::AddItem(void *item) \fn bool BList::AddItem(void *item, int32 index)
\brief Append an item to the list. \brief Add an item at a certain position.
\param item The item to add. \param item The item to add.
\retval true The item was appended. \param index The place in the list.
\retval false Item was not appended, since resizing the list failed. \retval true The item was added.
\see AddItem(void *item, int32 index) \retval false Item was not added. Either the index is negative or invalid,
or resizing the list failed.
\see AddItem(void *item)
*/ */
/*! /*!
\fn bool BList::AddList(const BList *list, int32 index) \fn bool BList::AddItem(void *item)
\brief Add items from another list to this list at a certain position. \brief Append an item to the list.
Note that the \a list parameter is \c const, so the original list will not be \param item The item to add.
altered. \retval true The item was appended.
\retval false Item was not appended, since resizing the list failed.
\param list The list to be added. \see AddItem(void *item, int32 index)
\param index The position in the current list where the new item(s) should be
put.
\retval true The list was added.
\retval false Failed to insert the list, due to the fact that resizing our
list failed.
\see AddList(const BList *list)
*/ */
/*! /*!
\fn bool BList::AddList(const BList *list) \fn bool BList::AddList(const BList *list, int32 index)
\brief Append a list to this list. \brief Add items from another list to this list at a certain position.
Note that the \a list parameter is a \c const, so the original list will not Note that the \a list parameter is \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 added.
\retval true The list was appended. \param index The position in the current list where the new item(s) should
\retval false Failed to append the list, due to the fact that resizing of our be put.
list failed. \retval true The list was added.
\see AddList(const BList *list, int32 index) \retval false Failed to insert the list, due to the fact that resizing our
list failed.
\see AddList(const BList *list)
*/ */
/*! /*!
\fn bool BList::RemoveItem(void *item) \fn bool BList::AddList(const BList *list)
\brief Remove an item from the list. \brief Append a list to this list.
\param item The item that should be removed. Note that the \a list parameter is a \c const, so the original list will not
\retval true The item was found and removed. be altered.
\retval false The item was not in this list and thus not removed.
\see RemoveItem(int32 index) \param list The list to be appended.
\retval true The list was appended.
\retval false Failed to append the list, due to the fact that resizing of
our list failed.
\see AddList(const BList *list, int32 index)
*/ */
/*! /*!
\fn void * BList::RemoveItem(int32 index) \fn bool BList::RemoveItem(void *item)
\brief Remove the item at \a index from the list. \brief Remove an item from the list.
\param index The item that should be removed. \param item The item that should be removed.
\return The pointer to the item that was removed, or \c NULL in case the \retval true The item was found and removed.
index was invalid. \retval false The item was not in this list and thus not removed.
\see RemoveItem(void *item) \see RemoveItem(int32 index)
*/ */
/*! /*!
\fn bool BList::RemoveItems(int32 index, int32 count) \fn void * BList::RemoveItem(int32 index)
\brief Remove a number of items starting at a certain position. \brief Remove the item at \a index from the list.
If the count parameter is larger than the number of items in the list, \param index The item that should be removed.
all the items from the offset to the end will be removed. \return The pointer to the item that was removed, or \c NULL in case the
index was invalid.
\param index The offset in the list where removal should start. \see RemoveItem(void *item)
\param count The number of items to remove.
\retval true Removal succeeded.
\retval false Failed to remove the items because the index was invalid.
*/ */
/*! /*!
\fn bool BList::ReplaceItem(int32 index, void *newItem) \fn bool BList::RemoveItems(int32 index, int32 count)
\brief Replace an item with another one. \brief Remove a number of items starting at a certain position.
\param index The offset in the list where to put the item. If the count parameter is larger than the number of items in the list,
\param newItem The new item to put in the list. all the items from the offset to the end will be removed.
\retval true Item replaced.
\retval false The index was invalid. \param index The offset in the list where removal should start.
\param count The number of items to remove.
\retval true Removal succeeded.
\retval false Failed to remove the items because the index was invalid.
*/ */
/*! /*!
\fn void BList::MakeEmpty() \fn bool BList::ReplaceItem(int32 index, void *newItem)
\brief Clear all the items from the list. \brief Replace an item with another one.
Please note that this does not free the items. \param index The offset in the list where to put the item.
\param newItem The new item to put in the list.
\retval true Item replaced.
\retval false The index was invalid.
*/ */
/*!
\fn void BList::MakeEmpty()
\brief Clear all the items from the list.
Please note that this does not free the items.
*/
//! @} //! @}
/*! /*!
\name Reordering Items \name Reordering Items
*/ */
//! @{ //! @{
/*! /*!
\fn void BList::SortItems(int (*compareFunc)(const void *, const void *)) \fn void BList::SortItems(int (*compareFunc)(const void *, const void *))
\brief Sort the items with the use of a supplied comparison function. \brief Sort the items with the use of a supplied comparison function.
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
an integer. return an integer.
For an example, see the Compare(const BString *, const BString *) function. For an example, see the Compare(const BString *, const BString *) function.
*/ */
/*!
\fn bool BList::SwapItems(int32 indexA, int32 indexB)
\brief Swap two items.
\param indexA The first item. /*!
\param indexB The second item. \fn bool BList::SwapItems(int32 indexA, int32 indexB)
\retval true Swap succeeded. \brief Swap two items.
\retval false Swap failed because one of the indexes was invalid.
\param indexA The first item.
\param indexB The second item.
\retval true Swap succeeded.
\retval false Swap failed because one of the indexes was invalid.
*/ */
/*!
\fn bool BList::MoveItem(int32 fromIndex, int32 toIndex)
\brief Move an item to a new place
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: \fn bool BList::MoveItem(int32 fromIndex, int32 toIndex)
\verbatim \brief Move an item to a new place
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:
\verbatim
A B C D E F G H I J A B C D E F G H I J
\endverbatim \endverbatim
Moving 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
\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 due to the indexes being invalid. \retval false Move failed due to the indexes being invalid.
*/ */
//! @} //! @}
/*! /*!
\name Retrieving Items \name Retrieving Items
*/ */
//! @{ //! @{
/*!
\fn void *BList::ItemAt(int32 index) const
\brief Get an item.
\param index The item to retrieve.
\return A pointer to the item in that position, or \c NULL if the index is
out of bounds.
\see ItemAtFast(int32 index) const
*/
/*! /*!
\fn void *BList::FirstItem() const \fn void *BList::ItemAt(int32 index) const
\brief Get the first item. \brief Get an item.
\return A pointer to the first item or \c NULL if the list is empty. \param index The item to retrieve.
\see LastItem() const \return A pointer to the item in that position, or \c NULL if the index is
out of bounds.
\see ItemAtFast(int32 index) const
*/ */
/*! /*!
\fn void *BList::ItemAtFast(int32 index) const \fn void *BList::FirstItem() const
\brief Get an item. \brief Get the first item.
This method does not perform any boundary checks when it retrieves an item. \return A pointer to the first item or \c NULL if the list is empty.
Use this method in a performance critical area of your program where you are \see LastItem() const
sure you will not get an invalid item.
\return A pointer to the item.
*/ */
/*! /*!
\fn void *BList::LastItem() const \fn void *BList::ItemAtFast(int32 index) const
\brief Get the last item. \brief Get an item.
\return A pointer to the last item or \c NULL if the list is empty.
\see FirstItem() const This method does not perform any boundary checks when it retrieves an item.
Use this method in a performance critical area of your program where you are
sure you will not get an invalid item.
\return A pointer to the item.
*/ */
/*! /*!
\fn void *BList::Items() const \fn void *BList::LastItem() const
\brief Return the internal list of objects. \brief Get the last item.
\return A pointer to the last item or \c NULL if the list is empty.
This method will return a pointer to the internal pointer list. This means \see FirstItem() const
that you should be careful what you are doing, since you are working with the
internals of the class directly.
It is not a good idea to make any changes to the list, since that will mess
up the internal consistency.
\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 is
a bad idea to begin with and that you should avoid this method. The list of
objects does not belong to you. See also DoForEach() for an alternate
method.
\return The internal list of pointers.
*/ */
/*!
\fn void *BList::Items() const
\brief Return the internal list of objects.
This method will return a pointer to the internal pointer list. This means
that you should be careful what you are doing, since you are working with
the internals of the class directly.
It is not a good idea to make any changes to the list, since that will mess
up the internal consistency.
\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 is a bad idea to begin with and that you should avoid this method.
The list of objects does not belong to you. See also DoForEach() for an
alternate method.
\return The internal list of pointers.
*/
//! @} //! @}
/*! /*!
\name Querying for Items \name Querying for Items
*/ */
//! @{ //! @{
/*!
\fn bool BList::HasItem(void *item) const
\brief Check if an item is in the list.
*/
/*! /*!
\fn int32 BList::IndexOf(void *item) const \fn bool BList::HasItem(void *item) const
\brief Get the index of an item. \brief Check if an item is in the list.
\return The index of the item, or -1 when the item is not in the list.
*/ */
/*! /*!
\fn int32 BList::CountItems() const \fn int32 BList::IndexOf(void *item) const
\brief Get the number of items in the list. \brief Get the index of an item.
\return The index of the item, or -1 when the item is not in the list.
*/ */
/*! /*!
\fn bool BList::IsEmpty() const \fn int32 BList::CountItems() const
\brief Check if there are items in the list. \brief Get the number of items in the list.
*/ */
/*!
\fn bool BList::IsEmpty() const
\brief Check if there are items in the list.
*/
//! @} //! @}
/*! /*!
\name Iterating over the List \name Iterating over the List
*/ */
//! @{ //! @{
/*!
\fn void BList::DoForEach(bool (*func)(void* item))
\brief Perform an action on every item in the list.
If one of the actions on the items fails it means that the \a func function
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.
\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))
\brief Perform an action on every item in the list with an argument. \brief Perform an action on every item in the list.
If one of the actions on the items fails it means that the \a func function If one of the actions on the items fails it means that the \a func function
returned \c false and 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 that takes a \c void * argument and returns a
and the second \c void * being the argument that you supply. It should boolean.
return a boolean value on whether it succeeded or not. \see DoForEach(bool (*func)(void* item, void* arg2), void *arg2)
\param arg2 An argument to supply to \a func.
\see DoForEach(bool (*func)(void* item))
*/ */
/*!
\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.
If one of the actions on the items fails it means that the \a func function
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
and the second \c void * being the argument that you supply. It should
return a boolean value on whether it succeeded or not.
\param arg2 An argument to supply to \a func.
\see DoForEach(bool (*func)(void* item))
*/
//! @} //! @}