Detailed Description

A single unit referenced in an SBML unit definition.

The SBML unit definition facility uses two classes of objects, UnitDefinition_t and Unit_t. The approach to defining units in SBML is compositional; for example, meter second^–2 is constructed by combining a Unit_t object representing meter with another Unit_t object representing second^–2. The combination is wrapped inside a UnitDefinition_t, which provides for assigning an identifier and optional name to the combination. The identifier can then be referenced from elsewhere in a model. Thus, the UnitDefinition_t class is the container, and Unit_t instances are placed inside UnitDefinition_t instances.

A Unit_t has four attributes named "kind", "exponent", "scale" and "multiplier". It represents a (possibly transformed) reference to a base unit. The attribute "kind" on Unit_t indicates the chosen base unit. Its value must be one of the text strings listed below; this list corresponds to SBML Level 3:

ampere	farad	joule	lux	radian	volt
avogadro	gram	katal	metre	second	watt
becquerel	gray	kelvin	mole	siemens	weber
candela	henry	kilogram	newton	sievert
coulomb	hertz	litre	ohm	steradian
dimensionless	item	lumen	pascal	tesla

A few small differences exist between the Level 3 list of base units and the list defined in other Level/Version combinations of SBML. Specifically, Levels of SBML before Level 3 do not define avogadro; conversely, Level 2 Version 1 defines Celsius, and Level 1 defines celsius, meter, and liter, none of which are available in Level 3. In libSBML, each of the predefined base unit names is represented by an enumeration value in UnitKind_t, discussed in a separate section below.

The attribute named "exponent" on Unit_t represents an exponent on the unit. In SBML Level 2, the attribute is optional and has a default value of 1 (one); in SBML Level 3, the attribute is mandatory and there is no default value. A Unit_t also has an attribute called "scale"; its value must be an integer exponent for a power-of-ten multiplier used to set the scale of the unit. For example, a unit having a "kind" value of gram and a "scale" value of -3 signifies 10^–3 $\times$ gram, or milligrams. In SBML Level 2, the attribute is optional and has a default value of 0 (zero), because 10⁰ = 1; in SBML Level 3, the attribute is mandatory and has no default value. Lastly, the attribute named "multiplier" can be used to multiply the unit by a real-numbered factor; this enables the definition of units that are not power-of-ten multiples of SI units. For instance, a multiplier of 0.3048 could be used to define foot as a measure of length in terms of a metre. The "multiplier" attribute is optional in SBML Level 2, where it has a default value of 1 (one); in SBML Level 3, the attribute is mandatory and has no default value.

UnitKind_t

As discussed above, SBML defines a set of base units which serves as the starting point for new unit definitions. This set of base units consists of the SI units and a small number of additional convenience units.

Until SBML Level 2 Version 3, there existed a data type in the SBML specifications called UnitKind, enumerating the possible SBML base units. Although SBML Level 2 Version 3 removed this type from the language specification, libSBML maintains the corresponding enumeration type UnitKind_t as a convenience and as a way to provide backward compatibility to previous SBML Level/Version specifications. (The removal in SBML Level 2 Version 3 of the enumeration UnitKind was also accompanied by the redefinition of the data type UnitSId to include the previous UnitKind values as reserved symbols in the UnitSId space. This change has no net effect on permissible models, their representation or their syntax. The purpose of the change in the SBML specification was simply to clean up an inconsistency about the contexts in which these values were usable.)

As a consequence of the fact that libSBML supports models in all Levels and Versions of SBML, libSBML's set of UNIT_KIND_ values is a union of all the possible base unit names defined in the different SBML specifications. However, not every base unit is allowed in every Level+Version combination of SBML. Note in particular the following exceptions:

The alternate spelling "meter" is included in addition to the official SI spelling "metre". This spelling is only permitted in SBML Level 1 models.
The alternate spelling "liter" is included in addition to the official SI spelling "litre". This spelling is only permitted in SBML Level 1 models.
The unit "Celsius" is included because of its presence in specifications of SBML prior to SBML Level 2 Version 2.
The unit avogadro was introduced in SBML Level 3, and is only permitted for use in SBML Level 3 models.

The table below lists the symbols defined in the UnitKind_t enumeration, and their meanings.

