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
This commit is contained in:
Niels Sascha Reedijk
+196
-176
@@ -1,176 +1,196 @@
|
||||
/*
|
||||
* Copyright 2007, Haiku, Inc. All Rights Reserved.
|
||||
* Distributed under the terms of the MIT License.
|
||||
*
|
||||
* Author:
|
||||
* Niels Sascha Reedijk <[email protected]>
|
||||
*
|
||||
* Proofreader:
|
||||
* David Weizades <[email protected]>
|
||||
* Thom Holwerda <[email protected]>
|
||||
*
|
||||
* 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, [email protected]
|
||||
*
|
||||
* Proofreader:
|
||||
* David Weizades, [email protected]
|
||||
* Thom Holwerda, [email protected]
|
||||
*
|
||||
* 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.
|
||||
*/
|
||||
|
||||
|
||||
//! @}
|
||||
|
||||
@@ -3,124 +3,133 @@
|
||||
* Distributed under the terms of the MIT License.
|
||||
*
|
||||
* Authors:
|
||||
* Niels Sascha Reedijk <[email protected]>
|
||||
* Niels Sascha Reedijk, [email protected]
|
||||
*
|
||||
* Proofreading:
|
||||
* David Weizades <[email protected]>
|
||||
* Thom Holwerda <[email protected]>
|
||||
* David Weizades, [email protected]
|
||||
* Thom Holwerda, [email protected]
|
||||
*
|
||||
* 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.
|
||||
*/
|
||||
|
||||
+299
-253
@@ -3,375 +3,421 @@
|
||||
* Distributed under the terms of the MIT License.
|
||||
*
|
||||
* Authors:
|
||||
* Niels Sascha Reedijk <[email protected]>
|
||||
* Niels Sascha Reedijk, [email protected]
|
||||
*
|
||||
* Proofreading:
|
||||
* David Weizades <[email protected]>
|
||||
* Thom Holwerda <[email protected]>
|
||||
* John Drinkwater <[email protected]>
|
||||
* David Weizades, [email protected]
|
||||
* Thom Holwerda, [email protected]
|
||||
* John Drinkwater, [email protected]
|
||||
*
|
||||
* 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))
|
||||
*/
|
||||
|
||||
|
||||
//! @}
|
||||
|
||||
Reference in New Issue
Block a user