Detailed Description

File and text-string SBML writer.

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 SBMLWriter_t class is the converse of SBMLReader_t, and provides the main interface for serializing SBML models into XML and writing the result to an output stream or to files and text strings. The methods for writing SBML all take an SBMLDocument_t object and a destination. They return a boolean or integer value to indicate success or failure.

Support for writing compressed files

LibSBML provides support for writing (as well as reading) compressed SBML files. The process is transparent to the calling application—the application does not need to do anything deliberate to invoke the functionality. If a given SBML filename ends with an extension for the gzip, zip or bzip2 compression formats (respectively, ".gz", ".zip", or ".bz2"), then the methods SBMLWriter_t::writeSBML() and SBMLReader_t::readSBML() will automatically compress and decompress the file while writing and reading it. If the filename has no such extension, it will be written and read uncompressed as normal.

The compression feature requires that the zlib (for gzip and zip formats) and/or bzip2 (for bzip2 format) be available on the system running libSBML, and that libSBML was configured with their support compiled-in. Please see the libSBML installation instructions for more information about this. The methods SBMLWriter_t::hasZlib() and SBMLWriter_t::hasBzip2() can be used by an application to query at run-time whether support for the compression libraries is available in the present copy of libSBML.

Support for compression is not mandated by the SBML standard, but applications may find it helpful, particularly when large SBML models are being communicated across data links of limited bandwidth.

Public Member Functions
SBMLWriter_t *	SBMLWriter_create (void)
	Creates a new SBMLWriter_t and returns a pointer to it. More...

void	SBMLWriter_free (SBMLWriter_t *sw)
	Frees the given SBMLWriter_t. More...

int	SBMLWriter_hasBzip2 ()
	Predicate returning `1` (true) or `0` (false) depending on whether libSBML is linked with bzip2 at compile time. More...

int	SBMLWriter_hasZlib ()
	Predicate returning `1` (true) or `0` (false) depending on whether libSBML is linked with zlib at compile time. More...

int	SBMLWriter_setProgramName (SBMLWriter_t sw, const char name)
	Sets the name of this program. More...

int	SBMLWriter_setProgramVersion (SBMLWriter_t sw, const char version)
	Sets the version of this program. More...

int	SBMLWriter_writeSBML (SBMLWriter_t sw, const SBMLDocument_t d, const char *filename)
	Writes the given SBML document to filename. More...

int	SBMLWriter_writeSBMLToFile (SBMLWriter_t sw, const SBMLDocument_t d, const char *filename)
	Writes the given SBML document to filename. More...

char *	SBMLWriter_writeSBMLToString (SBMLWriter_t sw, const SBMLDocument_t d)
	Writes the given SBML document to an in-memory string and returns a pointer to it. More...

int	writeSBML (const SBMLDocument_t d, const char filename)
	Writes the given SBML document `d` to the file named by `filename`. More...

int	writeSBMLToFile (const SBMLDocument_t d, const char filename)
	Writes the given SBML document `d` to the file `filename`. More...

char *	writeSBMLToString (const SBMLDocument_t *d)
	Writes the given SBML document `d` to an in-memory string and returns a pointer to it. More...

Member Function Documentation

SBMLWriter_t * SBMLWriter_create ( void )

Creates a new SBMLWriter_t and returns a pointer to it.

void SBMLWriter_free ( SBMLWriter_t * sw )

Frees the given SBMLWriter_t.

int SBMLWriter_hasBzip2 ( )

Predicate returning 1 (true) or 0 (false) depending on whether libSBML is linked with bzip2 at compile time.

Returns: 1 (true) if bzip2 is linked, 0 (false) otherwise.

int SBMLWriter_hasZlib ( )

Predicate returning 1 (true) or 0 (false) depending on whether libSBML is linked with zlib at compile time.

Returns: 1 (true) if zlib is linked, 0 (false) otherwise.

int SBMLWriter_setProgramName	(	SBMLWriter_t *	sw,
		const char *	name
	)

Sets the name of this program.

