ConversionProperties_t Class Reference

Detailed Description

Set of configuration option values for a converter.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. It is a class used in the implementation of extra functionality provided by libSBML.

LibSBML provides a number of converters that can perform transformations on SBML documents. The properties of SBML converters are communicated using objects of class ConversionProperties_t, and within such objects, individual options are encapsulated using ConversionOption_t objects. The ConversionProperties_t class provides numerous methods for setting and getting options.

ConversionProperties_t objects are also used to determine the target SBML namespace when an SBML converter's behavior depends on the intended Level+Version combination of SBML. In addition, it is conceivable that conversions may be affected by SBML Level 3 packages being used by an SBML document; consequently, the packages in use are also communicated by the values of the SBML namespaces set on a ConversionProperties_t object.

General information about the use of SBML converters

The use of all the converters follows a similar approach. First, one creates a ConversionProperties_t object and calls ConversionProperties_t::addOption() on this object with one argument: a text string that identifies the desired converter. (The text string is specific to each converter; consult the documentation for a given converter to find out how it should be enabled.)

Next, for some converters, the caller can optionally set some converter-specific properties using additional calls to ConversionProperties_t::addOption(). Many converters provide the ability to configure their behavior to some extent; this is realized through the use of properties that offer different options. The default property values for each converter can be interrogated using the method SBMLConverter_t::getDefaultProperties() on the converter class in question .

Finally, the caller should invoke the method SBMLDocument_t::convert() with the ConversionProperties_t object as an argument.

Example of invoking an SBML converter

The following code fragment illustrates an example using SBMLReactionConverter_t, which is invoked using the option string "replaceReactions":

In the case of SBMLReactionConverter_t, there are no options to affect its behavior, so the next step is simply to invoke the converter on an SBMLDocument_t object. Continuing the example code:

Here is an example of using a converter that offers an option. The following code invokes SBMLStripPackageConverter_t to remove the SBML Level 3 Layout package from a model. It sets the name of the package to be removed by adding a value for the option named "package" defined by that converter:

Available SBML converters in libSBML

LibSBML provides a number of built-in converters; by convention, their names end in Converter. The following are the built-in converters provided by libSBML 5.18.0:

• CobraToFbcConverter_t
• CompFlatteningConverter_t
• FbcToCobraConverter_t
• FbcV1ToV2Converter_t
• FbcV2ToV1Converter_t
• RenderLayoutConverter_t
• SBMLFunctionDefinitionConverter_t
• SBMLIdConverter_t
• SBMLInferUnitsConverter_t
• SBMLInitialAssignmentConverter_t
• SBMLLevel1Version1Converter_t
• SBMLLevelVersionConverter_t
• SBMLLocalParameterConverter_t
• SBMLRateOfConverter_t
• SBMLReactionConverter_t
• SBMLRuleConverter_t
• SBMLStripPackageConverter_t
• SBMLUnitsConverter_t

See also

ConversionOption_t

SBMLNamespaces_t

Examples:

flattenModel.c, promoteParameters.c, and stripPackage.c.

Public Member Functions
void	ConversionProperties_addOption (ConversionProperties_t *cp, const ConversionOption_t *option)
	Adds a copy of the given ConversionOption_t structure to the properties. More...
void	ConversionProperties_addOptionWithKey (ConversionProperties_t *cp, const char *key)
	Adds a new ConversionOption_t structure with the given key to the properties. More...
ConversionProperties_t *	ConversionProperties_clone (const ConversionProperties_t *cp)
	Creates and returns a deep copy of the given ConversionProperties_t structure. More...
ConversionProperties_t *	ConversionProperties_create ()
	Creates a new conversion properties structure (without namespace) More...
ConversionProperties_t *	ConversionProperties_createWithSBMLNamespace (SBMLNamespaces_t *sbmlns)
	Creates a new conversion properties structure with a specific SBML target namespace. More...
int	ConversionProperties_getBoolValue (const ConversionProperties_t *cp, const char *key)
	Returns the value as boolean for a given option in the properties structure. More...
char *	ConversionProperties_getDescription (const ConversionProperties_t *cp, const char *key)
	Returns the description string for a given option in the properties structure. More...
double	ConversionProperties_getDoubleValue (const ConversionProperties_t *cp, const char *key)
	Returns the value as double for a given option in the properties structure. More...
