List.cpp File Reference

Simple, generic list class. More...

Include dependency graph for List.cpp:

Functions
void	List_add (List_t *lst, void *item)
	Adds item to the end of this List_t. More...
unsigned int	List_countIf (const List_t *lst, ListItemPredicate predicate)
void *	List_find (const List_t *lst, const void *item1, ListItemComparator comparator)
List_t *	List_findIf (const List_t *lst, ListItemPredicate predicate)
void	List_free (List_t *lst)
	Frees the given List_t. More...
void *	List_get (const List_t *lst, unsigned int n)
	Returns the nth item in this List_t. More...
void	List_prepend (List_t *lst, void *item)
	Adds item to the beginning of this List_t. More...
void *	List_remove (List_t *lst, unsigned int n)
	Removes the nth item from this List_t and returns a pointer to it. More...
unsigned int	List_size (const List_t *lst)

Detailed Description

Simple, generic list class.

Author

Ben Bornstein

Function Documentation

void List_add	(	List_t *	lst,
		void *	item
	)

Adds item to the end of this List_t.

Parameters

lst	The List_t structure
item	The item to add to the end of the list

unsigned int List_countIf	(	const List_t *	lst,
		ListItemPredicate	predicate
	)

Returns

the number of items in this List_t for which predicate(item) returns true.

The typedef for ListItemPredicate is:

int (*ListItemPredicate) (const void *item);

where a return value of non-zero represents true and zero represents false.

Parameters

lst	The List_t structure
predicate	The predicate to test the elements of the list against.

void* List_find	(	const List_t *	lst,
		const void *	item1,
		ListItemComparator	comparator
	)

Returns

the first occurrence of item1 in this List_t or NULL if item was not found. ListItemComparator is a pointer to a function used to find item. The typedef for ListItemComparator is:

int (*ListItemComparator) (void *item1, void *item2);

The return value semantics are the same as for strcmp:

-1 item1 < item2, 0 item1 == item 2 1 item1 > item2

Parameters

lst	The List_t structure
item1	The item to look for.
comparator	The pointer to the function used to find the item.

List_t* List_findIf	(	const List_t *	lst,
		ListItemPredicate	predicate
	)

Returns

a new List_t containing (pointers to) all items in this List_t for which predicate(item) was true.

The returned list may be empty.

The caller owns the returned list (but not its constituent items) and is responsible for freeing it with List_free().

Parameters

lst	The List_t structure
predicate	The predicate to test the elements of the list against.

void List_free

(

List_t *

lst

)

Frees the given List_t.

This function does not free List_t items. It frees only the List_t structure and its constituent internal structures (if any).

Presumably, you either i) have pointers to the individual list items elsewhere in your program and you want to keep them around for awhile longer or ii) the list has no items (List_size(lst) == 0). If neither are true, try List_freeItems() instead.

Parameters

lst	The List_t structure

void* List_get	(	const List_t *	lst,
		unsigned int	n
	)

Returns the nth item in this List_t.

If n > List_size(lst) returns NULL.

Parameters

lst	The List_t structure
n	The index of the item to find.

void List_prepend	(	List_t *	lst,
		void *	item
	)

Adds item to the beginning of this List_t.

Parameters

lst	The List_t structure
item	The item to add to the list.

void* List_remove	(	List_t *	lst,
		unsigned int	n
	)

Removes the nth item from this List_t and returns a pointer to it.

If n > List_size(lst) returns NULL.

Parameters

lst	The List_t structure
n	The index of the item to remove.

unsigned int List_size

(

const List_t *

lst

)

Returns

the number of elements in this List_t.

Parameters

lst	The List_t structure