From 55f7db1bd9cf6ffda3d593de1b88fdf834b766f8 Mon Sep 17 00:00:00 2001 From: Niels Sascha Reedijk Date: Mon, 6 Aug 2007 09:32:27 +0000 Subject: [PATCH] Update according to the latest guideline changes. These files already 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 --- docs/user/support/Archivable.dox | 372 +++++++++++---------- docs/user/support/BlockCache.dox | 191 ++++++----- docs/user/support/List.dox | 552 +++++++++++++++++-------------- 3 files changed, 595 insertions(+), 520 deletions(-) diff --git a/docs/user/support/Archivable.dox b/docs/user/support/Archivable.dox index addcba5d4a..5204e83ca2 100644 --- a/docs/user/support/Archivable.dox +++ b/docs/user/support/Archivable.dox @@ -1,176 +1,196 @@ -/* - * Copyright 2007, Haiku, Inc. All Rights Reserved. - * Distributed under the terms of the MIT License. - * - * Author: - * Niels Sascha Reedijk - * - * Proofreader: - * David Weizades - * Thom Holwerda - * - * Corresponds to: - * /trunk/headers/os/support/Archivable.h rev 19972 - * /trunk/src/kits/support/Archivable.cpp rev 19095 - */ - -/*! - \file Archivable.h - \brief Provides the BArchivable interface. -*/ - -/*! - \class BArchivable - \ingroup support - \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) - \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() - \brief Destructor. Does nothing. -*/ - -/*! - \fn virtual status_t BArchivable::Archive(BMessage* into, bool deep = true) const - \brief Archive the object into a BMessage. - - 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) - \brief Static member to restore objects from messages. - - 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 ///// -/*! - \addtogroup support_globals - @{ -*/ - -/*! - \typedef typedef BArchivable* (*instantiation_func)(BMessage*) - \brief Internal definition of a function that can instantiate objects that - have been created with the BArchivable API. -*/ - -/*! - \fn BArchivable* instantiate_object(BMessage *from, image_id *id) - \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. - - \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 - at the kernel API for further information. -*/ - -/*! - \fn BArchivable* instantiate_object(BMessage *from) - \brief Instantiate an archived object. - - 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. - - \param from The archived object. - \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 - reason why it failed. - \see instantiate_object(BMessage *from, image_id *id) -*/ - -/*! - \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(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. -*/ - -//! @} +/* + * Copyright 2007, Haiku, Inc. All Rights Reserved. + * Distributed under the terms of the MIT License. + * + * Author: + * Niels Sascha Reedijk, niels.reedijk@gmail.com + * + * Proofreader: + * David Weizades, ddewbofh@hotmail.com + * Thom Holwerda, slakje@quicknet.nl + * + * Corresponds to: + * /trunk/headers/os/support/Archivable.h rev 19972 + * /trunk/src/kits/support/Archivable.cpp rev 19095 + */ + + +/*! + \file Archivable.h + \brief Provides the BArchivable interface. +*/ + + +/*! + \class BArchivable + \ingroup support + \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) + \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() + \brief Destructor. Does nothing. +*/ + + +/*! + \fn virtual status_t BArchivable::Archive(BMessage* into, + bool deep = true) const + \brief Archive the object into a BMessage. + + 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) + \brief Static member to restore objects from messages. + + 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 ///// +/*! + \addtogroup support_globals + @{ +*/ + + +/*! + \typedef typedef BArchivable* (*instantiation_func)(BMessage*) + \brief Internal definition of a function that can instantiate objects that + have been created with the BArchivable API. +*/ + + +/*! + \fn BArchivable* instantiate_object(BMessage *from, image_id *id) + \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. + + \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 + at the kernel API for further information. +*/ + + +/*! + \fn BArchivable* instantiate_object(BMessage *from) + \brief Instantiate an archived object. + + 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. + + \param from The archived object. + \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 reason why it failed. + \see instantiate_object(BMessage *from, image_id *id) +*/ + + +/*! + \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(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. +*/ + + +//! @} diff --git a/docs/user/support/BlockCache.dox b/docs/user/support/BlockCache.dox index 826caee813..3e44079748 100644 --- a/docs/user/support/BlockCache.dox +++ b/docs/user/support/BlockCache.dox @@ -3,124 +3,133 @@ * Distributed under the terms of the MIT License. * * Authors: - * Niels Sascha Reedijk + * Niels Sascha Reedijk, niels.reedijk@gmail.com * * Proofreading: - * David Weizades - * Thom Holwerda + * David Weizades, ddewbofh@hotmail.com + * Thom Holwerda, slakje@quicknet.nl * * Corresponds to: * /trunk/headers/os/support/BlockCache.h rev 19972 * /trunk/src/kits/support/BlockCache.cpp rev 4568 */ - + + /*! - \file BlockCache.h - \brief Implements a mechanism to store and retrieve memory blocks. + \file BlockCache.h + \brief Implements a mechanism to store and retrieve memory blocks. */ + /*! - \var B_OBJECT_CACHE - \brief Used in the constructor of BBlockCache. Determines that objects will - be created using \c new[] and \c delete[]. + \var B_OBJECT_CACHE + \brief Used in the constructor of BBlockCache. Determines that objects will + be created using \c new[] and \c delete[]. */ + /*! - \var B_MALLOC_CACHE - \brief Used in the constructor of BBlockCache. Determines that objects will - be created using \c malloc() and \c free(). + \var B_MALLOC_CACHE + \brief Used in the constructor of BBlockCache. Determines that objects will + be created using \c malloc() and \c free(). */ + /*! - \class BBlockCache - \ingroup support - \ingroup libbe - \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 - lot of little blocks of memory that you want to access and dispose of - continuously. Since allocating and freeing memory are 'expensive' operations, - it is better to have a pool of memory blocks at your disposal. Luckily, the - Haiku API provides a class that will act as the administrator 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 - 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. - 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 - performance or you want to take care of freeing the objects yourself, either - way works fine. - - 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 - you will not have to worry about availability. As soon as you are done you can - Save() the memory back into the pool. BBlockCache will make sure that no more - blocks will be saved than the initial number you requested when you created - the object, so be aware of that. - - 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 - 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 - delete your objects yourself, make sure you free the memory the right way. 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 - 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, - Get() will be allocating the objects by itself. - - \note BBlockCache is thread-safe. + \class BBlockCache + \ingroup support + \ingroup libbe + \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 lot of little blocks of memory that you want to access and dispose of + continuously. Since allocating and freeing memory are 'expensive' + operations, it is better to have a pool of memory blocks at your disposal. + Luckily, the Haiku API provides a class that will act as the administrator + 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 + 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. + 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 + performance or you want to take care of freeing the objects yourself, either + way works fine. + + 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 + you will not have to worry about availability. As soon as you are done you + can Save() the memory back into the pool. BBlockCache will make sure that no + more blocks will be saved than the initial number you requested when you + created the object, so be aware of that. + + 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 + 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 + delete your objects yourself, make sure you free the memory the right way. + 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 + 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, + Get() will be allocating the objects by itself. + + \note BBlockCache is thread-safe. */ + /*! - \fn BBlockCache::BBlockCache(uint32 blockCount, size_t blockSize, uint32 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 - that will be kept. - \param blockSize The size of the blocks. - \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(uint32 blockCount, size_t blockSize, uint32 + 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 + that will be kept. + \param blockSize The size of the blocks. + \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() - \brief Destroy the empty blocks in the free list. - - 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 - up after yourself. + \fn BBlockCache::~BBlockCache() + \brief Destroy the empty blocks in the free list. + + 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 up after yourself. */ + /*! - \fn void *BBlockCache::Get(size_t blockSize) - \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 - that if the size given in the \c blockSize parameter is different from the - size given in the constructor, a new block of memory will be created. Only - sizes that match the blocks in the memory pool will come from the pool. - - \param blockSize The required size of the memory block. - \return Returns a pointer to a memory block, or \c NULL if locking the object - failed. + \fn void *BBlockCache::Get(size_t blockSize) + \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 that if the size given in the \c blockSize parameter is different from + the size given in the constructor, a new block of memory will be created. + Only sizes that match the blocks in the memory pool will come from the pool. + + \param blockSize The required size of the memory block. + \return Returns a pointer to a memory block, or \c NULL if locking the + object failed. */ + /*! - \fn void BBlockCache::Save(void *pointer, size_t blockSize) - \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 - 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 - freed. - - Note that it is perfectly valid to pass objects other than those you got from - Get(), but please note that the way it was created conforms to the way memory - is allocated and freed in this pool. Therefore, only feed blocks that were - created with \c new[] if the allocation type is #B_OBJECT_CACHE. Likewise, - you should only use objects allocated with \c malloc() when the allocation - type is #B_MALLOC_CACHE. + \fn void BBlockCache::Save(void *pointer, size_t blockSize) + \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 + 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 + freed. + + Note that it is perfectly valid to pass objects other than those you got + from Get(), but please note that the way it was created conforms to the way + memory is allocated and freed in this pool. Therefore, only feed blocks that + were created with \c new[] if the allocation type is #B_OBJECT_CACHE. + Likewise, you should only use objects allocated with \c malloc() when the + allocation type is #B_MALLOC_CACHE. */ diff --git a/docs/user/support/List.dox b/docs/user/support/List.dox index bfaf48681d..a79c0d7b32 100644 --- a/docs/user/support/List.dox +++ b/docs/user/support/List.dox @@ -3,375 +3,421 @@ * Distributed under the terms of the MIT License. * * Authors: - * Niels Sascha Reedijk + * Niels Sascha Reedijk, niels.reedijk@gmail.com * * Proofreading: - * David Weizades - * Thom Holwerda - * John Drinkwater + * David Weizades, ddewbofh@hotmail.com + * Thom Holwerda, slakje@quicknet.nl + * John Drinkwater, jdrinkwater@gmail.com * * Corresponds to: * /trunk/headers/os/support/List.h rev 19972 * /trunk/src/kits/support/List.cpp rev 18649 */ -/*! - \file List.h - \brief Defines the BList class. -*/ /*! - \class BList - \ingroup support - \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. + \file List.h + \brief Defines the BList class. */ + /*! - \fn BList::BList(int32 count = 20) - \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. + \class BList + \ingroup support + \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(const BList& anotherList) - \brief Copy constructor. Copy a complete list into this one. + \fn BList::BList(int32 count = 20) + \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() - \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. + \fn BList::BList(const BList& anotherList) + \brief Copy constructor. Copy a complete list into this one. */ + /*! - \fn BList& BList::operator=(const BList &list) - \brief Copy another list into this object. + \fn BList::~BList() + \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) - \brief Append an item to the list. - - \param item The item to add. - \retval true The item was appended. - \retval false Item was not appended, since resizing the list failed. - \see AddItem(void *item, int32 index) + \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::AddList(const BList *list, int32 index) - \brief Add items from another list to this list at a certain position. - - Note that the \a list parameter is \c const, so the original list will not be - altered. - - \param list The list to be added. - \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::AddItem(void *item) + \brief Append an item to the list. + + \param item The item to add. + \retval true The item was appended. + \retval false Item was not appended, since resizing the list failed. + \see AddItem(void *item, int32 index) */ + /*! - \fn bool BList::AddList(const BList *list) - \brief Append a list to this list. - - Note that the \a list parameter is a \c const, so the original list will not - be altered. - - \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 bool BList::AddList(const BList *list, int32 index) + \brief Add items from another list to this list at a certain position. + + Note that the \a list parameter is \c const, so the original list will not + be altered. + + \param list The list to be added. + \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::RemoveItem(void *item) - \brief Remove an item from the list. - - \param item The item that should be removed. - \retval true The item was found and removed. - \retval false The item was not in this list and thus not removed. - \see RemoveItem(int32 index) + \fn bool BList::AddList(const BList *list) + \brief Append a list to this list. + + Note that the \a list parameter is a \c const, so the original list will not + be altered. + + \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) - \brief Remove the item at \a index from the list. - - \param index The item that should be removed. - \return The pointer to the item that was removed, or \c NULL in case the - index was invalid. - \see RemoveItem(void *item) + \fn bool BList::RemoveItem(void *item) + \brief Remove an item from the list. + + \param item The item that should be removed. + \retval true The item was found and removed. + \retval false The item was not in this list and thus not removed. + \see RemoveItem(int32 index) */ + /*! - \fn bool BList::RemoveItems(int32 index, int32 count) - \brief Remove a number of items starting at a certain position. - - If the count parameter is larger than the number of items in the list, - all the items from the offset to the end will be removed. - - \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::RemoveItem(int32 index) + \brief Remove the item at \a index from the list. + + \param index The item that should be removed. + \return The pointer to the item that was removed, or \c NULL in case the + index was invalid. + \see RemoveItem(void *item) */ + /*! - \fn bool BList::ReplaceItem(int32 index, void *newItem) - \brief Replace an item with another one. - - \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 bool BList::RemoveItems(int32 index, int32 count) + \brief Remove a number of items starting at a certain position. + + If the count parameter is larger than the number of items in the list, + all the items from the offset to the end will be removed. + + \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() - \brief Clear all the items from the list. - - Please note that this does not free the items. + \fn bool BList::ReplaceItem(int32 index, void *newItem) + \brief Replace an item with another one. + + \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) - \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 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::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 +/*! + \fn bool BList::SwapItems(int32 indexA, int32 indexB) + \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 - \endverbatim - - Moving 1(B)->6(G) would result in this: - \verbatim + \endverbatim + + Moving 1(B)->6(G) would result in this: + \verbatim A C D E F G B H I J - \endverbatim - - \param fromIndex The original location. - \param toIndex The new location. - \retval true Move succeeded. - \retval false Move failed due to the indexes being invalid. + \endverbatim + + \param fromIndex The original location. + \param toIndex The new location. + \retval true Move succeeded. + \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 - \brief Get the first item. - - \return A pointer to the first item or \c NULL if the list is empty. - \see LastItem() const + \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::ItemAtFast(int32 index) const - \brief Get an item. - - 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::FirstItem() const + \brief Get the first item. + + \return A pointer to the first item or \c NULL if the list is empty. + \see LastItem() const */ + /*! - \fn void *BList::LastItem() const - \brief Get the last item. - \return A pointer to the last item or \c NULL if the list is empty. - \see FirstItem() const + \fn void *BList::ItemAtFast(int32 index) const + \brief Get an item. + + 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 - \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. + \fn void *BList::LastItem() const + \brief Get the last item. + \return A pointer to the last item or \c NULL if the list is empty. + \see FirstItem() const */ + +/*! + \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 - \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::HasItem(void *item) const + \brief Check if an item is in the list. */ + /*! - \fn int32 BList::CountItems() const - \brief Get the number of items in the list. + \fn int32 BList::IndexOf(void *item) const + \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 - \brief Check if there are items in the list. + \fn int32 BList::CountItems() const + \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) - \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)) + \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) + \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)) +*/ + + //! @}