float	ConversionProperties_getFloatValue (const ConversionProperties_t *cp, const char *key)
	Returns the value as float for a given option in the properties structure. More...
int	ConversionProperties_getIntValue (const ConversionProperties_t *cp, const char *key)
	Returns the value as integer for a given option in the properties structure. More...
const ConversionOption_t *	ConversionProperties_getOption (const ConversionProperties_t *cp, const char *key)
	Returns the ConversionOption_t structure for a given key. More...
const SBMLNamespaces_t *	ConversionProperties_getTargetNamespaces (const ConversionProperties_t *cp)
	Returns the current target SBML namespace of the conversion properties. More...
ConversionOptionType_t	ConversionProperties_getType (const ConversionProperties_t *cp, const char *key)
	Returns the type of a given option in the properties structure. More...
char *	ConversionProperties_getValue (const ConversionProperties_t *cp, const char *key)
	Returns the value string for a given option in the properties structure. More...
int	ConversionProperties_hasOption (const ConversionProperties_t *cp, const char *key)
	Checks whether the given properties structure has an option for the given key. More...
int	ConversionProperties_hasTargetNamespaces (const ConversionProperties_t *cp)
	Tests whether the given conversion properties has a target namespace set. More...
ConversionOption_t *	ConversionProperties_removeOption (ConversionProperties_t *cp, const char *key)
	Removes the ConversionOption_t with the given key from the properties. More...
void	ConversionProperties_setBoolValue (ConversionProperties_t *cp, const char *key, int value)
	Sets the value of the option with given key to the given boolean value. More...
void	ConversionProperties_setDoubleValue (ConversionProperties_t *cp, const char *key, double value)
	Sets the value of the option with given key to the given double value. More...
void	ConversionProperties_setFloatValue (ConversionProperties_t *cp, const char *key, float value)
	Sets the value of the option with given key to the given float value. More...
void	ConversionProperties_setIntValue (ConversionProperties_t *cp, const char *key, int value)
	Sets the value of the option with given key to the given int value. More...
void	ConversionProperties_setTargetNamespaces (ConversionProperties_t *cp, SBMLNamespaces_t *sbmlns)
	Sets the target namespace. More...
void	ConversionProperties_setValue (ConversionProperties_t *cp, const char *key, const char *value)
	Sets the value of the option with given key to the given value. More...

Member Function Documentation

void ConversionProperties_addOption	(	ConversionProperties_t *	cp,
		const ConversionOption_t *	option
	)

Adds a copy of the given ConversionOption_t structure to the properties.

Parameters

cp	the conversion properties.
option	the option to add.

Examples:

flattenModel.c, promoteParameters.c, and stripPackage.c.

void ConversionProperties_addOptionWithKey	(	ConversionProperties_t *	cp,
		const char *	key
	)

Adds a new ConversionOption_t structure with the given key to the properties.

Parameters

cp	the conversion properties.
key	the key for the new option.

ConversionProperties_t * ConversionProperties_clone

(

const ConversionProperties_t *

cp

)

Creates and returns a deep copy of the given ConversionProperties_t structure.

Parameters

cp	the conversion properties to clone.

Returns

a (deep) copy of this ConversionProperties_t structure.

ConversionProperties_t * ConversionProperties_create

(

)

Creates a new conversion properties structure (without namespace)

Examples:

flattenModel.c, promoteParameters.c, and stripPackage.c.

ConversionProperties_t * ConversionProperties_createWithSBMLNamespace

(

SBMLNamespaces_t *

sbmlns

)

Creates a new conversion properties structure with a specific SBML target namespace.

Parameters

sbmlns

the target namespace to convert to.

int ConversionProperties_getBoolValue	(	const ConversionProperties_t *	cp,
		const char *	key
	)

Returns the value as boolean for a given option in the properties structure.

Parameters

cp	the conversion properties.
key	the key for the option.

Returns

the boolean value of the option as an integer (1 = true; 0 = false or NULL) with the given key to be freed by the caller.

char * ConversionProperties_getDescription	(	const ConversionProperties_t *	cp,
		const char *	key
	)

Returns the description string for a given option in the properties structure.

Parameters

cp	the conversion properties.
key	the key for the option.

Returns

the description text of the option with the given key to be freed by the caller.

double ConversionProperties_getDoubleValue	(	const ConversionProperties_t *	cp,
		const char *	key
	)

Returns the value as double for a given option in the properties structure.

