libSBML C API  libSBML 5.8.0 C API
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
SBMLReader.h File Reference

Detailed Description

Reads an SBML Document into memory.

Author
Ben Bornstein
Include dependency graph for SBMLReader.h:
This graph shows which files directly or indirectly include this file:

Functions

SBMLDocument_t * readSBML (const char *filename)
 Reads an SBML document from the given file filename. More...
 
SBMLDocument_t * readSBMLFromFile (const char *filename)
 
SBMLDocument_t * readSBMLFromString (const char *xml)
 Reads an SBML document from a string assumed to be in XML format. More...
 
SBMLReader_t * SBMLReader_create (void)
 Creates a new SBMLReader and returns it. More...
 
void SBMLReader_free (SBMLReader_t *sr)
 Frees the given SBMLReader. More...
 
int SBMLReader_hasBzip2 ()
 Predicate returning non-zero or zero depending on whether libSBML is linked with bzip2. More...
 
int SBMLReader_hasZlib ()
 Predicate returning non-zero or zero depending on whether underlying libSBML is linked with. More...
 
SBMLDocument_t * SBMLReader_readSBML (SBMLReader_t *sr, const char *filename)
 Reads an SBML document from the given file. More...
 
SBMLDocument_t * SBMLReader_readSBMLFromFile (SBMLReader_t *sr, const char *filename)
 
SBMLDocument_t * SBMLReader_readSBMLFromString (SBMLReader_t *sr, const char *xml)
 Reads an SBML document from the given XML string. More...
 

Function Documentation

SBMLDocument_t* readSBML ( const char *  filename)

Reads an SBML document from the given file filename.

If filename does not exist, or it is not an SBML file, an error will be logged in the error log of the SBMLDocument object returned by this method. Calling programs can inspect this error log to determine the nature of the problem. Please refer to the definition of SBMLDocument for more information about the error reporting mechanism.

Returns
a pointer to the SBMLDocument read.
SBMLDocument_t* readSBMLFromFile ( const char *  filename)
SBMLDocument_t* readSBMLFromString ( const char *  xml)

Reads an SBML document from a string assumed to be in XML format.

If the string does not begin with XML declaration,

<?xml version='1.0' encoding='UTF-8'?>

an XML declaration string will be prepended.

This method will report an error if the given string xml is not SBML. The error will be logged in the error log of the SBMLDocument object returned by this method. Calling programs can inspect this error log to determine the nature of the problem. Please refer to the definition of SBMLDocument for more information about the error reporting mechanism.

Returns
a pointer to the SBMLDocument read.
SBMLReader_t* SBMLReader_create ( void  )

Creates a new SBMLReader and returns it.

By default XML Schema validation is off.

void SBMLReader_free ( SBMLReader_t *  sr)

Frees the given SBMLReader.

int SBMLReader_hasBzip2 ( )

Predicate returning non-zero or zero depending on whether libSBML is linked with bzip2.

Returns
non-zero if libSBML is linked with bzip2, zero otherwise.
int SBMLReader_hasZlib ( )

Predicate returning non-zero or zero depending on whether underlying libSBML is linked with.

Returns
non-zero if libSBML is linked with zlib, zero otherwise.
SBMLDocument_t* SBMLReader_readSBML ( SBMLReader_t *  sr,
const char *  filename 
)

Reads an SBML document from the given file.

If filename does not exist or is not an SBML file, an error will be logged. Errors can be identified by their unique ids, e.g.:

SBMLReader_t *sr;
SBMLDocument_t *d;

sr = SBMLReader_create();

d = SBMLReader_readSBML(reader, filename);

if (SBMLDocument_getNumErrors(d) > 0)
{
if (XMLError_getId(SBMLDocument_getError(d, 0)) == SBML_READ_ERROR_FILE_NOT_FOUND)
if (XMLError_getId(SBMLDocument_getError(d, 0)) == SBML_READ_ERROR_NOT_SBML)
}

If the given filename ends with the suffix ".gz" (for example, "myfile.xml.gz"), the file is assumed to be compressed in gzip format and will be automatically decompressed upon reading. Similarly, if the given filename ends with ".zip" or ".bz2", the file is assumed to be compressed in zip or bzip2 format (respectively). Files whose names lack these suffixes will be read uncompressed. Note that if the file is in zip format but the archive contains more than one file, only the first file in the archive will be read and the rest ignored.

Note
LibSBML versions 2.x and 3.x behave differently in error handling in several respects. One difference is how early some errors are caught and whether libSBML continues processing a file in the face of some early errors. In general, libSBML 3.x stops parsing SBML inputs sooner than libSBML 2.x in the face of XML errors because the errors may invalidate any further SBML content. For example, a missing XML declaration at the beginning of the file was ignored by libSBML 2.x but in version 3.x, it will cause libSBML to stop parsing the rest of the input altogether. While this behavior may seem more severe and intolerant, it was necessary in order to provide uniform behavior regardless of which underlying XML parser (Expat, Xerces, libxml2) is being used by libSBML. The XML parsers themselves behave differently in their error reporting, and sometimes libSBML has to resort to the lowest common denominator.
To read a gzip/zip file, libSBML needs to be configured and linked with the zlib library at compile time. It also needs to be linked with the bzip2 library to read files in bzip2 format. (Both of these are the default configurations for libSBML.) Errors about unreadable files will be logged if a compressed filename is given and libSBML was not linked with the corresponding required library.
Returns
a pointer to the SBMLDocument read.
SBMLDocument_t* SBMLReader_readSBMLFromFile ( SBMLReader_t *  sr,
const char *  filename 
)
SBMLDocument_t* SBMLReader_readSBMLFromString ( SBMLReader_t *  sr,
const char *  xml 
)

Reads an SBML document from the given XML string.

If the string does not begin with XML declaration:

<?xml version='1.0' encoding='UTF-8'?>

it will be prepended.

This method will log a fatal error if the XML string is not SBML. See the method documentation for readSBML(filename) for example error checking code.

Returns
a pointer to the SBMLDocument read.