i. e. the one about to write out the SBMLDocument_t. If the program name and version are set (SBMLWriter_setProgramVersion()), the following XML comment, intended for human consumption, will be written at the beginning of the document:

<!-- Created by <program name> version <program version>
on yyyy-MM-dd HH:mm with libSBML version <libsbml version>. -->

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 SBMLWriter_setProgramVersion	(	SBMLWriter_t *	sw,
		const char *	version
	)

Sets the version of this program.

i. e. the one about to write out the SBMLDocument_t. If the program version and name are set (SBMLWriter_setProgramName()), the following XML comment, intended for human consumption, will be written at the beginning of the document:

<!-- Created by <program name> version <program version>
on yyyy-MM-dd HH:mm with libSBML version <libsbml version>. -->

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 SBMLWriter_writeSBML	(	SBMLWriter_t *	sw,
		const SBMLDocument_t *	d,
		const char *	filename
	)

Writes the given SBML document to filename.

If the given filename ends with the suffix ".gz" (for example, "myfile.xml.gz"), libSBML assumes the caller wants the file to be written compressed in gzip format. Similarly, if the given filename ends with ".zip" or ".bz2", libSBML assumes the caller wants the file to be compressed in zip or bzip2 format (respectively). Files whose names lack these suffixes will be written uncompressed. Special considerations for the zip format: If the given filename ends with ".zip", the file placed in the zip archive will have the suffix ".xml" or ".sbml". For example, the file in the zip archive will be named "test.xml" if the given filename is "test.xml.zip" or "test.zip". Similarly, the filename in the archive will be "test.sbml" if the given filename is "test.sbml.zip".

If the filename ends with .gz, the file will be compressed by gzip. Similary, if the filename ends with .zip or .bz2, the file will be compressed by zip or bzip2, respectively. Otherwise, the fill will be uncompressed. If the filename ends with .zip, a filename that will be added to the zip archive file will end with .xml or .sbml. For example, the filename in the zip archive will be test.xml if the given filename is test.xml.zip or test.zip. Also, the filename in the archive will be test.sbml if the given filename is test.sbml.zip.

Note: To write 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 write files in bzip2 format. (Both of these are the default configurations for libSBML.) Errors about unreadable files will be logged and this method will return 0 (false) if a compressed filename is given and libSBML was not linked with the corresponding required library.; SBMLWriter_hasZlib() and SBMLWriter_hasBzip2() can be used to check whether libSBML has been linked with each library.

Returns: 1 (true) on success and 0 (false) if the filename could not be opened for writing.

int SBMLWriter_writeSBMLToFile	(	SBMLWriter_t *	sw,
		const SBMLDocument_t *	d,
		const char *	filename
	)

Writes the given SBML document to filename.

If the filename ends with .gz, the file will be compressed by gzip. Similary, if the filename ends with .zip or .bz2, the file will be compressed by zip or bzip2, respectively. Otherwise, the fill will be uncompressed. If the filename ends with .zip, a filename that will be added to the zip archive file will end with .xml or .sbml. For example, the filename in the zip archive will be test.xml if the given filename is test.xml.zip or test.zip. Also, the filename in the archive will be test.sbml if the given filename is test.sbml.zip.

Note: To create a gzip/zip file, libSBML needs to be linked with zlib at compile time. Also, libSBML needs to be linked with bzip2 to create a bzip2 file. File unwritable error will be logged and 0 (false) will be returned if a compressed file name is given and libSBML is not linked with the required library. SBMLWriter_hasZlib() and SBMLWriter_hasBzip2() can be used to check whether libSBML was linked with the library at compile time.

Returns: 1 (true) on success and 0 (false) if the filename could not be opened for writing.

char * SBMLWriter_writeSBMLToString	(	SBMLWriter_t *	sw,
		const SBMLDocument_t *	d
	)

Writes the given SBML document to an in-memory string and returns a pointer to it.

The string is owned by the caller and should be freed (with free()) when no longer needed.

Returns: the string on success and NULL if one of the underlying parser components fail (rare).

int writeSBML	(	const SBMLDocument_t *	d,
		const char *	filename
	)

