An ordered container that is designed to hold generic void*
objects.
More...
Inherited by _PointerList_.
Public Member Functions | |
BList (const BList &other) | |
Copy constructor. Copy a complete list into this one. | |
BList (int32 blockSize=20) | |
Create a new list with a number of empty slots. | |
virtual | ~BList () |
Destroy the list. | |
Operators | |
BList & | operator= (const BList &other) |
Copy another list into this object. | |
bool | operator== (const BList &other) const |
Returns whether or not the BList and other are equal. | |
bool | operator!= (const BList &other) const |
Returns whether or not the BList and other are NOT equal. | |
Adding and Removing Items | |
bool | AddItem (void *item, int32 index) |
Add item at the specified index. | |
bool | AddItem (void *item) |
Append the item to the end of the list. | |
bool | AddList (const BList *list, int32 index) |
Add a list of items to this list at the specified index. | |
bool | AddList (const BList *list) |
Append a list of items to this list. | |
bool | RemoveItem (void *item) |
Remove item from the list. | |
void * | RemoveItem (int32 index) |
Remove the item at index from the list. | |
bool | RemoveItems (int32 index, int32 count) |
Remove a number of items starting at a certain position. | |
bool | ReplaceItem (int32 index, void *item) |
Replace an item with another one. | |
void | MakeEmpty () |
Clear all the items from the list. | |
Reordering Items | |
void | SortItems (int(*compareFunc)(const void *, const void *)) |
Sort the items with the use of a supplied comparison function. | |
bool | SwapItems (int32 indexA, int32 indexB) |
Swap the items at indexA and indexB. | |
bool | MoveItem (int32 from, int32 to) |
Move the item at fromIndex to the position of toIndex. | |
Retrieving Items | |
void * | ItemAt (int32 index) const |
Return a pointer to the item at the given index. | |
void * | FirstItem () const |
Return a pointer to the first item in the list. | |
void * | ItemAtFast (int32 index) const |
Return a pointer to the item at index. | |
void * | LastItem () const |
Return a pointer to the last item in the list. | |
void * | Items () const |
Return the internal list of objects. | |
Querying Items | |
bool | HasItem (void *item) const |
Return whether or not item is in the list. | |
bool | HasItem (const void *item) const |
Return whether or not item is in the list. | |
int32 | IndexOf (void *item) const |
Return the index of item. | |
int32 | IndexOf (const void *item) const |
Return the index of item. | |
int32 | CountItems () const |
Returns the number of items in the list. | |
bool | IsEmpty () const |
Return whether or not there are items in the list. | |
Iterating Over Items | |
void | DoForEach (bool(*func)(void *item)) |
Perform an action on every item in the list. | |
void | DoForEach (bool(*func)(void *item, void *arg2), void *arg2) |
Perform an action on every item in the list with an argument. | |
An ordered container that is designed to hold generic 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.
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.
BList::BList | ( | int32 | count = 20 | ) |
Create a new list with a number of empty slots.
The memory management of this class allocates new memory per block. The 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.
count | The size of the blocks allocated in memory. |
BList::BList | ( | const BList & | other | ) |
Copy constructor. Copy a complete list into this one.
other | The list to copy from. |
|
virtual |
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.
bool BList::AddItem | ( | void * | item | ) |
Append the item to the end of the list.
item | The item to append. |
true | The item was appended. |
false | item was not appended, since resizing the BList failed. |
bool BList::AddItem | ( | void * | item, |
int32 | index | ||
) |
Add item at the specified index.
item | The item to add. |
index | The place in the list to add the item. |
true | The item was added. |
false | Item was not added. Either the index is negative or invalid, or resizing the list failed. |
Referenced by BObjectList< T >::AddItem().
bool BList::AddList | ( | const BList * | list | ) |
Append a list of items to this list.
Note that the list parameter is a const
, so the original list will not be altered.
list | The list to be added. |
true | The list was appended. |
false | Failed to append the list, resizing failed. |
Add a list of items to this list at the specified index.
Note that the list parameter is const
, so the original list will not be altered.
list | The list to be added. |
index | The position in the current list where the new item(s) are added. |
true | The list was added. |
false | Failed to insert the list resizing failed. |
Referenced by BObjectList< T >::AddList().
int32 BList::CountItems | ( | ) | const |
Returns the number of items in the list.
Referenced by BObjectList< T >::CountItems().
void BList::DoForEach | ( | bool(*)(void *item) | func | ) |
Perform an action on every item in the list.
Iterates over all items in the list, and calls the func function on each of them, until the function returns true
.
func | A pointer to a function that takes a void* list item, and returns a bool indicating if the iteration should stop. |
void BList::DoForEach | ( | bool(*)(void *item, void *arg2) | func, |
void * | arg2 | ||
) |
Perform an action on every item in the list with an argument.
The iteration stops when the func function returns true
. This can be used to implement a linear search of the list, for example:
func | A function with the first void* argument being the item and the second void* being the argument that you supply. |
arg2 | An argument to supply to func. |
void * BList::FirstItem | ( | ) | const |
Return a pointer to the first item in the list.
NULL
if the list is empty.Referenced by BObjectList< T >::FirstItem().
bool BList::HasItem | ( | const void * | item | ) | const |
Return whether or not item is in the list.
true
if the item was in the list, false
otherwise.bool BList::HasItem | ( | void * | item | ) | const |
Return whether or not item is in the list.
true
if the item was in the list, false
otherwise.Referenced by BObjectList< T >::HasItem().
int32 BList::IndexOf | ( | const void * | item | ) | const |
Return the index of item.
int32 BList::IndexOf | ( | void * | item | ) | const |
Return the index of item.
Referenced by BObjectList< T >::IndexOf().
bool BList::IsEmpty | ( | ) | const |
Return whether or not there are items in the list.
true
if the list was empty, false
otherwise.Referenced by BObjectList< T >::IsEmpty().
void * BList::ItemAt | ( | int32 | index | ) | const |
Return a pointer to the item at the given index.
index | The item to retrieve. |
NULL
if the index is out of bounds.Referenced by BObjectList< T >::ItemAt().
void * BList::ItemAtFast | ( | int32 | index | ) | const |
Return a pointer to the item at index.
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.
void * BList::Items | ( | ) | const |
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.
void * BList::LastItem | ( | ) | const |
Return a pointer to the last item in the list.
NULL
if the list is empty.Referenced by BObjectList< T >::LastItem().
void BList::MakeEmpty | ( | ) |
Clear all the items from the list.
Referenced by BObjectList< T >::MakeEmpty().
Move the item at fromIndex to the position of toIndex.
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:
A B C D E F G H I J
Moving 1(B)->6(G) would result in this:
A C D E F G B H I J
fromIndex | The original location. |
toIndex | The new location. |
true | Move succeeded. |
false | Move failed due to the indexes being invalid. |
bool BList::operator!= | ( | const BList & | other | ) | const |
Returns whether or not the BList and other are NOT equal.
true
if the lists are NOT equal, false
if they are equal.bool BList::operator== | ( | const BList & | other | ) | const |
Returns whether or not the BList and other are equal.
Equal means that they are the same object or their contents are the same.
true
if the lists are equal, false
if they are NOT equal.void * BList::RemoveItem | ( | int32 | index | ) |
Remove the item at index from the list.
index | The index of the item to be removed. |
NULL
if the index was invalid.bool BList::RemoveItem | ( | void * | item | ) |
Remove item from the list.
item | The item to be removed. |
true | The item was found and removed. |
false | The item was not in this list and thus not removed. |
Referenced by BObjectList< T >::RemoveItem(), and BObjectList< T >::RemoveItemAt().
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.
index | The offset in the list where removal should start. |
count | The number of items to remove. |
true | Removal succeeded. |
false | Failed to remove the items because the index was invalid. |
bool BList::ReplaceItem | ( | int32 | index, |
void * | item | ||
) |
Replace an item with another one.
index | The offset in the list where to put the item. |
item | The new item to put in the list. |
true | The item was replaced. |
false | The index was invalid. |
void BList::SortItems | ( | int(*)(const void *, const void *) | compareFunc | ) |
Sort the items with the use of a supplied comparison function.
The function should take two const
pointers as arguments and should return an integer.
For an example, see the Compare(const BString *, const BString *) function.
Referenced by BObjectList< T >::SortItems().