Enumerator	Meaning
`UNIT_KIND_AMPERE`	The ampere unit.
`UNIT_KIND_AVOGADRO`	The unit `dimensionless` multiplied by the numerical value of Avogadro's constant. (Only usable in SBML Level 3 models.)
`UNIT_KIND_BECQUEREL`	The becquerel unit.
`UNIT_KIND_CANDELA`	The candela unit.
`UNIT_KIND_CELSIUS`	The Celsius unit. (Only usable in SBML Level 1 and SBML Level 2 Version 1 models.)
`UNIT_KIND_COULOMB`	The coulomb unit.
`UNIT_KIND_DIMENSIONLESS`	A pseudo-unit indicating a dimensionless quantity.
`UNIT_KIND_FARAD`	The farad unit.
`UNIT_KIND_GRAM`	The gram unit.
`UNIT_KIND_GRAY`	The gray unit.
`UNIT_KIND_HENRY`	The henry unit.
`UNIT_KIND_HERTZ`	The hertz unit.
`UNIT_KIND_ITEM`	A pseudo-unit representing a single "thing".
`UNIT_KIND_JOULE`	The joule unit.
`UNIT_KIND_KATAL`	The katal unit.
`UNIT_KIND_KELVIN`	The kelvin unit.
`UNIT_KIND_KILOGRAM`	The kilogram unit.
`UNIT_KIND_LITER`	Alternate spelling of litre.
`UNIT_KIND_LITRE`	The litre unit.
`UNIT_KIND_LUMEN`	The lumen unit.
`UNIT_KIND_LUX`	The lux unit.
`UNIT_KIND_METER`	Alternate spelling of metre.
`UNIT_KIND_METRE`	The metre unit.
`UNIT_KIND_MOLE`	The mole unit.
`UNIT_KIND_NEWTON`	The newton unit.
`UNIT_KIND_OHM`	The ohm unit.
`UNIT_KIND_PASCAL`	The pascal unit.
`UNIT_KIND_RADIAN`	The radian unit.
`UNIT_KIND_SECOND`	The second unit.
`UNIT_KIND_SIEMENS`	The siemens unit.
`UNIT_KIND_SIEVERT`	The sievert unit.
`UNIT_KIND_STERADIAN`	The steradian unit.
`UNIT_KIND_TESLA`	The tesla unit.
`UNIT_KIND_VOLT`	The volt unit.
`UNIT_KIND_WATT`	The watt unit.
`UNIT_KIND_WEBER`	The weber unit.
`UNIT_KIND_INVALID`	Marker used by libSBML to indicate an invalid or unset unit.

Examples:: createExampleSBML.c.

Public Member Functions
int	Unit_areEquivalent (Unit_t unit1, Unit_t unit2)
	Predicate returning `true` if Unit_t structures are equivalent. More...

int	Unit_areIdentical (Unit_t unit1, Unit_t unit2)
	Predicate returning `1` (true) if two Unit_t structures are identical. More...

Unit_t *	Unit_clone (const Unit_t *u)
	Creates a deep copy of the given Unit_t structure. More...

UnitDefinition_t *	Unit_convertToSI (Unit_t *unit)
	Returns a UnitDefinition_t structure containing the given `unit` converted to the appropriate SI unit. More...

Unit_t *	Unit_create (unsigned int level, unsigned int version)
	Creates a new Unit_t structure using the given SBML `level` and `version` values. More...

Unit_t *	Unit_createWithNS (SBMLNamespaces_t *sbmlns)
	Creates a new Unit_t structure using the given SBMLNamespaces_t structure. More...

void	Unit_free (Unit_t *u)
	Frees the given Unit_t structure. More...

int	Unit_getExponent (const Unit_t *u)
	Returns the value of the "exponent" attribute of the given Unit_t structure `u`. More...

double	Unit_getExponentAsDouble (const Unit_t *u)
	Returns the value of the "exponent" attribute of the given Unit_t structure `u`. More...

UnitKind_t	Unit_getKind (const Unit_t *u)
	Returns the "kind" attribute value of the given unit `u`. More...

double	Unit_getMultiplier (const Unit_t *u)
	Returns the value of the "multiplier" attribute of the given Unit_t structure `u`. More...

const XMLNamespaces_t *	Unit_getNamespaces (Unit_t *u)
	Returns a list of XMLNamespaces_t associated with this Unit_t structure. More...

double	Unit_getOffset (const Unit_t *u)
	Returns the value of the "offset" attribute of the given Unit_t structure `u`. More...

int	Unit_getScale (const Unit_t *u)
	Returns the value of the "scale" attribute of the given Unit_t structure `u`. More...

int	Unit_hasRequiredAttributes (Unit_t *u)
	Predicate returning `1` (true) or `0` (false) depending on whether all the required attributes for this Unit_t structure have been set. More...

void	Unit_initDefaults (Unit_t *u)
	Initializes the attributes of this Unit_t (except for "kind") to their default values. More...

int	Unit_isAmpere (const Unit_t *u)
	Predicate for testing whether the given Unit_t structure represents a unit of the kind `ampere`. More...

int	Unit_isBecquerel (const Unit_t *u)
	Predicate for testing whether the given Unit_t structure represents a unit of the kind `becquerel`. More...

int	Unit_isBuiltIn (const char *name, unsigned int level)
	Predicate to test whether a given string is the name of a built-in SBML unit, depending on the SBML level, since new predefined units were added between level 2 versions 1 and 2, and then all predefined units were removed again in SBML Level 3. More...

int	Unit_isCandela (const Unit_t *u)
	Predicate for testing whether the given Unit_t structure represents a unit of the kind `candela`. More...

int	Unit_isCelsius (const Unit_t *u)
	Predicate for testing whether the given Unit_t structure represents a unit of the kind `Celsius`. More...

int	Unit_isCoulomb (const Unit_t *u)
	Predicate for testing whether the given Unit_t structure represents a unit of the kind `coulomb`. More...

int	Unit_isDimensionless (const Unit_t *u)
	Predicate for testing whether the given Unit_t structure represents a unit of the kind `dimensionless`. More...

int	Unit_isFarad (const Unit_t *u)
	Predicate for testing whether the given Unit_t structure represents a unit of the kind `farad`. More...

int	Unit_isGram (const Unit_t *u)
	Predicate for testing whether the given Unit_t structure represents a unit of the kind `gram`. More...