Parameters

cp	the conversion properties.
key	the key for the option.

Returns

the double value of the option with the given key to be freed by the caller, or NaN.

float ConversionProperties_getFloatValue	(	const ConversionProperties_t *	cp,
		const char *	key
	)

Returns the value as float for a given option in the properties structure.

Parameters

cp	the conversion properties.
key	the key for the option.

Returns

the float value of the option with the given key to be freed by the caller, or NaN.

int ConversionProperties_getIntValue	(	const ConversionProperties_t *	cp,
		const char *	key
	)

Returns the value as integer for a given option in the properties structure.

Parameters

cp	the conversion properties.
key	the key for the option.

Returns

the integer value of the option with the given key to be freed by the caller, or -1.

const ConversionOption_t * ConversionProperties_getOption	(	const ConversionProperties_t *	cp,
		const char *	key
	)

Returns the ConversionOption_t structure for a given key.

Parameters

cp	the conversion properties.
key	the key for the option.

Returns

the option with the given key, or NULL.

const SBMLNamespaces_t * ConversionProperties_getTargetNamespaces

(

const ConversionProperties_t *

cp

)

Returns the current target SBML namespace of the conversion properties.

Parameters

cp	the conversion properties.

Returns

the SBMLNamepaces_t structure expressing the target namespace, or NULL.

ConversionOptionType_t ConversionProperties_getType	(	const ConversionProperties_t *	cp,
		const char *	key
	)

Returns the type of a given option in the properties structure.

Parameters

cp	the conversion properties.
key	the key for the option.

Returns

the type of the option with the given key.

char * ConversionProperties_getValue	(	const ConversionProperties_t *	cp,
		const char *	key
	)

Returns the value string for a given option in the properties structure.

Parameters

cp	the conversion properties.
key	the key for the option.

Returns

the string value of the option with the given key to be freed by the caller, or NULL.

int ConversionProperties_hasOption	(	const ConversionProperties_t *	cp,
		const char *	key
	)

Checks whether the given properties structure has an option for the given key.

Parameters

cp	the conversion properties.
key	the key for the option.

Returns

1 (true) if the option exists, 0 (false) otherwise.

int ConversionProperties_hasTargetNamespaces

(

const ConversionProperties_t *

cp

)

Tests whether the given conversion properties has a target namespace set.

Parameters

cp	the conversion properties.

Returns

1 (true) if the target namespace has been set, 0 (false) otherwise.

ConversionOption_t * ConversionProperties_removeOption	(	ConversionProperties_t *	cp,
		const char *	key
	)

Removes the ConversionOption_t with the given key from the properties.

Parameters

cp	the conversion properties.
key	the key for the option to remove.

Returns

the removed conversion option (needs to be freed by the caller), or NULL, if no option with the given key exists

void ConversionProperties_setBoolValue	(	ConversionProperties_t *	cp,
		const char *	key,
		int	value
	)

Sets the value of the option with given key to the given boolean value.

Parameters

cp	the conversion properties.
key	the key for the option.
value	the new value for the option, with nonzero indicating true, and zero indicating false.

void ConversionProperties_setDoubleValue	(	ConversionProperties_t *	cp,
		const char *	key,
		double	value
	)

Sets the value of the option with given key to the given double value.

Parameters

cp	the conversion properties.
key	the key for the option.
value	the new value for the option.

void ConversionProperties_setFloatValue	(	ConversionProperties_t *	cp,
		const char *	key,
		float	value
	)

Sets the value of the option with given key to the given float value.

Parameters

cp	the conversion properties.
key	the key for the option.
value	the new value for the option.

void ConversionProperties_setIntValue	(	ConversionProperties_t *	cp,
		const char *	key,
		int	value
	)

Sets the value of the option with given key to the given int value.

Parameters

cp	the conversion properties.
key	the key for the option.
value	the new value for the option.

void ConversionProperties_setTargetNamespaces	(	ConversionProperties_t *	cp,
		SBMLNamespaces_t *	sbmlns
	)

Sets the target namespace.

Parameters

cp	the conversion properties.
sbmlns	the target namespace to use.

void ConversionProperties_setValue	(	ConversionProperties_t *	cp,
		const char *	key,
		const char *	value
	)

Sets the value of the option with given key to the given value.

Parameters

cp	the conversion properties.
key	the key for the option.
value	the new value for the option.