Detailed Description

Parent class for libSBML's "ListOfXYZ" classes.

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.

The ListOf_t class in libSBML is a utility class that serves as the parent class for implementing the ListOf__ classes. It provides methods for working generically with the various SBML lists of objects in a program. LibSBML uses this separate list class rather than ordinary C lists, so that it can provide the methods and features associated with SBase_t.

Whether a given ListOf_t element may be empty or not depends on the element in question, and on what level and version of SBML it is being used for. For ListOf_t elements in SBML Level 3 Version 1 and prior, no core list and few package lists could be empty. As of SBML Level 3 Version 2, the rules were relaxed, and lists were allowed to be empty. In libSBML, documents created for Level 3 Version 2 will be written with empty ListOf_t's if that ListOf_t contains some other 'extra' information: an attribute such as metaid or sboTerm, a child '<notes>' or '<annotation>', or information from a SBML Level 3 package.

: The various ListOf___ structures in SBML are merely containers used for organizing the main components of an SBML model. In libSBML's implementation, ListOf___ data structures are derived from the intermediate utility structure ListOf_t, which is not defined by the SBML specifications but serves as a useful programmatic construct. ListOf_t is itself is in turn derived from SBase_t, which provides all of the various ListOf___ data structures with common features defined by the SBML specification, such as "metaid" attributes and annotations.

The relationship between the lists and the rest of an SBML model is illustrated by the following (for SBML Level 2 Version 4):

SBML Level 3 Version 1 has essentially the same structure as Level 2 Version 4, depicted above, but SBML Level 3 Version 2 allows containers to contain zero or more of the relevant object, instead of requiring at least one. As such, libsbml will write out an otherwise-empty ListOf___ element that has any optional attribute set (such as 'id' or 'metaid'), that has an optional child (such as a 'notes' or 'annotation'), or that has attributes or children set from any SBML Level 3 package, whether or not the ListOf___ has any other children.

Readers may wonder about the motivations for using the ListOf___ containers in SBML. A simpler approach in XML might be to place the components all directly at the top level of the model definition. The choice made in SBML is to group them within XML elements named after ListOfClassname, in part because it helps organize the components. More importantly, the fact that the container classes are derived from SBase_t means that software tools can add information about the lists themselves into each list container's "annotation".

See also: ListOfFunctionDefinitions_t; ListOfUnitDefinitions_t; ListOfCompartmentTypes_t; ListOfSpeciesTypes_t; ListOfCompartments_t; ListOfSpecies_t; ListOfParameters_t; ListOfInitialAssignments_t; ListOfRules_t; ListOfConstraints_t; ListOfReactions_t; ListOfEvents_t

Note: In the C API for libSBML, functions that in other language APIs would be inherited by the various ListOf___ structures not shown in the pages for the individual ListOf___'s. Instead, the functions are defined on ListOf_t. Please consult the documentation for ListOf_t for the many common functions available for manipulating ListOf___ structures. The documentation for the individual ListOf___ structures (ListOfCompartments_t, ListOfReactions_t, etc.) does not reveal all of the functionality available.

Public Member Functions
int	ListOf_append (ListOf_t lo, const SBase_t item)
	Adds a copy of a given item to the end of a ListOf_t list. More...

int	ListOf_appendAndOwn (ListOf_t lo, SBase_t disownedItem)
	Adds the given item to the end of a ListOf_t list. More...

int	ListOf_appendFrom (ListOf_t lo, ListOf_t list)
	Adds clones of one list of items to another. More...

void	ListOf_clear (ListOf_t *lo, int doDelete)
	Removes all items in this ListOf_t structure. More...

ListOf_t *	ListOf_clone (const ListOf_t *lo)
	Creates a deep copy of the given ListOf_t structure. More...

ListOf_t *	ListOf_create (unsigned int level, unsigned int version)
	Creates a new instance of a ListOf_t structure. More...

void	ListOf_free (ListOf_t *lo)
	Frees the given ListOf_t structure. More...

SBase_t *	ListOf_get (ListOf_t *lo, unsigned int n)
	Returns the nth item of a given list. More...

int	ListOf_getItemTypeCode (const ListOf_t *lo)
	Get the type code of the objects contained in the given ListOf_t structure. More...

int	ListOf_insert (ListOf_t lo, int location, const SBase_t item)
	Inserts a copy of an item into a ListOf_t list at a given position. More...

int	ListOf_insertAndOwn (ListOf_t lo, int location, SBase_t disownedItem)
	Inserts an item into a ListOf_t list at a given position. More...

SBase_t *	ListOf_remove (ListOf_t *lo, unsigned int n)
	Removes the nth item from this ListOf_t list and returns it. More...

unsigned int	ListOf_size (const ListOf_t *lo)
	Returns the number of items in this ListOf_t items. More...

Member Function Documentation

int ListOf_append	(	ListOf_t *	lo,
		const SBase_t *	item
	)

Adds a copy of a given item to the end of a ListOf_t list.

Parameters

lo	the ListOf_t structure to which the `item` should be appended.
item	the item to append to the list.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