int	Unit_isGray (const Unit_t *u)
	Predicate for testing whether the given Unit_t structure represents a unit of the kind `gray`. More...

int	Unit_isHenry (const Unit_t *u)
	Predicate for testing whether the given Unit_t structure represents a unit of the kind `henry`. More...

int	Unit_isHertz (const Unit_t *u)
	Predicate for testing whether the given Unit_t structure represents a unit of the kind `hertz`. More...

int	Unit_isItem (const Unit_t *u)
	Predicate for testing whether the given Unit_t structure represents a unit of the kind `item`. More...

int	Unit_isJoule (const Unit_t *u)
	Predicate for testing whether the given Unit_t structure represents a unit of the kind `joule`. More...

int	Unit_isKatal (const Unit_t *u)
	Predicate for testing whether the given Unit_t structure represents a unit of the kind `katal`. More...

int	Unit_isKelvin (const Unit_t *u)
	Predicate for testing whether the given Unit_t structure represents a unit of the kind `kelvin`. More...

int	Unit_isKilogram (const Unit_t *u)
	Predicate for testing whether the given Unit_t structure represents a unit of the kind `kilogram`. More...

int	Unit_isLitre (const Unit_t *u)
	Predicate for testing whether the given Unit_t structure represents a unit of the kind `litre` or `liter`. More...

int	Unit_isLumen (const Unit_t *u)
	Predicate for testing whether the given Unit_t structure represents a unit of the kind `lumen`. More...

int	Unit_isLux (const Unit_t *u)
	Predicate for testing whether the given Unit_t structure represents a unit of the kind `lux`. More...

int	Unit_isMetre (const Unit_t *u)
	Predicate for testing whether the given Unit_t structure represents a unit of the kind `metre` or `meter`. More...

int	Unit_isMole (const Unit_t *u)
	Predicate for testing whether the given Unit_t structure represents a unit of the kind `mole`. More...

int	Unit_isNewton (const Unit_t *u)
	Predicate for testing whether the given Unit_t structure represents a unit of the kind `newton`. More...

int	Unit_isOhm (const Unit_t *u)
	Predicate for testing whether the given Unit_t structure represents a unit of the kind `ohm`. More...

int	Unit_isPascal (const Unit_t *u)
	Predicate for testing whether the given Unit_t structure represents a unit of the kind `pascal`. More...

int	Unit_isRadian (const Unit_t *u)
	Predicate for testing whether the given Unit_t structure represents a unit of the kind `radian`. More...

int	Unit_isSecond (const Unit_t *u)
	Predicate for testing whether the given Unit_t structure represents a unit of the kind `second`. More...

int	Unit_isSetExponent (const Unit_t *u)
	Predicate to test whether the "exponent" attribute of the given Unit_t structure `u` is set. More...

int	Unit_isSetKind (const Unit_t *u)
	Predicate to test whether the "kind" attribute of the given Unit_t structure `u` is set. More...

int	Unit_isSetMultiplier (const Unit_t *u)
	Predicate to test whether the "multiplier" attribute of the given Unit_t structure `u` is set. More...

int	Unit_isSetOffset (const Unit_t *u)
	Predicate to test whether the "scale" attribute of the given Unit_t structure `u` is set. More...

int	Unit_isSetScale (const Unit_t *u)
	Predicate to test whether the "scale" attribute of the given Unit_t structure `u` is set. More...

int	Unit_isSiemens (const Unit_t *u)
	Predicate for testing whether the given Unit_t structure represents a unit of the kind `siemens`. More...

int	Unit_isSievert (const Unit_t *u)
	Predicate for testing whether the given Unit_t structure represents a unit of the kind `sievert`. More...

int	Unit_isSteradian (const Unit_t *u)
	Predicate for testing whether the given Unit_t structure represents a unit of the kind `steradian`. More...

int	Unit_isTesla (const Unit_t *u)
	Predicate for testing whether the given Unit_t structure represents a unit of the kind `tesla`. More...

int	Unit_isVolt (const Unit_t *u)
	Predicate for testing whether the given Unit_t structure represents a unit of the kind `volt`. More...

int	Unit_isWatt (const Unit_t *u)
	Predicate for testing whether the given Unit_t structure represents a unit of the kind `watt`. More...

int	Unit_isWeber (const Unit_t *u)
	Predicate for testing whether the given Unit_t structure represents a unit of the kind `weber`. More...

void	Unit_merge (Unit_t unit1, Unit_t unit2)
	Merges two Unit_t structures with the same "kind" attribute value into a single Unit_t. More...

int	Unit_removeScale (Unit_t *unit)
	Manipulates the attributes of the Unit_t to express the unit with the value of the scale attribute reduced to zero. More...

int	Unit_setExponent (Unit_t *u, int value)
	Sets the "exponent" attribute value of the given Unit_t structure `u`. More...

int	Unit_setExponentAsDouble (Unit_t *u, double value)
	Sets the "exponent" attribute value of the given Unit_t structure `u`. More...

int	Unit_setKind (Unit_t *u, UnitKind_t kind)
	Sets the kind of the given Unit_t structure `u` to the given UnitKind_t value. More...

int	Unit_setMultiplier (Unit_t *u, double value)
	Sets the "multiplier" attribute value of the given Unit_t structure `u`. More...

int	Unit_setOffset (Unit_t *u, double value)
	Sets the "offset" attribute value of the given Unit_t structure `u`. More...

