• 
• 
• 
• 

BList Class Reference
[Support Kit, (libbe.so)]

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

List of all members.

Public Member Functions
	BList (const BList &anotherList)
	Copy constructor. Copy a complete list into this one.
	BList (int32 count=20)
	Create a new list with a number of empty slots.
BList &	operator= (const BList &)
	Copy another list into this object.
virtual	~BList ()
	Destroy the list.
Adding and Removing Items
bool	AddItem (void *item)
	Append an item to the list.
bool	AddItem (void *item, int32 index)
	Add an item at a certain position.
bool	AddList (const BList *list)
	Append a list to this list.
bool	AddList (const BList *list, int32 index)
	Add items from another list to this list at a certain position.
void	MakeEmpty ()
	Clear all the items from the list.
void *	RemoveItem (int32 index)
	Remove the item at index from the list.
bool	RemoveItem (void *item)
	Remove an item from the list.
bool	RemoveItems (int32 index, int32 count)
	Remove a number of items starting at a certain position.
bool	ReplaceItem (int32 index, void *newItem)
	Replace an item with another one.
Querying for Items
int32	CountItems () const
	Get the number of items in the list.
bool	HasItem (void *item) const
	Check if an item is in the list.
int32	IndexOf (void *item) const
	Get the index of an item.
bool	IsEmpty () const
	Check if there are items in the list.
Iterating over the List
void	DoForEach (bool(*func)(void *item, void *arg2), void *arg2)
	Perform an action on every item in the list with an argument.
void	DoForEach (bool(*func)(void *item))
	Perform an action on every item in the list.
Retrieving Items
void *	FirstItem () const
	Get the first item.
void *	ItemAt (int32 index) const
	Get an item.
void *	ItemAtFast (int32) const
	Get an item.
void *	Items () const
	Return the internal list of objects.
void *	LastItem () const
	Get the last item.
Reordering Items
bool	MoveItem (int32 fromIndex, int32 toIndex)
	Move an item to a new place.
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 two items.

---

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.

---

Constructor & Destructor Documentation

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:

count

The size of the blocks allocated in memory.

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.

---

Member Function Documentation

bool BList::AddItem

(

void *

item

)

Append an item to the list.

Parameters:

item

The item to add.

Return values:

	true	The item was appended.
	false	Item was not appended, since resizing the list failed.

See also:

AddItem(void *item, int32 index)

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

Add an item at a certain position.

Parameters:

	item	The item to add.
	index	The place in the list.

Return values:

	true	The item was added.
	false	Item was not added. Either the index is negative or invalid, or resizing the list failed.

See also:

AddItem(void *item)

bool BList::AddList

(

const BList *

list

)

Append a list to this list.

Note that the list parameter is a const, so the original list will not be altered.

Parameters:

list

The list to be appended.

Return values:

	true	The list was appended.
	false	Failed to append the list, due to the fact that resizing of our list failed.

See also:

AddList(const BList *list, int32 index)

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

Add items from another list to this list at a certain position.

Note that the list parameter is const, so the original list will not be altered.

Parameters:

	list	The list to be added.
	index	The position in the current list where the new item(s) should be put.

Return values:

	true	The list was added.
	false	Failed to insert the list, due to the fact that resizing our list failed.

See also:

AddList(const BList *list)

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:

	func	A 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.
	arg2	An argument to supply to func.

See also:

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

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:

func

A function that takes a void * argument and returns a boolean.

See also:

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

void * BList::FirstItem

(

)

const

Get the first item.

Returns:

A pointer to the first item or NULL if the list is empty.

See also:

LastItem() const

int32 BList::IndexOf

(

void *

item

)

const

Get the index of an item.

Returns:

The index of the item, or -1 when the item is not in the list.

void * BList::ItemAt

(

int32

index

)

const

Get an item.

Parameters:

index

The 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

void * BList::ItemAtFast

(

int32

index

)

const

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.

Returns:

A pointer to the 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.

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.

Returns:

The internal list of pointers.

void * BList::LastItem

(

)

const

Get the last item.

Returns:

A pointer to the last item or NULL if the list is empty.

See also:

FirstItem() const

void BList::MakeEmpty

(

)

Clear all the items from the list.

Please note that this does not free the items.

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

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:

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:

	fromIndex	The original location.
	toIndex	The new location.

Return values:

	true	Move succeeded.
	false	Move failed due to the indexes being invalid.

void * BList::RemoveItem

(

int32

index

)

Remove the item at index from the list.

Parameters:

index

The item that should be removed.

Returns:

The pointer to the item that was removed, or NULL in case the index was invalid.

See also:

RemoveItem(void *item)

bool BList::RemoveItem

(

void *

item

)

Remove an item from the list.

Parameters:

item

The item that should be removed.

Return values:

	true	The item was found and removed.
	false	The item was not in this list and thus not removed.

See also:

RemoveItem(int32 index)

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:

	index	The offset in the list where removal should start.
	count	The number of items to remove.

Return values:

	true	Removal succeeded.
	false	Failed to remove the items because the index was invalid.

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

Replace an item with another one.

Parameters:

	index	The offset in the list where to put the item.
	newItem	The new item to put in the list.

Return values:

	true	Item 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.

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

Swap two items.

Parameters:

	indexA	The first item.
	indexB	The second item.

Return values:

	true	Swap succeeded.
	false	Swap failed because one of the indexes was invalid.

---

The Haiku Book pre-R1 - BList Class Reference
Generated on 14 Feb 2008