List_t Class Reference

Detailed Description

Simple, plain, generic lists.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

This class implements basic vanilla lists for libSBML. It was developed in the time before libSBML was converted to C++ and used C++ STL library classes more extensively. At some point in the future, this List_t class may be removed in favor of using standard C++ classes.

This class is distinct from ListOf_t because the latter is derived from the SBML SBase_t class, whereas this List_t class is not. ListOf_t can only be used when a list is actually intended to implement an SBML ListOfX class. This is why libSBML has both a List_t and a ListOf_t.

Examples:

printRegisteredPackages.c.

Public Types
typedef int(*	ListItemComparator) (const void *item1, const void *item2)
	A ListItemComparator is a typedef for a pointer to a function that compares two list items. More...
typedef int(*	ListItemPredicate) (const void *item)
	A ListItemPredicate is a typedef for a pointer to a function that takes a List_t item and returns 1 (true) or 0 (false). More...

Public Member Functions
void	List_add (List_t *lst, void *item)
	Adds a pointer to 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)
	Searches the List_t for an entry that matches item1, according to comparator. More...
List_t *	List_findIf (const List_t *lst, ListItemPredicate predicate)
	Create and return a new List_t with the subset of items for which predicate(item) returns true. More...
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)
	The number of elements in lst. More...

Member Typedef Documentation

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

A ListItemComparator 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)

A ListItemPredicate is a typedef for a pointer to a function that takes a List_t item and returns 1 (true) or 0 (false).

See also

List_countIf()

Member Function Documentation

void List_add	(	List_t *	lst,
		void *	item
	)

Adds a pointer to 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 1 represents true and 0 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.

The pointer that is returned by this function is owned by the caller, who is responsible for deleting it.

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

Searches the List_t for an entry that matches item1, according to comparator.

The ListItemComparator is a pointer to a function used to find a matching entry. 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.

Returns

the first occurrence of an entry matching item1 in this List_t or NULL if item was not found.

The pointer that is returned by this function is not owned by the caller, but may be queried and modified.

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

Create and return a new List_t with the subset of items for which predicate(item) returns 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.

Returns

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

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() == 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() returns NULL.

Parameters

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

Examples:

printRegisteredPackages.c.

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() returns NULL.

Parameters

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

Unlike other 'remove' functions in libsbml, the caller does not own the returned item: it continues to be owned by whoever owned it before being put on the List_t. It may be queried or changed by the caller, like other elements of the List_t.

unsigned int List_size

(

const List_t *

lst

)

The number of elements in lst.

Parameters

lst	the List_t structure.

Returns

the number of elements in the given List_t.

Examples:

printRegisteredPackages.c.