int	Unit_setScale (Unit_t *u, int value)
	Sets the "scale" attribute value of the given Unit_t structure `u`. More...

int	Unit_unsetExponent (Unit_t *u)
	Unsets the "exponent" attribute value of the given Unit_t structure `u`. More...

int	Unit_unsetKind (Unit_t *u)
	Unsets the kind of the given Unit_t structure `u`. More...

int	Unit_unsetMultiplier (Unit_t *u)
	Unsets the "multiplier" attribute value of the given Unit_t structure `u`. More...

int	Unit_unsetOffset (Unit_t *u)
	Unsets the "offset" attribute value of the given Unit_t structure `u`. More...

int	Unit_unsetScale (Unit_t *u)
	Unsets the "scale" attribute value of the given Unit_t structure `u`. More...

int	UnitKind_equals (UnitKind_t uk1, UnitKind_t uk2)
	Tests for logical equality between two given `UNIT_KIND_` code values. More...

UnitKind_t	UnitKind_forName (const char *name)
	Converts a text string naming a kind of unit to its corresponding libSBML `UNIT_KIND_` constant/enumeration value. More...

int	UnitKind_isValidUnitKindString (const char *str, unsigned int level, unsigned int version)
	Predicate for testing whether a given string corresponds to a predefined libSBML unit code. More...

const char *	UnitKind_toString (UnitKind_t uk)
	Converts a unit code to a text string equivalent. More...

Member Function Documentation

int Unit_areEquivalent	(	Unit_t *	unit1,
		Unit_t *	unit2
	)

Predicate returning true if Unit_t structures are equivalent.

Two Unit_t structures are considered to be equivalent either if (1) both have a "kind" attribute value of dimensionless, or (2) their "kind", "exponent" and (for SBML Level 2 Version 1) "offset" attribute values are equal. (Contrast this to the method Unit_areIdentical(), which compares Unit_t structures with respect to all attributes, not just the "kind" and "exponent".)

Parameters

unit1	the first Unit_t structure to compare.
unit2	the second Unit_t structure to compare.

Returns: 1 (true) if the "kind" and "exponent" attributes of unit1 are identical to the kind and exponent attributes of unit2, or if the kind attributes of both are dimensionless; 0 (false) otherwise.

See also: Unit_areIdentical()

int Unit_areIdentical	(	Unit_t *	unit1,
		Unit_t *	unit2
	)

Predicate returning 1 (true) if two Unit_t structures are identical.

Two Unit_t structures are considered to be identical if they match in all attributes. (Contrast this to the method Unit_areEquivalent(), which compares Unit_t structures only with respect to certain attributes.)

Parameters

unit1	the first Unit_t structure to compare.
unit2	the second Unit_t structure to compare.

Returns: 1 (true) if all the attributes of unit1 are identical to the attributes of unit2, 0 (false) otherwise.

See also: Unit_areEquivalent()

Unit_t * Unit_clone ( const Unit_t * u )

Creates a deep copy of the given Unit_t structure.

Parameters

u	the Unit_t structure to be copied.

Returns: a (deep) copy of the given Unit_t structure.

UnitDefinition_t * Unit_convertToSI ( Unit_t * unit )

Returns a UnitDefinition_t structure containing the given unit converted to the appropriate SI unit.

This method exists because some units can be expressed in terms of others when the same physical dimension is involved. For example, one hertz is identical to 1 sec^-1, one litre is equivalent to 1 cubic decametre, and so on.

Parameters

unit	the Unit_t structure to convert to SI.

Returns: a UnitDefinition_t structure containing the SI unit.

See also: Unit_merge()

Unit_t * Unit_create	(	unsigned int	level,
		unsigned int	version
	)

Creates a new Unit_t structure using the given SBML level and version values.

Parameters

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

Returns: a pointer to the newly created Unit_t structure.

Note: Attempting to add an object to an SBMLDocument_t having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument_t), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.

Unit_t * Unit_createWithNS ( SBMLNamespaces_t * sbmlns )

Creates a new Unit_t structure using the given SBMLNamespaces_t structure.

Parameters

sbmlns SBMLNamespaces_t, a pointer to an SBMLNamespaces_t structure to assign to this Unit_t.

Returns: a pointer to the newly created Unit_t structure.

Note: Attempting to add an object to an SBMLDocument_t having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument_t), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.

void Unit_free ( Unit_t * u )

Frees the given Unit_t structure.

Parameters

u	the Unit_t structure to be freed.

int Unit_getExponent ( const Unit_t * u )

Returns the value of the "exponent" attribute of the given Unit_t structure u.

Parameters

u	a Unit_t structure.

Returns: the "exponent" value of this Unit_t structure, as an integer.

double Unit_getExponentAsDouble ( const Unit_t * u )

Returns the value of the "exponent" attribute of the given Unit_t structure u.

Parameters

u	a Unit_t structure.

Returns: the "exponent" value of this Unit_t structure, as a double.

UnitKind_t Unit_getKind ( const Unit_t * u )

Returns the "kind" attribute value of the given unit u.

Returns: the value of the "kind" attribute of this Unit_t as a value from the UnitKind_t enumeration.

double Unit_getMultiplier ( const Unit_t * u )

Returns the value of the "multiplier" attribute of the given Unit_t structure u.

Parameters

