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 class is the converse of SBMLReader, 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 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::writeSBML() and SBMLReader::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 libSBMLinstallation instructions for more information about this. The methods SBMLWriter::hasZlib() and SBMLWriter::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 ()
	Creates a new SBMLWriter. More...

int	setProgramName (const std::string &name)
	Sets the name of this program, i.e., the program that is about to write out the SBMLDocument. More...

int	setProgramVersion (const std::string &version)
	Sets the version of this program, i.e., the program that is about to write out the SBMLDocument. More...

bool	writeSBML (const SBMLDocument *d, const std::string &filename)
	Writes the given SBML document to filename. More...

bool	writeSBML (const SBMLDocument *d, std::ostream &stream)
	Writes the given SBML document to the output stream. More...

bool	writeSBMLToFile (const SBMLDocument *d, const std::string &filename)
	Writes the given SBML document to filename. More...

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

	~SBMLWriter ()
	Destroys this SBMLWriter. More...

Static Public Member Functions
static bool	hasBzip2 ()
	Predicate returning `true` if this copy of libSBML has been linked with the bzip2 library. More...

static bool	hasZlib ()
	Predicate returning `true` if this copy of libSBML has been linked with the zlib library. More...

Constructor & Destructor Documentation

SBMLWriter::SBMLWriter ( )

Creates a new SBMLWriter.

The libSBML SBMLWriter objects offer methods for writing SBML in XML form to files and text strings.

SBMLWriter::~SBMLWriter ( )

Destroys this SBMLWriter.

Member Function Documentation

static bool SBMLWriter::hasBzip2 ( )

static

Predicate returning true if this copy of libSBML has been linked with the bzip2 library.

LibSBML supports reading and writing files compressed with either bzip2 or zip/gzip compression. The facility depends on libSBML having been compiled with the necessary support libraries. This method allows a calling program to inquire whether that is the case for the copy of libSBML it is using.

Returns: true if libSBML is linked with bzip2, false otherwise.

Note: Because this is a static method on a class, the Python language interface for libSBML will contain two variants. One will be the expected, normal static method on the class (i.e., a regular methodName), and the other will be a standalone top-level function with the name ClassName_methodName(). This is merely an artifact of how the language interfaces are created in libSBML. The methods are functionally identical.

See also: SBMLWriter::hasZlib()

static bool SBMLWriter::hasZlib ( )

static

Predicate returning true if this copy of libSBML has been linked with the zlib library.

LibSBML supports reading and writing files compressed with either bzip2 or zip/gzip compression. The facility depends on libSBML having been compiled with the necessary support libraries. This method allows a calling program to inquire whether that is the case for the copy of libSBML it is using.

Returns: true if libSBML is linked with zlib, false otherwise.

Note: Because this is a static method on a class, the Python language interface for libSBML will contain two variants. One will be the expected, normal static method on the class (i.e., a regular methodName), and the other will be a standalone top-level function with the name ClassName_methodName(). This is merely an artifact of how the language interfaces are created in libSBML. The methods are functionally identical.

See also: SBMLWriter::hasBzip2()

int SBMLWriter::setProgramName ( const std::string & name )

Sets the name of this program, i.e., the program that is about to write out the SBMLDocument.

If the program name and version are set (see SBMLWriter::setProgramVersion()), the following XML comment, intended for human consumption, will be written at the beginning of the XML document:

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

If the program name and version are not set at some point before calling the writeSBML() methods, no such comment is written out.

Parameters

name	the name of this program (where "this program" refers to program in which libSBML is embedded, not libSBML itself!)

Returns

integer value indicating success/failure of the function. This particular function only does one thing irrespective of user input or object state, and thus will only return a single value:

LIBSBML_OPERATION_SUCCESS

See also: setProgramVersion(const std::string& version)

int SBMLWriter::setProgramVersion ( const std::string & version )

Sets the version of this program, i.e., the program that is about to write out the SBMLDocument.

If the program version and name are set (see 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>. -->

If the program version and name are not set at some point before calling the writeSBML() methods, no such comment is written out.

Parameters

version the version of this program (where "this program" refers to program in which libSBML is embedded, not libSBML itself!)

Returns

integer value indicating success/failure of the function. This particular function only does one thing irrespective of user input or object state, and thus will only return a single value:

LIBSBML_OPERATION_SUCCESS

See also: setProgramName(const std::string& name)

bool SBMLWriter::writeSBML	(	const SBMLDocument *	d,
		const std::string &	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".

Parameters

d	the SBML document to be written.
filename	the name or full pathname of the file where the SBML is to be written.

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

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 false if a compressed filename is given and libSBML was not linked with the corresponding required library.

See also: setProgramVersion(const std::string& version); setProgramName(const std::string& name)

bool SBMLWriter::writeSBML	(	const SBMLDocument *	d,
		std::ostream &	stream
	)

Writes the given SBML document to the output stream.

Parameters

d	the SBML document to be written.
stream	the stream object where the SBML is to be written.

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

See also: setProgramVersion(const std::string& version); setProgramName(const std::string& name)

bool SBMLWriter::writeSBMLToFile	(	const SBMLDocument *	d,
		const std::string &	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".

Parameters

d	the SBML document to be written.
filename	the name or full pathname of the file where the SBML is to be written.

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

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 false if a compressed filename is given and libSBML was not linked with the corresponding required library.

See also: setProgramVersion(const std::string& version); setProgramName(const std::string& name)

char* SBMLWriter::writeSBMLToString ( const SBMLDocument * 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.

Parameters

d	the SBML document to be written.

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

See also: setProgramVersion(const std::string& version); setProgramName(const std::string& name)

Detailed Description

Support for writing compressed files

Public Member Functions

Static Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation