List 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 class may be removed in favor of using standard C++ classes.

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

Examples

getAllElementsWithNotes.cpp, printSupported.cpp, renameSId.cpp, setIdFromNames.cpp, and setNamesFromIds.cpp.

Public Member Functions
void	add (void *item)
	Adds item to the end of this List. More...
unsigned int	countIf (ListItemPredicate predicate) const
	Return the count of items in this list satisfying a given predicate function. More...
void *	find (const void *item1, ListItemComparator comparator) const
	Find the first occurrence of an item in a list according to a given comparator function. More...
List *	findIf (ListItemPredicate predicate) const
	Find all items in this list satisfying a given predicate function. More...
void *	get (unsigned int n) const
	Get the nth item in this List. More...
unsigned int	getSize () const
	Get the number of items in this List. More...
	List ()
	Creates a new List object. More...
void	prepend (void *item)
	Adds a given item to the beginning of this List. More...
void *	remove (unsigned int n)
	Removes the nth item from this List and returns a pointer to it. More...
void	transferFrom (List *list)
	Merge this elements of the second list into this list (by pointing the last ListNode to the first ListNode in the supplied List). More...
virtual	~List ()
	Destroys this List object. More...

Constructor & Destructor Documentation

List()

List::List

(

)

Creates a new List object.

~List()

List::~List ( )

virtual

Destroys this List object.

This function does not delete List items. It destroys only the List and its constituent ListNodes (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 the macro List_freeItems() instead.

Member Function Documentation

add()

void List::add

(

void *

item

)

Adds item to the end of this List.

Parameters

item	a pointer to the item to be added.

countIf()

unsigned int List::countIf

(

ListItemPredicate

predicate

)

const

Return the count of items in this list satisfying a given predicate function.

The typedef for ListItemPredicate is:

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

where a return value of 1 represents true and 0 represents false.

Parameters

predicate

the function applied to each item in this list.

Returns

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

find()

void * List::find	(	const void *	item1,
		ListItemComparator	comparator
	)		const

Find the first occurrence of an item in a list according to a given comparator function.

The typedef for ListItemComparator is:

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

The return value semantics are the same as for the C library function strcmp:

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

Parameters

item1	a pointer to the item being sought.
comparator	a pointer to a ListItemComparator function used to find the item of interest in this list.

Returns

the first occurrence of item1 in this List or NULL if item1 was not found.

findIf()

List * List::findIf

(

ListItemPredicate

predicate

)

const

Find all items in this list satisfying a given predicate function.

The typedef for ListItemPredicate is:

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

where a return value of 1 represents true and 0 represents false.

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

Parameters

predicate

the function applied to each item in this list.

Returns

a new List containing (pointers to) all items in this List for which predicate(item) returned nonzero (true). The returned list may be empty if none of the items satisfy the predicate.

get()

void * List::get

(

unsigned int

n

)

const

Get the nth item in this List.

If n > List.size(), this method returns 0.

Returns

the nth item in this List. If the index n is invalid, NULL is returned.

See also

remove()

Examples

printSupported.cpp, renameSId.cpp, and setIdFromNames.cpp.

getSize()

unsigned int List::getSize

(

)

const

Get the number of items in this List.

Returns

the number of elements in this List.

Examples

getAllElementsWithNotes.cpp, printSupported.cpp, renameSId.cpp, and setIdFromNames.cpp.

prepend()

void List::prepend

(

void *

item

)

Adds a given item to the beginning of this List.

Parameters

item	a pointer to the item to be added to this list.

remove()

void * List::remove

(

unsigned int

n

)

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

If n > List.size(), this method returns 0.

Returns

the nth item in this List. If the index n is invalid, NULL is returned.

See also

get()

transferFrom()

void List::transferFrom

(

List *

list

)

Merge this elements of the second list into this list (by pointing the last ListNode to the first ListNode in the supplied List).