u	a Unit_t structure.

Returns: the "multiplier" value of this Unit_t, as a double

const XMLNamespaces_t * Unit_getNamespaces ( Unit_t * u )

Returns a list of XMLNamespaces_t associated with this Unit_t structure.

Parameters

u	the Unit_t structure.

Returns: pointer to the XMLNamespaces_t structure associated with this structure.

double Unit_getOffset ( const Unit_t * u )

Returns the value of the "offset" attribute of the given Unit_t structure u.

Parameters

u	a Unit_t structure.

Returns: the "offset" value of this Unit_t, as a double

Warning: The "offset" attribute is only available in SBML Level 2 Version 1. This attribute is not present in SBML Level 2 Version 2 or above. When producing SBML models using these later specifications, Modelers and software need to account for units with offsets explicitly. The SBML specification document offers a number of suggestions for how to achieve this. LibSBML functions such as this one related to "offset" are retained for compatibility with earlier versions of SBML Level 2, but their use is strongly discouraged.

int Unit_getScale ( const Unit_t * u )

Returns the value of the "scale" attribute of the given Unit_t structure u.

Parameters

u	a Unit_t structure.

Returns: the "scale" value of this Unit_t, as an integer.

int Unit_hasRequiredAttributes ( Unit_t * u )

Predicate returning 1 (true) or 0 (false) depending on whether all the required attributes for this Unit_t structure have been set.

The required attributes for a Unit_t structure are:

kind
exponent (L3 on)
multiplier (L3 on)
scale (L3 on)

Returns: a boolean value indicating whether all the required elements for this structure have been defined.

void Unit_initDefaults ( Unit_t * u )

Initializes the attributes of this Unit_t (except for "kind") to their default values.

The default values are as follows:

exponent = 1
scale = 0
multiplier = 1.0

int Unit_isAmpere ( const Unit_t * u )

Predicate for testing whether the given Unit_t structure represents a unit of the kind ampere.

Parameters

u	the Unit_t structure to query.

Returns: 1 (true) if the "kind" attribute of the given Unit_t structure is set to "ampere", 0 (false) otherwise.

int Unit_isBecquerel ( const Unit_t * u )

Predicate for testing whether the given Unit_t structure represents a unit of the kind becquerel.

Parameters

u	the Unit_t structure to query.

Returns: 1 (true) if the "kind" attribute of the given Unit_t structure is set to "becquerel", 0 (false) otherwise.

int Unit_isBuiltIn	(	const char *	name,
		unsigned int	level
	)

Predicate to test whether a given string is the name of a built-in SBML unit, depending on the SBML level, since new predefined units were added between level 2 versions 1 and 2, and then all predefined units were removed again in SBML Level 3.

Parameters

name	a string to be tested against the built-in unit names.
level	the level of SBML one is checking.

Returns: 1 (true) if name is one of "substance", "volume", or "time" and the level is 1; or if name is one of "substance", "volume", "area", "length", or "time" and the level is 2; 0 (false) otherwise (including all values when level is 3).

int Unit_isCandela ( const Unit_t * u )

Predicate for testing whether the given Unit_t structure represents a unit of the kind candela.

Parameters

u	the Unit_t structure to query.

Returns: 1 (true) if the "kind" attribute of the given Unit_t structure is set to "candela", 0 (false) otherwise.

int Unit_isCelsius ( const Unit_t * u )

Predicate for testing whether the given Unit_t structure represents a unit of the kind Celsius.

Parameters

u	the Unit_t structure to query.

Returns: 1 (true) if the "kind" attribute of the given Unit_t structure is set to "Celsius", 0 (false) otherwise.

Warning: The predefined unit Celsius was removed from the list of predefined units in SBML Level 2 Version 2 at the same time that the "offset" attribute was removed from Unit_t definitions. LibSBML functions such as this one related to Celsius are retained for compatibility with earlier versions of SBML Level 2, but their use is strongly discouraged.

int Unit_isCoulomb ( const Unit_t * u )

Predicate for testing whether the given Unit_t structure represents a unit of the kind coulomb.

Parameters

u	the Unit_t structure to query.

Returns: 1 (true) if the "kind" attribute of the given Unit_t structure is set to "coulomb", 0 (false) otherwise.

int Unit_isDimensionless ( const Unit_t * u )

Predicate for testing whether the given Unit_t structure represents a unit of the kind dimensionless.

Parameters

u	the Unit_t structure to query.

Returns: 1 (true) if the "kind" attribute of the given Unit_t structure is set to "dimensionless", 0 (false) otherwise.

int Unit_isFarad ( const Unit_t * u )

Predicate for testing whether the given Unit_t structure represents a unit of the kind farad.

Parameters

u	the Unit_t structure to query.

Returns: 1 (true) if the "kind" attribute of the given Unit_t structure is set to "farad", 0 (false) otherwise.

int Unit_isGram ( const Unit_t * u )

Predicate for testing whether the given Unit_t structure represents a unit of the kind gram.

Parameters

u	the Unit_t structure to query.

Returns: 1 (true) if the "kind" attribute of the given Unit_t structure is set to "gram", 0 (false) otherwise.

int Unit_isGray ( const Unit_t * u )

Predicate for testing whether the given Unit_t structure represents a unit of the kind gray.

Parameters

u	the Unit_t structure to query.

