BList Class Reference

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 count=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.

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

count

The 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

other

The 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

)

Append the item to the end of the list.

Parameters

item	The item to append.

Returns

Whether or not the item was appended.

Return values

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

See also

AddItem(void*, int32)

Since

BeOS R3

AddItem() [2/2]

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

Add item at the specified index.

Parameters

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

Returns

Whether or not the item was added.

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*)

Since

BeOS R3

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

AddList() [1/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

list	The list to be added.

Returns

Whether or not the list was added.

Return values

true	The list was appended.
false	Failed to append the list, resizing failed.

See also

AddList(const BList*, int32)

Since

BeOS R3

AddList() [2/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

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

Returns

Whether or not the list was added.

Return values

true	The list was added.
false	Failed to insert the list resizing failed.

See also

AddList(const BList*)

Since

BeOS R3

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

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< T >::CountItems().

DoForEach() [1/2]

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.

Parameters

func	A pointer to a function that takes a void* list item, and returns a bool indicating if the iteration should stop.

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.

The iteration stops when the func function returns true. This can be used to implement a linear search of the list, for example:

bool compareFunc(void* _item, void* arg2) {
    Item* item = (Item*)_item;
    Args* args = (Args*)arg2;
    if (item->Matches(args->pattern)) {
        args->result = item;
        return true;
    }
    return false;
}
 
Args args = {0};
list.DoForEach(compareFunc, &args);
if (args->result != NULL) {
    // Found it!
}

Parameters

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.

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< T >::FirstItem().

HasItem() [1/2]

bool BList::HasItem

(

const void *

item

)

const

Return whether or not item is in the list.

Returns

true if the item was in the list, false otherwise.

Since

Haiku R1

HasItem() [2/2]

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< T >::HasItem().

IndexOf() [1/2]

int32 BList::IndexOf

(

const 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

Haiku R1

IndexOf() [2/2]

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< T >::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< T >::IsEmpty().

ItemAt()

void * BList::ItemAt

(

int32

index

)

const

Return a pointer to the item at the given index.

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

Since

BeOS R3

Referenced by BObjectList< T >::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< T >::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< T >::MakeEmpty().

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

fromIndex	The original location.
toIndex	The new location.

Returns

Whether or not the items were moved.

Return values

true	Move succeeded.
false	Move 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]

void * BList::RemoveItem

(

int32

index

)

Remove the item at index from the list.

Parameters

index

The 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

RemoveItem() [2/2]

bool BList::RemoveItem

(

void *

item

)

Remove item from the list.

Parameters

item	The item to be removed.

Returns

Whether or not the item was 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)

Since

BeOS R3

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

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

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

Returns

Whether or not the items were removed.

Return values

true	Removal succeeded.
false	Failed 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

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

Returns

Whether or not the item was replaced.

Return values

true	The item was replaced.
false	The 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< T >::SortItems().

SwapItems()

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

Swap the items at indexA and indexB.

Parameters

indexA	The first item.
indexB	The second item.

Returns

Whether or not the items were swapped.

Return values

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

Since

Haiku R1