Writes the given SBML document d to the file named by filename.

This convenience function is functionally equivalent to:

SBMLWriter_writeSBML(SBMLWriter_create(), d, filename);

If the given filename ends with the suffix ".gz" (for example, "myfile.xml.gz"), libSBML assumes the caller wants the file to be written compressed in gzip format. Similarly, if the given filename ends with ".zip" or ".bz2", libSBML assumes the caller wants the file to be compressed in zip or bzip2 format (respectively). Files whose names lack these suffixes will be written uncompressed. Special considerations for the zip format: If the given filename ends with ".zip", the file placed in the zip archive will have the suffix ".xml" or ".sbml". For example, the file in the zip archive will be named "test.xml" if the given filename is "test.xml.zip" or "test.zip". Similarly, the filename in the archive will be "test.sbml" if the given filename is "test.sbml.zip".

Parameters

d	the SBMLDocument_t object to be written out in XML format.
filename	a string giving the path to a file where the XML content is to be written.

Returns: 1 (true) on success and 0 (false) if filename could not be written. Some possible reasons for failure include (a) being unable to open the file, and (b) using a filename that indicates a compressed SBML file (i.e., a filename ending in ".zip" or similar) when the compression functionality has not been enabled in the underlying copy of libSBML.

See also: SBMLWriter_hasZlib(); SBMLWriter_hasBzip2()

Examples:: addCVTerms.c, addingEvidenceCodes_1.c, addingEvidenceCodes_2.c, addModelHistory.c, appendAnnotation.c, convertSBML.c, createExampleSBML.c, echoSBML.c, flattenModel.c, promoteParameters.c, stripPackage.c, unsetAnnotation.c, and unsetNotes.c.

int writeSBMLToFile	(	const SBMLDocument_t *	d,
		const char *	filename
	)

Writes the given SBML document d to the file filename.

This convenience function is functionally equivalent to:

SBMLWriter_writeSBMLToFile(SBMLWriter_create(), d, filename);

but that does not require the caller to create an SBMLWriter_t object first.

If the given filename ends with the suffix ".gz" (for example, "myfile.xml.gz"), libSBML assumes the caller wants the file to be written compressed in gzip format. Similarly, if the given filename ends with ".zip" or ".bz2", libSBML assumes the caller wants the file to be compressed in zip or bzip2 format (respectively). Files whose names lack these suffixes will be written uncompressed. Special considerations for the zip format: If the given filename ends with ".zip", the file placed in the zip archive will have the suffix ".xml" or ".sbml". For example, the file in the zip archive will be named "test.xml" if the given filename is "test.xml.zip" or "test.zip". Similarly, the filename in the archive will be "test.sbml" if the given filename is "test.sbml.zip".

Parameters

d	an SBMLDocument_t object to be written out in XML format.
filename	a string giving the path to a file where the XML content is to be written.

Returns: 1 (true) on success and 0 (false) if filename could not be written. Some possible reasons for failure include (a) being unable to open the file, and (b) using a filename that indicates a compressed SBML file (i.e., a filename ending in ".zip" or similar) when the compression functionality has not been enabled in the underlying copy of libSBML.

Warning: Note that the string is owned by the caller and should be freed (with the normal string free() C++ function) after it is no longer needed.

See also: SBMLWriter_t::hasZlib(); SBMLWriter_t::hasBzip2()

Examples:: spec_example1.c.

char * writeSBMLToString ( const SBMLDocument_t * d )

Writes the given SBML document d to an in-memory string and returns a pointer to it.

The string is owned by the caller and should be freed (with free()) when no longer needed. This convenience function is functionally equivalent to:

SBMLWriter_writeSBMLToString(SBMLWriter_create(), d);

but does not require the caller to create an SBMLWriter_t object first.

Parameters

d	an SBMLDocument_t object to be written out in XML format.

Returns: the string on success and NULL if one of the underlying parser components fail.

Warning: Note that the string is owned by the caller and should be freed after it is no longer needed.

Detailed Description

Support for writing compressed files

Public Member Functions

Member Function Documentation