Returns: 1 (true) if the "kind" attribute of the given Unit_t structure is set to "gray", 0 (false) otherwise.

int Unit_isHenry ( const Unit_t * u )

Predicate for testing whether the given Unit_t structure represents a unit of the kind henry.

Parameters

u	the Unit_t structure to query.

Returns: 1 (true) if the "kind" attribute of the given Unit_t structure is set to "henry", 0 (false) otherwise.

int Unit_isHertz ( const Unit_t * u )

Predicate for testing whether the given Unit_t structure represents a unit of the kind hertz.

Parameters

u	the Unit_t structure to query.

Returns: 1 (true) if the "kind" attribute of the given Unit_t structure is set to "hertz", 0 (false) otherwise.

int Unit_isItem ( const Unit_t * u )

Predicate for testing whether the given Unit_t structure represents a unit of the kind item.

Parameters

u	the Unit_t structure to query.

Returns: 1 (true) if the "kind" attribute of the given Unit_t structure is set to "item", 0 (false) otherwise.

int Unit_isJoule ( const Unit_t * u )

Predicate for testing whether the given Unit_t structure represents a unit of the kind joule.

Parameters

u	the Unit_t structure to query.

Returns: 1 (true) if the "kind" attribute of the given Unit_t structure is set to "joule", 0 (false) otherwise.

int Unit_isKatal ( const Unit_t * u )

Predicate for testing whether the given Unit_t structure represents a unit of the kind katal.

Parameters

u	the Unit_t structure to query.

Returns: 1 (true) if the "kind" attribute of the given Unit_t structure is set to "katal", 0 (false) otherwise.

int Unit_isKelvin ( const Unit_t * u )

Predicate for testing whether the given Unit_t structure represents a unit of the kind kelvin.

Parameters

u	the Unit_t structure to query.

Returns: 1 (true) if the "kind" attribute of the given Unit_t structure is set to "kelvin", 0 (false) otherwise.

int Unit_isKilogram ( const Unit_t * u )

Predicate for testing whether the given Unit_t structure represents a unit of the kind kilogram.

Parameters

u	the Unit_t structure to query.

Returns: 1 (true) if the "kind" attribute of the given Unit_t structure is set to "kilogram", 0 (false) otherwise.

int Unit_isLitre ( const Unit_t * u )

Predicate for testing whether the given Unit_t structure represents a unit of the kind litre or liter.

Parameters

u	the Unit_t structure to query.

Returns: 1 (true) if the "kind" attribute of the given Unit_t structure is set to "litre" or "liter", 0 (false) otherwise.

int Unit_isLumen ( const Unit_t * u )

Predicate for testing whether the given Unit_t structure represents a unit of the kind lumen.

Parameters

u	the Unit_t structure to query.

Returns: 1 (true) if the "kind" attribute of the given Unit_t structure is set to "lumen", 0 (false) otherwise.

int Unit_isLux ( const Unit_t * u )

Predicate for testing whether the given Unit_t structure represents a unit of the kind lux.

Parameters

u	the Unit_t structure to query.

Returns: 1 (true) if the "kind" attribute of the given Unit_t structure is set to "lux", 0 (false) otherwise.

int Unit_isMetre ( const Unit_t * u )

Predicate for testing whether the given Unit_t structure represents a unit of the kind metre or meter.

Parameters

u	the Unit_t structure to query.

Returns: 1 (true) if the "kind" attribute of the given Unit_t structure is set to "metre" or "meter", 0 (false) otherwise.

int Unit_isMole ( const Unit_t * u )

Predicate for testing whether the given Unit_t structure represents a unit of the kind mole.

Parameters

u	the Unit_t structure to query.

Returns: 1 (true) if the "kind" attribute of the given Unit_t structure is set to "mole", 0 (false) otherwise.

int Unit_isNewton ( const Unit_t * u )

Predicate for testing whether the given Unit_t structure represents a unit of the kind newton.

Parameters

u	the Unit_t structure to query.

Returns: 1 (true) if the "kind" attribute of the given Unit_t structure is set to "newton", 0 (false) otherwise.

int Unit_isOhm ( const Unit_t * u )

Predicate for testing whether the given Unit_t structure represents a unit of the kind ohm.

Parameters

u	the Unit_t structure to query.

Returns: 1 (true) if the "kind" attribute of the given Unit_t structure is set to "ohm", 0 (false) otherwise.

int Unit_isPascal ( const Unit_t * u )

Predicate for testing whether the given Unit_t structure represents a unit of the kind pascal.

Parameters

u	the Unit_t structure to query.

Returns: 1 (true) if the "kind" attribute of the given Unit_t structure is set to "pascal", 0 (false) otherwise.

int Unit_isRadian ( const Unit_t * u )

Predicate for testing whether the given Unit_t structure represents a unit of the kind radian.

Parameters

u	the Unit_t structure to query.

Returns: 1 (true) if the "kind" attribute of the given Unit_t structure is set to "radian", 0 (false) otherwise.

int Unit_isSecond ( const Unit_t * u )

Predicate for testing whether the given Unit_t structure represents a unit of the kind second.

Parameters

u	the Unit_t structure to query.

Returns: 1 (true) if the "kind" attribute of the given Unit_t structure is set to "second", 0 (false) otherwise.

int Unit_isSetExponent ( const Unit_t * u )

