Public Member Functions | List of all members
BList Class Reference

An ordered container that is designed to hold generic void* objects. More...

Inherited by _PointerList_.

Public Member Functions

 BList (int32 count=20)
 Create a new list with a number of empty slots. More...
 
 BList (const BList &other)
 Copy constructor. Copy a complete list into this one. More...
 
virtual ~BList ()
 Destroy the list. More...
 
Operators
BListoperator= (const BList &other)
 Copy another list into this object. More...
 
bool operator== (const BList &other) const
 Returns whether or not the BList and other are equal. More...
 
bool operator!= (const BList &other) const
 Returns whether or not the BList and other are NOT equal. More...
 
Adding and Removing Items
bool AddItem (void *item, int32 index)
 Add item at the specified index. More...
 
bool AddItem (void *item)
 Append the item to the end of the list. More...
 
bool AddList (const BList *list, int32 index)
 Add a list of items to this list at the specified index. More...
 
bool AddList (const BList *list)
 Append a list of items to this list. More...
 
bool RemoveItem (void *item)
 Remove item from the list. More...
 
void * RemoveItem (int32 index)
 Remove the item at index from the list. More...
 
bool RemoveItems (int32 index, int32 count)
 Remove a number of items starting at a certain position. More...
 
bool ReplaceItem (int32 index, void *item)
 Replace an item with another one. More...
 
void MakeEmpty ()
 Clear all the items from the list. More...
 
Reordering Items
void SortItems (int(*compareFunc)(const void *, const void *))
 Sort the items with the use of a supplied comparison function. More...
 
bool SwapItems (int32 indexA, int32 indexB)
 Swap the items at indexA and indexB. More...
 
bool MoveItem (int32 from, int32 to)
 Move the item at fromIndex to the position of toIndex. More...
 
Retrieving Items
void * ItemAt (int32 index) const
 Return a pointer to the item at the given index. More...
 
void * FirstItem () const
 Return a pointer to the first item in the list. More...
 
void * ItemAtFast (int32 index) const
 Return a pointer to the item at index. More...
 
void * LastItem () const
 Return a pointer to the last item in the list. More...
 
void * Items () const
 Return the internal list of objects. More...
 
Querying Items
bool HasItem (void *item) const
 Return whether or not item is in the list. More...
 
int32 IndexOf (void *item) const
 Return the index of item. More...
 
int32 CountItems () const
 Returns the number of items in the list. More...
 
bool IsEmpty () const
 Return whether or not there are items in the list. More...
 
Iterating Over Items
void DoForEach (bool(*func)(void *item))
 Perform an action on every item in the list. More...
 
void DoForEach (bool(*func)(void *item, void *arg2), void *arg2)
 Perform an action on every item in the list with an argument. More...
 

Detailed Description

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.

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.

See also
BObjectList for a templated version of BList that adds type safety, optional object ownership, search, and insert operations.
Since
BeOS R3

Constructor & Destructor Documentation

◆ BList() [1/2]

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.

Parameters
countThe size of the blocks allocated in memory.
Since
BeOS R3

◆ BList() [2/2]

BList::BList ( const BList other)

Copy constructor. Copy a complete list into this one.

Parameters
otherThe list to copy from.
Since
BeOS R3

◆ ~BList()

BList::~BList ( )
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.

Since
BeOS R3

Member Function Documentation

◆ AddItem() [1/2]

bool BList::AddItem ( void *  item,
int32  index 
)

Add item at the specified index.

Parameters
itemThe item to add.
indexThe place in the list to add the item.
Returns
Whether or not the item was added.
Return values
trueThe item was added.
falseItem was not added. Either the index is negative or invalid, or resizing the list failed.
See also
AddItem(void*)
Since
BeOS R3

Referenced by BObjectList< BBitmap >::AddItem().

◆ AddItem() [2/2]

bool BList::AddItem ( void *  item)

Append the item to the end of the list.

Parameters
itemThe item to append.
Returns
Whether or not the item was appended.
Return values
trueThe item was appended.
falseitem was not appended, since resizing the BList failed.
See also
AddItem(void*, int32)
Since
BeOS R3

◆ AddList() [1/2]

bool BList::AddList ( const BList list,
int32  index 
)

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.

Parameters
listThe list to be added.
indexThe position in the current list where the new item(s) are added.
Returns
Whether or not the list was added.
Return values
trueThe list was added.
falseFailed to insert the list resizing failed.
See also
AddList(const BList*)
Since
BeOS R3

Referenced by BObjectList< BBitmap >::AddList().

◆ AddList() [2/2]

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.

Parameters
listThe list to be added.
Returns
Whether or not the list was added.
Return values
trueThe list was appended.
falseFailed to append the list, resizing failed.
See also
AddList(const BList*, int32)
Since
BeOS R3

◆ CountItems()

int32 BList::CountItems ( ) const

Returns the number of items in the list.

Returns
The number of items in the list as an int32.
Since
BeOS R3

Referenced by BObjectList< BBitmap >::CountItems().

◆ DoForEach() [1/2]

void BList::DoForEach ( bool(*)(void *item)  func)

Perform an action on every item in the list.

If one of the actions on the items fails it means that the func function returned false and the processing of the list will be stopped.

Parameters
funcA pointer to a function that takes a void* argument and returns a bool.
See also
DoForEach(bool (*func)(void*, void*), void*)
Since
BeOS R3

