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
+196 -176
View File
@@ -1,176 +1,196 @@
/* /*
* 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.
* *
* 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. \file Archivable.h
*/ \brief Provides the BArchivable interface.
*/
/*!
\class BArchivable
\ingroup support /*!
\ingroup libbe \class BArchivable
\brief Interface for objects that can be archived into a BMessage. \ingroup support
\ingroup libbe
BArchivable provides an interface for objects that can be put into message \brief Interface for objects that can be archived into a BMessage.
archives and extracted into objects in another location. Using this you are
able to send objects between applications, or even between computers across BArchivable provides an interface for objects that can be put into message
networks. archives and extracted into objects in another location. Using this you are
able to send objects between applications, or even between computers across
BArchivable differs from BFlattenable in that BFlattenable is designed to networks.
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 BArchivable differs from BFlattenable in that BFlattenable is designed to
be restored to other objects. To illustrate this point, BArchivable messages store objects into flat streams of data, the main objective being storage to
know how to restore themselves whereas BFlattenables have a datatype which disk. The objective of this interface, however, is to store objects that
you need to map to classes manually. will be restored to other objects. To illustrate this point, BArchivable
messages know how to restore themselves whereas BFlattenables have a
Archiving is done with the Archive() method. If your class supports it, the datatype which you need to map to classes manually.
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 Archiving is done with the Archive() method. If your class supports it, the
Instantiate() method, which is static. Since the interface is designed to caller can request it to store into a deep archive, meaning that all child
extract objects without the caller knowing what kind of object it actually is, objects in it will be stored. Extracting the archive works with the
the global function #instantiate_object() instantiates a message without you Instantiate() method, which is static. Since the interface is designed to
manually having to determine the class the message is from. This adds extract objects without the caller knowing what kind of object it actually
considerable flexibility and allows BArchivable to be used in combination with is, the global function #instantiate_object() instantiates a message without
other add-ons. you manually having to determine the class the message is from. This adds
considerable flexibility and allows BArchivable to be used in combination
To provide this interface in your classes you should publicly inherit this with other add-ons.
class. You should implement Archive() and Instantiate(), and provide one
constructor that takes one BMessage argument. 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)
\brief Constructor. Does nothing.
/*!
If you inherit this interface you should provide at least one constructor that \fn BArchivable::BArchivable(BMessage* from)
takes one BMessage argument. \brief Constructor. Does nothing.
*/
If you inherit this interface you should provide at least one constructor
/*! that takes one BMessage argument.
\fn BArchivable::BArchivable() */
\brief Constructor. Does nothing.
*/
/*!
/*! \fn BArchivable::BArchivable()
\fn BArchivable::~BArchivable() \brief Constructor. Does nothing.
\brief Destructor. 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. \fn virtual status_t BArchivable::Archive(BMessage* into,
\param deep If \c true, all children of this object should be stored as well. bool deep = true) const
Only pay attention to this parameter if you actually have child objects. \brief Archive the object into a BMessage.
\retval B_OK The archiving succeeded.
\retval "error codes" The archiving did not succeed. 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.
\fn static BArchivable* BArchivable::Instantiate(BMessage* archive) \param deep If \c true, all children of this object should be stored as
\brief Static member to restore objects from messages. well. Only pay attention to this parameter if you actually have child
objects.
You should always check that the \a archive argument actually corresponds to \retval B_OK The archiving succeeded.
your class. The automatic functions, such as #instantiate_object() will not \retval "error codes" The archiving did not succeed.
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. \fn static BArchivable* BArchivable::Instantiate(BMessage* archive)
\warning The default implementation will always return \c NULL. Even though \brief Static member to restore objects from messages.
it is possible to store plain BArchive objects, it is impossible to restore
them. You should always check that the \a archive argument actually corresponds to
\see instantiate_object(BMessage *from) 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.
\fn virtual status_t BArchivable::Perform(perform_code d, void* arg) \retval You should return a pointer to your object, or \c NULL if you
\brief Internal method. fail.
\internal This method is defined in case of unforeseen binary compatibility \warning The default implementation will always return \c NULL. Even though
API issues. Currently nothing of interest is implemented. it is possible to store plain BArchive objects, it is impossible to
*/ restore them.
\see instantiate_object(BMessage *from)
///// Global methods ///// */
/*!
\addtogroup support_globals
@{ /*!
*/ \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
\typedef typedef BArchivable* (*instantiation_func)(BMessage*) API issues. Currently nothing of interest is implemented.
\brief Internal definition of a function that can instantiate objects that */
have been created with the BArchivable API.
*/
///// Global methods /////
/*! /*!
\fn BArchivable* instantiate_object(BMessage *from, image_id *id) \addtogroup support_globals
\brief Instantiate an archived object with the object being defined in a @{
different application or library. */
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 /*!
stored. \typedef typedef BArchivable* (*instantiation_func)(BMessage*)
\brief Internal definition of a function that can instantiate objects that
\note Images are names for executable files. Image id's refer to these have been created with the BArchivable API.
executable files that have been loaded by your application. Have a look */
at the kernel API for further information.
*/
/*!
/*! \fn BArchivable* instantiate_object(BMessage *from, image_id *id)
\fn BArchivable* instantiate_object(BMessage *from) \brief Instantiate an archived object with the object being defined in a
\brief Instantiate an archived object. different application or library.
This global function will determine the base class, based on the \a from This function is similar to instantiate_object(BMessage *from), except that
argument, and it will call the Instantiate() function of that object to it takes the \a id argument referring to an image where the object might be
restore it. stored.
\param from The archived object. \note Images are names for executable files. Image id's refer to these
\return The object returns a pointer to the instantiated object, or \c NULL executable files that have been loaded by your application. Have a look
if the instantiation failed. The global \c errno variable will contain the at the kernel API for further information.
reason why it failed. */
\see instantiate_object(BMessage *from, image_id *id)
*/
/*!
/*! \fn BArchivable* instantiate_object(BMessage *from)
\fn bool validate_instantiation(BMessage* from, const char* className) \brief Instantiate an archived object.
\brief Internal function that checks if the \a className is the same as the
one stored in the \a from message. 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
restore it.
/*!
\fn instantiation_func find_instantiation_func(const char* className, const char* signature) \param from The archived object.
\brief Internal function that searches for the instantiation func with a \return The object returns a pointer to the instantiated object, or \c NULL
specific signature. Use instantiate_object() instead. if the instantiation failed. The global \c errno variable will contain
*/ the reason why it failed.
\see instantiate_object(BMessage *from, image_id *id)
/*! */
\fn instantiation_func find_instantiation_func(const char* className)
\brief Internal function that searches for the instantiation func of a
specific class. Use instantiate_object() instead. /*!
*/ \fn bool validate_instantiation(BMessage* from, const char* className)
\brief Internal function that checks if the \a className is the same as the
/*! one stored in the \a from message.
\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.
*/ /*!
\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)
\brief Internal function that searches for the instantiation func of a
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
+100 -91
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
initially. This number is also used as the maximum number of free blocks \param blockCount The number of free memory blocks you want to allocate
that will be kept. initially. This number is also used as the maximum number of free blocks
\param blockSize The size of the blocks. that will be kept.
\param allocationType Either #B_OBJECT_CACHE for using \c new[] and \param blockSize The size of the blocks.
\c delete[] or #B_MALLOC_CACHE for \c malloc() and \c free(). \param allocationType Either #B_OBJECT_CACHE for using \c new[] and
\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
+299 -253
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
The memory management of this class allocates new memory per block. The \brief An ordered container that is designed to hold generic \c void *
\c count parameter can be tweaked to determine the size of these blocks. objects.
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 This class is designed to be used for a variety of tasks. Unlike similar
few items, it is safe to choose a low number. This is to prevent the list from implementations in other libraries, this class is not based on templates
taking up unneeded memory. If you expect the list to contain a large number and as such is inherently not typed. So it will be the job of the programmer
of items, choose a higher value. Every time the memory is full, all the items to make sure proper data is entered since the compiler cannot check this by
have to be copied into a new piece of allocated memory, which is an expensive itself.
operation.
BList contains a list of items that will grow and shrink depending on how
If you are unsure, you do not have to worry too much. Just make sure you do many items are in it. So you will not have to do any of the memory
not use a lot of lists, and as long as the list is not used in one of the management nor any ordering. These properties makes it useful in a whole
performance critical parts of the code, you are safe to go with the default range of situations such as the interface kit within the BListView class.
values.
A note on the ownership of the objects might come in handy. BList never
\param count The size of the blocks allocated in memory. 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 *))
\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
an integer.
For an example, see the Compare(const BString *, const BString *) function.
*/
/*! /*!
\fn bool BList::SwapItems(int32 indexA, int32 indexB) \fn void BList::SortItems(int (*compareFunc)(const void *, const void *))
\brief Swap two items. \brief Sort the items with the use of a supplied comparison function.
\param indexA The first item. The function should take two \c const pointers as arguments and should
\param indexB The second item. return an integer.
\retval true Swap succeeded.
\retval false Swap failed because one of the indexes was invalid. For an example, see the Compare(const BString *, const BString *) function.
*/ */
/*!
\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::SwapItems(int32 indexA, int32 indexB)
\verbatim \brief Swap two items.
\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:
\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))
*/
//! @} //! @}