Predicate to test whether the "exponent" attribute of the given Unit_t structure u is set.

Parameters

u	the Unit_t structure to query.

Returns: 1 (true) if the "exponent" attribute of the given Unit_t structure is set, 0 (false) otherwise.

int Unit_isSetKind ( const Unit_t * u )

Predicate to test whether the "kind" attribute of the given Unit_t structure u is set.

Parameters

u	the Unit_t structure to query.

Returns: 1 (true) if the "kind" attribute of the given Unit_t structure is set, 0 (false) otherwise.

int Unit_isSetMultiplier ( const Unit_t * u )

Predicate to test whether the "multiplier" attribute of the given Unit_t structure u is set.

Parameters

u	the Unit_t structure to query.

Returns: 1 (true) if the "multiplier" attribute of the given Unit_t structure is set, 0 (false) otherwise.

int Unit_isSetOffset ( const Unit_t * u )

Predicate to test whether the "scale" attribute of the given Unit_t structure u is set.

Parameters

u	the Unit_t structure to query.

Returns: 1 (true) if the "scale" attribute of the given Unit_t structure is set, 0 (false) otherwise.

Warning: The "offset" attribute is only available in SBML Level 2 Version 1. This attribute is not present in SBML Level 2 Version 2 or above. When producing SBML models using these later specifications, Modelers and software need to account for units with offsets explicitly. The SBML specification document offers a number of suggestions for how to achieve this. LibSBML functions such as this one related to "offset" are retained for compatibility with earlier versions of SBML Level 2, but their use is strongly discouraged.

int Unit_isSetScale ( const Unit_t * u )

Predicate to test whether the "scale" attribute of the given Unit_t structure u is set.

Parameters

u	the Unit_t structure to query.

Returns: 1 (true) if the "scale" attribute of the given Unit_t structure is set, 0 (false) otherwise.

int Unit_isSiemens ( const Unit_t * u )

Predicate for testing whether the given Unit_t structure represents a unit of the kind siemens.

Parameters

u	the Unit_t structure to query.

Returns: 1 (true) if the "kind" attribute of the given Unit_t structure is set to "siemens", 0 (false) otherwise.

int Unit_isSievert ( const Unit_t * u )

Predicate for testing whether the given Unit_t structure represents a unit of the kind sievert.

Parameters

u	the Unit_t structure to query.

Returns: 1 (true) if the "kind" attribute of the given Unit_t structure is set to "sievert", 0 (false) otherwise.

int Unit_isSteradian ( const Unit_t * u )

Predicate for testing whether the given Unit_t structure represents a unit of the kind steradian.

Parameters

u	the Unit_t structure to query.

Returns: 1 (true) if the "kind" attribute of the given Unit_t structure is set to "steradian", 0 (false) otherwise.

int Unit_isTesla ( const Unit_t * u )

Predicate for testing whether the given Unit_t structure represents a unit of the kind tesla.

Parameters

u	the Unit_t structure to query.

Returns: 1 (true) if the "kind" attribute of the given Unit_t structure is set to "tesla", 0 (false) otherwise.

int Unit_isVolt ( const Unit_t * u )

Predicate for testing whether the given Unit_t structure represents a unit of the kind volt.

Parameters

u	the Unit_t structure to query.

Returns: 1 (true) if the "kind" attribute of the given Unit_t structure is set to "volt", 0 (false) otherwise.

int Unit_isWatt ( const Unit_t * u )

Predicate for testing whether the given Unit_t structure represents a unit of the kind watt.

Parameters

u	the Unit_t structure to query.

Returns: 1 (true) if the "kind" attribute of the given Unit_t structure is set to "watt", 0 (false) otherwise.

int Unit_isWeber ( const Unit_t * u )

Predicate for testing whether the given Unit_t structure represents a unit of the kind weber.

Parameters

u	the Unit_t structure to query.

Returns: 1 (true) if the "kind" attribute of the given Unit_t structure is set to "weber", 0 (false) otherwise.

void Unit_merge	(	Unit_t *	unit1,
		Unit_t *	unit2
	)

Merges two Unit_t structures with the same "kind" attribute value into a single Unit_t.

For example, the following,

<unit kind="metre" exponent="2"/>
<unit kind="metre" exponent="1"/>

would be merged to become

<unit kind="metre" exponent="3"/>

Parameters

unit1	the first Unit_t structure; the result of the operation is left as a new version of this unit, modified in-place. Not modified if the two units have different kinds.
unit2	the second Unit_t structure to merge with the first.

See also: Unit_convertToSI(); Unit_removeScale()

int Unit_removeScale ( Unit_t * unit )

Manipulates the attributes of the Unit_t to express the unit with the value of the scale attribute reduced to zero.

For example, 1 millimetre can be expressed as a Unit_t with kind= "metre" multiplier="1" scale="-3" exponent="1". It can also be expressed as a Unit_t with kind="metre" multiplier="0.001" scale="0" exponent="1".

Parameters

unit	the Unit_t structure to manipulate.

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: Unit_convertToSI(); Unit_merge()

int Unit_setExponent	(	Unit_t *	u,
		int	value
	)

Sets the "exponent" attribute value of the given Unit_t structure u.

Parameters

u	the Unit_t structure whose value is to be set.
value	the integer to which the attribute "exponent" should be set.

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:

Examples:: createExampleSBML.c.

