libSBML C++ API  5.18.0
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...
 
ListfindIf (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 ( )

Creates a new List object.

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

void List::add ( void *  item)

Adds item to the end of this List.

Parameters
itema pointer to the item to be added.
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
predicatethe function applied to each item in this list.
Returns
the number of items in this List for which predicate(item) returns 1 (true).
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
item1a pointer to the item being sought.
comparatora 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.
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
predicatethe 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.
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.
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.
void List::prepend ( void *  item)

Adds a given item to the beginning of this List.

Parameters
itema pointer to the item to be added to this list.
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()
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).