See also: ListOf_appendAndOwn()

int ListOf_appendAndOwn	(	ListOf_t *	lo,
		SBase_t *	disownedItem
	)

Adds the given item to the end of a ListOf_t list.

Parameters

lo	the ListOf_t structure to which the `disownedItem` should be appended.
disownedItem	the item to append to the list. Will become a child of the parent list.

Unlike ListOf_append(), this function does not copy the disownedItem. The given lo list will contain the original item, and becomes responsible for its deletion.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

See also: ListOf_append()

int ListOf_appendFrom	(	ListOf_t *	lo,
		ListOf_t *	list
	)

Adds clones of one list of items to another.

Parameters

lo	the ListOf_t list to which `list` will be appended.
list	the list of items to append to `lo`.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

void ListOf_clear	(	ListOf_t *	lo,
		int	doDelete
	)

Removes all items in this ListOf_t structure.

If doDelete is nonzero (true), all items in this ListOf_t structure are both deleted and cleared, and thus the caller doesn't have to delete those items. Otherwise, if doDelete is 0 (false), all items are only cleared from this ListOf_t structure and the caller is responsible for deleting all items. (In the latter case, callers are advised to store pointers to all items elsewhere before calling this function.)

Parameters

lo	the ListOf_t structure to clear.
doDelete	whether to delete the items.

ListOf_t * ListOf_clone ( const ListOf_t * lo )

Creates a deep copy of the given ListOf_t structure.

Parameters

lo	the ListOf_t structure to be copied.

Returns: a (deep) copy of the given ListOf_t structure, or a null pointer if a failure occurred.

ListOf_t * ListOf_create	(	unsigned int	level,
		unsigned int	version
	)

Creates a new instance of a ListOf_t structure.

Parameters

level	an unsigned int, the SBML Level to assign to this ListOf_t structure.
version	an unsigned int, the SBML Version to assign to this ListOf_t structure.

Returns: a pointer to the newly-created ListOf_t structure.

Note: Bare ListOf_t structures are impossible to add to SBML models. The ListOf_t structure type is simply the base of other structure types in libSBML. Calling programs are not intended to create bare ListOf_t structures themselves.

void ListOf_free ( ListOf_t * lo )

Frees the given ListOf_t structure.

This function assumes each item in the list is derived from SBase_t.

Parameters

lo	the ListOf_t structure to be freed.

SBase_t * ListOf_get	(	ListOf_t *	lo,
		unsigned int	n
	)

Returns the nth item of a given list.

Parameters

lo	the list from which to retrieve the item.
n	the index of the item to retrieve.

Returns: the nth item in this ListOf_t items, or a null pointer if the index number n refers to a nonexistent position in lo.

See also: ListOf_size()

int ListOf_getItemTypeCode ( const ListOf_t * lo )

Get the type code of the objects contained in the given ListOf_t structure.

: LibSBML attaches an identifying code to every kind of SBML object. These are integer constants known as SBML type codes. The names of all the codes begin with the characters SBML_. The set of possible type codes for core elements is defined in the enumeration SBMLTypeCode_t, and in addition, libSBML plug-ins for SBML Level 3 packages define their own extra enumerations of type codes (e.g., SBMLLayoutTypeCode_t for the Level 3 Layout_t package). Note that different Level 3 package plug-ins may use overlapping type codes; to identify the package to which a given object belongs, call the SBase_getPackageName() method on the object.

The exception to this is lists: all SBML-style list elements have the type SBML_LIST_OF, regardless of what package they are from.

Parameters

lo	the ListOf_t whose item type codes are sought.

Returns: the type code corresponding to the objects in lo, or SBML_UNKNOWN.

int ListOf_insert	(	ListOf_t *	lo,
		int	location,
		const SBase_t *	item
	)

Inserts a copy of an item into a ListOf_t list at a given position.

Parameters

lo	the list into which `item` will be inserted.
location	the starting index for the `item` in the `lo` list.
item	the item to append to insert into `lo`.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

int ListOf_insertAndOwn	(	ListOf_t *	lo,
		int	location,
		SBase_t *	disownedItem
	)

Inserts an item into a ListOf_t list at a given position.

Unlike ListOf_insert(), this function does not clone disownedItem before inserting it into lo, which means that lo becomes the owner.

Parameters

lo	the list into which `disownedItem` will be inserted.
location	the starting index for the `disownedItem` in the `lo` list.
disownedItem	the item to append to insert into `lo`. Will become a child of the parent list.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

SBase_t * ListOf_remove	(	ListOf_t *	lo,
		unsigned int	n
	)

Removes the nth item from this ListOf_t list and returns it.

The caller owns the returned item and is responsible for deleting it.

Parameters

lo	the list from which the item should be removed.
n	the index number of the item to remove.

Returns: the item removed, or a null pointer if no item existed at the index n.

unsigned int ListOf_size ( const ListOf_t * lo )

Returns the number of items in this ListOf_t items.

Parameters

lo	the ListOf_t structure to count.

Returns: the number of items in lo.

Detailed Description

Public Member Functions

Member Function Documentation