int Unit_setExponentAsDouble	(	Unit_t *	u,
		double	value
	)

Sets the "exponent" attribute value of the given Unit_t structure u.

Parameters

u	the Unit_t structure whose value is to be set.
value	the double to which the attribute "exponent" should be set.

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 Unit_setKind	(	Unit_t *	u,
		UnitKind_t	kind
	)

Sets the kind of the given Unit_t structure u to the given UnitKind_t value.

Parameters

u	the Unit_t structure whose value is to be set.
kind	a value from the UnitKind_t enumeration.

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:

Examples:: createExampleSBML.c.

int Unit_setMultiplier	(	Unit_t *	u,
		double	value
	)

Sets the "multiplier" attribute value of the given Unit_t structure u.

Parameters

u	the Unit_t structure whose value is to be set.
value	the integer to which the attribute "multiplier" should be set.

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 Unit_setOffset	(	Unit_t *	u,
		double	value
	)

Sets the "offset" attribute value of the given Unit_t structure u.

Parameters

u	the Unit_t structure whose value is to be set.
value	the integer to which the attribute "offset" should be set.

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:

Warning: The "offset" attribute is only available in SBML Level 2 Version 1. This attribute is not present in SBML Level 2 Version 2 or above. When producing SBML models using these later specifications, Modelers and software need to account for units with offsets explicitly. The SBML specification document offers a number of suggestions for how to achieve this. LibSBML functions such as this one related to "offset" are retained for compatibility with earlier versions of SBML Level 2, but their use is strongly discouraged.

int Unit_setScale	(	Unit_t *	u,
		int	value
	)

Sets the "scale" attribute value of the given Unit_t structure u.

Parameters

u	the Unit_t structure whose value is to be set.
value	the integer to which the attribute "scale" should be set.

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:

Examples:: createExampleSBML.c.

int Unit_unsetExponent ( Unit_t * u )

Unsets the "exponent" attribute value of the given Unit_t structure u.

Parameters

u	the Unit_t structure whose value is to be set.

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 Unit_unsetKind ( Unit_t * u )

Unsets the kind of the given Unit_t structure u.

Parameters

u	the Unit_t structure whose value is to be set.

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 Unit_unsetMultiplier ( Unit_t * u )

Unsets the "multiplier" attribute value of the given Unit_t structure u.

Parameters

u	the Unit_t structure whose value is to be set.

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 Unit_unsetOffset ( Unit_t * u )

Unsets the "offset" attribute value of the given Unit_t structure u.

Parameters

u	the Unit_t structure whose value is to be set.

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:

Warning: The "offset" attribute is only available in SBML Level 2 Version 1. This attribute is not present in SBML Level 2 Version 2 or above. When producing SBML models using these later specifications, Modelers and software need to account for units with offsets explicitly. The SBML specification document offers a number of suggestions for how to achieve this. LibSBML functions such as this one related to "offset" are retained for compatibility with earlier versions of SBML Level 2, but their use is strongly discouraged.

int Unit_unsetScale ( Unit_t * u )

Unsets the "scale" attribute value of the given Unit_t structure u.

Parameters

u	the Unit_t structure whose value is to be set.

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 UnitKind_equals	(	UnitKind_t	uk1,
		UnitKind_t	uk2
	)

Tests for logical equality between two given UNIT_KIND_ code values.

This function behaves exactly like C's == operator, except for the following two cases:

UNIT_KIND_LITER == UNIT_KIND_LITRE
UNIT_KIND_METER == UNIT_KIND_METRE

In the two cases above, C equality comparison would yield 0 (false) (because each of the above is a distinct enumeration value), but this function returns true.

Parameters

uk1	a `UNIT_KIND_` value.
uk2	a second `UNIT_KIND_` value to compare to `uk1`.

Returns: 1 (true) if uk1 is logically equivalent to uk2, 0 (false) otherwise.

Note: For more information about the libSBML unit codes, please refer to the class documentation for Unit_t.

UnitKind_t UnitKind_forName ( const char * name )

Converts a text string naming a kind of unit to its corresponding libSBML UNIT_KIND_ constant/enumeration value.

Parameters

name	a string, the name of a predefined base unit in SBML.

Returns: a value from UnitKind_t corresponding to the given string name (determined in a case-insensitive manner).

Note: For more information about the libSBML unit codes, please refer to the class documentation for Unit_t.

int UnitKind_isValidUnitKindString	(	const char *	str,
		unsigned int	level,
		unsigned int	version
	)

Predicate for testing whether a given string corresponds to a predefined libSBML unit code.

Parameters

str	a text string naming a base unit defined by SBML.
level	the Level of SBML.
version	the Version within the Level of SBML.

Returns: 1 (true) if string is the name of a valid UNIT_KIND_ value, 0 (false) otherwise.

Note: For more information about the libSBML unit codes, please refer to the class documentation for Unit_t.

const char * UnitKind_toString ( UnitKind_t uk )

Converts a unit code to a text string equivalent.

Parameters

uk	a value from the UnitKind_t enumeration

Returns: the name corresponding to the given unit code.

Note: For more information about the libSBML unit codes, please refer to the class documentation for Unit_t.

Warning: The string returned is a static data value. The caller does not own the returned string and is therefore not allowed to modify it.

Detailed Description

UnitKind_t

Public Member Functions

Member Function Documentation