List.h File Reference

Simple, generic list utility class. More...

Include dependency graph for List.h:

This graph shows which files directly or indirectly include this file:

Macros
#define	List_freeItems(list, free_item, type)
	Frees the items in the given List. More...

Typedefs
typedef void(*	ListDeleteItemFunc )(void *item)
	ListDeleteItemFunc. More...
typedef int(*	ListItemComparator )(const void *item1, const void *item2)
	ListItemComparator. More...
typedef int(*	ListItemPredicate )(const void *item)
	ListItemPredicate. More...

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)
List_t *	List_create (void)
	Creates a new List_t and returns a pointer to it. More...
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 utility class.

Author

Ben Bornstein

Macro Definition Documentation

#define List_freeItems	(		list,
			free_item,
			type
	)

Value:

{                                                            \
  unsigned int size = List_size(list);                       \
  while (size--) free_item( (type *) List_remove(list, 0) ); \
}

Frees the items in the given List.

Iterates over the items in this List and frees each one in turn by calling the passed-in 'void free_item(type *)' function.

The List itself will not be freed and so may be re-used. To free the List, use the destructor.

While the function prototype cannot be expressed precisely in C syntax, it is roughly:

List_freeItems(List_t *lst, void (*free_item)(type *), type)

where type is a C type resolved at compile time.

Believe it or not, defining List_freeItems() as a macro is actually more type safe than can be acheived with straight C. That is, in C, the free_item() function would need to take a void pointer argument, requiring any type safe XXX_free() functions to be re-written to be less safe.

As with all line-continuation macros, compile-time errors will still report the correct line number.

Typedef Documentation

typedef void(* ListDeleteItemFunc)(void *item)

ListDeleteItemFunc.

This is a typedef for a pointer to a function that takes a List item and deletes / frees it as apropriate.

typedef int(* ListItemComparator)(const void *item1, const void *item2)

ListItemComparator.

This is a typedef for a pointer to a function that compares two list items. The return value semantics are the same as for the C library function strcmp:

• -1: item1 < item2
• 0: item1 == item2
• 1: item1 > item2

See also

List_find()

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

ListItemPredicate.

This is a typedef for a pointer to a function that takes a List item and returns nonzero (for true) or zero (for false).

See also

List_countIf()

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.

List_t* List_create

(

void

)

Creates a new List_t and returns a pointer to it.

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