◆ DoForEach() [2/2]

void BList::DoForEach ( bool(*)(void *item, void *arg2)  func,
void *  arg2 
)

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 func function returned false and the processing of the list will be stopped.

Parameters
funcA function with the first void* argument being the item and the second void* being the argument that you supply. It should return a boolean value on whether it succeeded or not.
arg2An argument to supply to func.
See also
DoForEach(bool (*func)(void*))
Since
BeOS R3

◆ FirstItem()

void * BList::FirstItem ( ) const

Return a pointer to the first item in the list.

Returns
A pointer to the first item or NULL if the list is empty.
See also
LastItem() const
Since
BeOS R3

Referenced by BObjectList< BBitmap >::FirstItem().

◆ HasItem()

bool BList::HasItem ( void *  item) const

Return whether or not item is in the list.

Returns
true if the item was in the list, false otherwise.
Since
BeOS R3

Referenced by BObjectList< BBitmap >::HasItem().

◆ IndexOf()

int32 BList::IndexOf ( void *  item) const

Return the index of item.

Returns
The index of the item, or -1 when the item is not in the list.
Since
BeOS R3

Referenced by BObjectList< BBitmap >::IndexOf().

◆ IsEmpty()

bool BList::IsEmpty ( ) const

Return whether or not there are items in the list.

Returns
true if the list was empty, false otherwise.
Since
BeOS R3

Referenced by BObjectList< BBitmap >::IsEmpty().

◆ ItemAt()

void * BList::ItemAt ( int32  index) const

Return a pointer to the item at the given index.

Parameters
indexThe item to retrieve.
Returns
A pointer to the item in that position, or NULL if the index is out of bounds.
See also
ItemAtFast(int32 index) const
Since
BeOS R3

Referenced by BObjectList< BBitmap >::ItemAt().

◆ ItemAtFast()

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.

Returns
A pointer to the item.
Since
Haiku R1

◆ Items()

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.

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.
Returns
The internal list of pointers.
See also
DoForEach() for an alternate method.
Since
BeOS R3

◆ LastItem()

void * BList::LastItem ( ) const

Return a pointer to the last item in the list.

Returns
A pointer to the last item or NULL if the list is empty.
See also
FirstItem() const
Since
BeOS R3

Referenced by BObjectList< BBitmap >::LastItem().

◆ MakeEmpty()

void BList::MakeEmpty ( )

Clear all the items from the list.

Note
This does not free the items.
Since
BeOS R3

Referenced by BObjectList< BBitmap >::MakeEmpty(), and BObjectList< BBitmap >::~BObjectList().

◆ MoveItem()

bool BList::MoveItem ( int32  fromIndex,
int32  toIndex 
)

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
Parameters
fromIndexThe original location.
toIndexThe new location.
Returns
Whether or not the items were moved.
Return values
trueMove succeeded.
falseMove failed due to the indexes being invalid.
Since
Haiku R1

◆ operator!=()

bool BList::operator!= ( const BList other) const

Returns whether or not the BList and other are NOT equal.

Returns
true if the lists are NOT equal, false if they are equal.
Since
Haiku R1

◆ operator=()

BList & BList::operator= ( const BList other)

Copy another list into this object.

Since
BeOS R3

◆ operator==()

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.

Returns
true if the lists are equal, false if they are NOT equal.
Since
Haiku R1

◆ RemoveItem() [1/2]

bool BList::RemoveItem ( void *  item)

Remove item from the list.

Parameters
itemThe item to be removed.
Returns
Whether or not the item was removed.
Return values
trueThe item was found and removed.
falseThe item was not in this list and thus not removed.
See also
RemoveItem(int32)
Since
BeOS R3

Referenced by BObjectList< BBitmap >::RemoveItem(), and BObjectList< BBitmap >::RemoveItemAt().

◆ RemoveItem() [2/2]

void * BList::RemoveItem ( int32  index)

Remove the item at index from the list.

Parameters
indexThe index of the item to be removed.
Returns
The pointer to the item that was removed, or NULL if the index was invalid.
See also
RemoveItem(void*)
Since
BeOS R3

◆ RemoveItems()

bool BList::RemoveItems ( int32  index,
int32  count 
)

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.

Parameters
indexThe offset in the list where removal should start.
countThe number of items to remove.
Returns
Whether or not the items were removed.
Return values
trueRemoval succeeded.
falseFailed to remove the items because the index was invalid.
Since
BeOS R3

◆ ReplaceItem()

bool BList::ReplaceItem ( int32  index,
void *  item 
)

Replace an item with another one.

Parameters
indexThe offset in the list where to put the item.
itemThe new item to put in the list.
Returns
Whether or not the item was replaced.
Return values
trueThe item was replaced.
falseThe index was invalid.
Since
Haiku R1

◆ SortItems()

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.

Since
BeOS R3

Referenced by BObjectList< BBitmap >::SortItems().

◆ SwapItems()

bool BList::SwapItems ( int32  indexA,
int32  indexB 
)

Swap the items at indexA and indexB.

Parameters
indexAThe first item.
indexBThe second item.
Returns
Whether or not the items were swapped.
Return values
trueSwap succeeded.
falseSwap failed because one of the indexes was invalid.
Since
Haiku R1