Derived from: public BObject
Declared in: <support/List.h>
A BList object is a compact, ordered list of data pointers. BList objects can contain pointers to any type of data, including--and especially--objects.
Items in a BList are identified by their ordinal position, or index, starting with index 0. Indices are neither arbitrary nor permanent. If, for example, you insert an item into the middle of a list, the indices of the items at the tail of the list are incremented (by one). Similarly, removing an item decrements the indices of the following items.
A BList stores its items as type void *, so it's necessary to cast an item to the correct type when you retrieve it. For example, items retrieved from a list of BBitmap objects must be cast as BBitmap pointers:
BBitmap *theImage = (BBitmap *)myList->ItemAt(anIndex);
Note
: There's nothing to prevent you from adding a NULL pointer to a BList. However, functions that retrieve items from the list (such as ItemAt()) return NULL when the requested item can't be found. Thus, you can't distinguish between a valid NULL item and an invalid attempt to access an item that isn't there.
BList(long blockSize = 20) BList(const BList& anotherList)
Initializes the BList by allocating enough memory to hold blockSize items. As the list grows and shrinks, additional memory is allocated and freed in blocks of the same size.
The copy constructor creates an independent list of data pointers, but it doesn't copy the pointed-to data. For example:
BList *newList = new BList(oldList);
Here, the contents of oldList and newList--the actual data pointers --are separate and independent. Adding, removing, or reordering items in oldList won't affect the number or order of items in newList. But if you modify the data that an item in oldList points to, the modification will be seen through the analogous item in newList.
The block size of a BList that's created through the copy constructor is the same as that of the original BList.
virtual ~BList(void)
Frees the list of data pointers, but doesn't free the data that they point to. To destroy the data, you need to free each item in an appropriate manner. For example, objects that were allocated with the new operator should be freed with delete:
void *anItem; for ( long i = 0; anItem = myList->ItemAt(i); i++ ) delete anItem; delete myList;
See also: MakeEmpty()
bool AddItem(void *item, long index) inline bool AddItem(void *item)
Adds an item to the BList at index--or, if no index is supplied, at the end of the list. If necessary, additional memory is allocated to accommodate the new item.
Adding an item never removes an item already in the list. If the item is added at an index that's already occupied, items currently in the list are bumped down one slot to make room.
If index is out-of-range (greater than the current item count, or less than zero), the function fails and returns FALSE. Otherwise it returns TRUE.
bool AddList(BList *list, long index) bool AddList(BList *list)
Adds the contents of another BList to this BList. The items from the other BList are inserted at index--or, if no index is given, they're appended to the end of the list. If the index is out-of-range, the function fails and returns FALSE. If successful, it returns TRUE.
See also: AddItem()
inline long CountItems(void) const
Returns the number of items currently in the list.
void DoForEach(bool (*func)(void *)) void DoForEach(bool (*func)(void *, void *), void *arg2)
Calls the func function once for each item in the BList. Items are visited in order, beginning with the first one in the list (index 0) and ending with the last. If a call to func returns TRUE, the iteration is stopped, even if some items have not yet been visited.
func must be a function that takes one or two arguments. The first argument is the currently-considered item from the list; the second argument, if func requires one, is passed to DoForEach() as arg2.
inline void *FirstItem(void) const
Returns the first item in the list, or NULL if the list is empty. This function doesn't remove the item from the list.
See also: LastItem(), ItemAt()
inline bool HasItem(void *item) const
Returns TRUE if item is in the list, and FALSE if not.
long IndexOf(void *item) const
Returns the ordinal position of item in the list, or B_ERROR if item isn't in the list. If the item is in the list more than once, the index returned will be the position of its first occurrence.
inline bool IsEmpty(void) const
Returns TRUE if the list is empty (if it contains no items), and FALSE otherwise.
See also: MakeEmpty()
inline void *ItemAt(long index) const
Returns the item at index, or NULL if the index is out-of-range. This function doesn't remove the item from the list.
See also: Items(), FirstItem(), LastItem()
inline void *Items(void) const
Returns a pointer to the BList's list. You can index directly into the list if you're certain that the index is in-range:
myType item = (myType)Items()[index];
Although the practice is discouraged, you can also step through the list of items by incrementing the list pointer that's returned by Items(). Be aware that the list isn't null- terminated--you have to detect the end of the list by some other means. The simplest method is to count items:
void *ptr = myList->Items(); for ( long i = myList->ItemCount(); i > 0; i-- ) { . . . *ptr++; }
You should never use the list pointer to change the number of items in the list.
See also: DoForEach(), SortItems()
inline void *LastItem(void) const
Returns the last item in the list without removing it. If the list is empty, this function returns NULL .
See also: RemoveLastItem(), FirstItem()
void MakeEmpty(void)
Empties the BList of all its items, without freeing the data that they point to.
See also: IsEmpty(), RemoveItem()
bool RemoveItem(void *item) void *RemoveItem(long index)
Removes an item from the list. If passed an item, the function looks for the item in the list, removes it, and returns TRUE. If it can't find the item, it returns FALSE. If the item is in the list more than once, this function removes only its first occurrence.
If passed an index, the function removes the item at that index and returns it. If there's no item at the index, it returns NULL.
The list is compacted after an item is removed. Because of this, you mustn't try to empty a list (or a range within a list) by removing items at monotonically increasing indices. You should either start with the highest index and move towards the head of the list, or remove at the same index (the lowest in the range) some number of times. As an example of the latter, the following code removes the first five items in the list:
for ( long i = 0; i <= 4; i++ ) myList->RemoveItem(0);
See also: MakeEmpty()
void *SortItems(int (*compareFunc)(const void *, const void *))
Rearranges the items in the list. The items are sorted using the compareFunc comparison function passed as an argument. This function should take two items as arguments. It should return a negative number if the first item should be ordered before the second, a positive number if the second should be ordered before the first, and 0 if the two items should be ordered equivalently.
See also: Items()
BList& operator =(const BList&)
Copies the contents of one BList object into another:
BList newList = oldList;
After the assignment, each object has its own independent copy of list data; destroying one of the objects won't affect the other.
Only the items in the list are copied, not the data they point to.
The Be Book, HTML Edition, for Developer Release 8 of the Be Operating System.
Copyright © 1996 Be, Inc. All rights reserved.
Be, the Be logo, BeBox, BeOS, BeWare, and GeekPort are trademarks of Be, Inc.
Last modified September 6, 1996.