Detailed Description

A token in an XML stream.

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 libSBML XML parser interface can read an XML file or data stream and convert the contents into tokens. The tokens represent items in the XML stream, either XML elements (start or end tags) or text that appears as content inside an element. The XMLToken_t class is libSBML's low-level representation of these entities.

Each XMLToken_t has the following information associated with it:

Qualified name: every XML element or XML attribute has a name (e.g., for the element <mytag>, the name is "mytag"), but this name may be qualified with a namespace (e.g., it may appear as <someNamespace:mytag> in the input). An XMLToken_t stores the name of a token, along with any namespace qualification present, through the use of an XMLTriple_t object. This object stores the bare name of the element, its XML namespace prefix (if any), and the XML namespace with which that prefix is associated.
Namespaces: An XML token can have one or more XML namespaces associated with it. These namespaces may be specified explicitly on the element or inherited from parent elements. In libSBML, a list of namespaces is stored in an XMLNamespaces_t object. An XMLToken_t possesses a field for storing an XMLNamespaces_t object.
Attributes: XML elements can have attributes associated with them, and these attributes can have values assigned to them. The set of attribute-value pairs is stored in an XMLAttributes_t object stored in an XMLToken_t object. (Note: only elements can have attributes—text blocks cannot have them in XML.)
Line number: the line number in the input where the token appears.
Column number: the column number in the input where the token appears.

The XMLToken_t class serves as base class for XMLNode_t. XML lends itself to a tree-structured representation, and in libSBML, the nodes in an XML document tree are XMLNode_t objects. Most higher-level libSBML classes and methods that offer XML-level functionality (such as the methods on SBase_t for interacting with annotations) work with XMLNode_t objects rather than XMLToken_t objects directly.

See also: XMLNode_t; XMLTriple_t; XMLAttributes_t; XMLNamespaces_t

Examples:: addingEvidenceCodes_2.c.

Public Member Functions
LIBLAX_EXTERN int	XMLToken_addAttr (XMLToken_t token, const char name, const char *value)
	Adds an attribute with the given local name to the attribute set in this XMLToken_t. More...

LIBLAX_EXTERN int	XMLToken_addAttrWithNS (XMLToken_t token, const char name, const char value, const char namespaceURI, const char *prefix)
	Adds an attribute with a prefix and namespace URI to the attribute set in this XMLToken_t. More...

LIBLAX_EXTERN int	XMLToken_addAttrWithTriple (XMLToken_t token, const XMLTriple_t triple, const char *value)
	Adds an attribute with the given XMLTriple_t/value pair to the attribute set in this XMLToken_t. More...

LIBLAX_EXTERN int	XMLToken_addNamespace (XMLToken_t token, const char uri, const char *prefix)
	Appends an XML namespace prefix and URI pair to this XMLToken_t. More...

LIBLAX_EXTERN int	XMLToken_append (XMLToken_t token, const char text)
	Appends characters to this XML text content. More...

LIBLAX_EXTERN int	XMLToken_clearAttributes (XMLToken_t *token)
	Clears (deletes) all attributes in this XMLToken_t. More...

LIBLAX_EXTERN int	XMLToken_clearNamespaces (XMLToken_t *token)
	Clears (deletes) all XML namespace declarations in the XMLNamespaces_t of this XMLNode_t. More...

LIBLAX_EXTERN XMLToken_t *	XMLToken_clone (const XMLToken_t *token)
	Creates a deep copy of the given XMLToken_t structure. More...

LIBLAX_EXTERN XMLToken_t *	XMLToken_create (void)
	Creates a new empty XMLToken_t structure and returns a pointer to it. More...

LIBLAX_EXTERN XMLToken_t *	XMLToken_createWithText (const char *text)
	Creates a text XMLToken_t structure. More...

LIBLAX_EXTERN XMLToken_t *	XMLToken_createWithTriple (const XMLTriple_t *triple)
	Creates a new end element XMLToken_t structure with XMLTriple_t structure set and returns a pointer to it. More...

LIBLAX_EXTERN XMLToken_t *	XMLToken_createWithTripleAttr (const XMLTriple_t triple, const XMLAttributes_t attr)
	Creates a new start element XMLToken_t structure with XMLTriple_t and XMLAttributes_t structures set and returns a pointer to it. More...

LIBLAX_EXTERN XMLToken_t *	XMLToken_createWithTripleAttrNS (const XMLTriple_t triple, const XMLAttributes_t attr, const XMLNamespaces_t *ns)
	Creates a new start element XMLToken_t structure with XMLTriple_t, XMLAttributes_t and XMLNamespaces_t structures set and returns a pointer to it. More...

LIBLAX_EXTERN void	XMLToken_free (XMLToken_t *token)
	Destroys this XMLToken_t structure. More...

LIBLAX_EXTERN const XMLAttributes_t *	XMLToken_getAttributes (const XMLToken_t *token)
	Returns the attributes of this element. More...

LIBLAX_EXTERN int	XMLToken_getAttributesLength (const XMLToken_t *token)
	Return the number of attributes in the attributes set. More...

LIBLAX_EXTERN int	XMLToken_getAttrIndex (const XMLToken_t token, const char name, const char *uri)
	Return the index of an attribute with the given local name and namespace URI. More...

LIBLAX_EXTERN int	XMLToken_getAttrIndexByTriple (const XMLToken_t token, const XMLTriple_t triple)
	Return the index of an attribute with the given XMLTriple_t. More...

LIBLAX_EXTERN char *	XMLToken_getAttrName (const XMLToken_t *token, int index)
	Return the local name of an attribute in the attributes set in this XMLToken_t (by position). More...

LIBLAX_EXTERN char *	XMLToken_getAttrPrefix (const XMLToken_t *token, int index)
	Return the prefix of an attribute in the attribute set in this XMLToken_t (by position). More...

LIBLAX_EXTERN char *	XMLToken_getAttrPrefixedName (const XMLToken_t *token, int index)
	Return the prefixed name of an attribute in the attribute set in this XMLToken_t (by position). More...

LIBLAX_EXTERN char *	XMLToken_getAttrURI (const XMLToken_t *token, int index)
	Return the namespace URI of an attribute in the attribute set in this XMLToken_t (by position). More...

LIBLAX_EXTERN char *	XMLToken_getAttrValue (const XMLToken_t *token, int index)
	Return the value of an attribute in the attribute set in this XMLToken_t (by position). More...

LIBLAX_EXTERN char *	XMLToken_getAttrValueByName (const XMLToken_t token, const char name)
	Return a value of an attribute with the given local name (without namespace URI). More...

LIBLAX_EXTERN char *	XMLToken_getAttrValueByNS (const XMLToken_t token, const char name, const char *uri)
	Return a value of an attribute with the given local name and namespace URI. More...

LIBLAX_EXTERN char *	XMLToken_getAttrValueByTriple (const XMLToken_t token, const XMLTriple_t triple)
	Return a value of an attribute with the given XMLTriple_t. More...

LIBLAX_EXTERN const char *	XMLToken_getCharacters (const XMLToken_t *token)
	Returns the text of this element. More...

LIBLAX_EXTERN unsigned int	XMLToken_getColumn (const XMLToken_t *token)
	Returns the column at which this XMLToken_t structure occurred. More...

LIBLAX_EXTERN unsigned int	XMLToken_getLine (const XMLToken_t *token)
	Returns the line at which this XMLToken_t structure occurred. More...

LIBLAX_EXTERN const char *	XMLToken_getName (const XMLToken_t *token)
	Returns the (unqualified) name of this XML element. More...

LIBLAX_EXTERN int	XMLToken_getNamespaceIndex (const XMLToken_t token, const char uri)
	Look up the index of an XML namespace declaration by URI. More...

LIBLAX_EXTERN int	XMLToken_getNamespaceIndexByPrefix (const XMLToken_t token, const char prefix)
	Look up the index of an XML namespace declaration by `prefix`. More...

LIBLAX_EXTERN char *	XMLToken_getNamespacePrefix (const XMLToken_t *token, int index)
	Look up the prefix of an XML namespace declaration by position. More...

LIBLAX_EXTERN char *	XMLToken_getNamespacePrefixByURI (const XMLToken_t token, const char uri)
	Look up the prefix of an XML namespace declaration by its URI. More...

LIBLAX_EXTERN const XMLNamespaces_t *	XMLToken_getNamespaces (const XMLToken_t *token)
	Returns the XML namespace declarations for this XML element. More...

LIBLAX_EXTERN int	XMLToken_getNamespacesLength (const XMLToken_t *token)
	Returns the number of XML namespaces stored in the XMLNamespaces_t of this XMLNode_t. More...

LIBLAX_EXTERN char *	XMLToken_getNamespaceURI (const XMLToken_t *token, int index)
	Look up the URI of an XML namespace declaration by its position. More...

LIBLAX_EXTERN char *	XMLToken_getNamespaceURIByPrefix (const XMLToken_t token, const char prefix)
	Look up the URI of an XML namespace declaration by its prefix. More...

LIBLAX_EXTERN const char *	XMLToken_getPrefix (const XMLToken_t *token)
	Returns the namespace prefix of this XML element. More...

LIBLAX_EXTERN const char *	XMLToken_getURI (const XMLToken_t *token)
	Returns the namespace URI of this XML element. More...

LIBLAX_EXTERN int	XMLToken_hasAttr (const XMLToken_t *token, int index)
	Returns `1` (true) or `0` (false) depending on whether an attribute with the given index exists in the attribute set in this XMLToken_t. More...

LIBLAX_EXTERN int	XMLToken_hasAttrWithName (const XMLToken_t token, const char name)
	Returns `1` (true) or `0` (false) depending on whether an attribute with the given local name (without namespace URI) exists in the attribute set in this XMLToken_t. More...

LIBLAX_EXTERN int	XMLToken_hasAttrWithNS (const XMLToken_t token, const char name, const char *uri)
	Returns `1` (true) or `0` (false) depending on whether an attribute with the given local name and namespace URI exists in the attribute set in this XMLToken_t. More...

LIBLAX_EXTERN int	XMLToken_hasAttrWithTriple (const XMLToken_t token, const XMLTriple_t triple)
	Returns `1` (true) or `0` (false) depending on whether an attribute with the given XML triple exists in the attribute set in this XMLToken_t. More...

LIBLAX_EXTERN int	XMLToken_hasNamespaceNS (const XMLToken_t token, const char uri, const char *prefix)
	Returns `1` (true) or `0` (false) depending on whether an XML Namespace with the given uri/prefix pair is contained in the XMLNamespaces_t ofthis XMLToken_t. More...

LIBLAX_EXTERN int	XMLToken_hasNamespacePrefix (const XMLToken_t token, const char prefix)
	Returns `1` (true) or `0` (false) depending on whether an XML Namespace with the given prefix is contained in the XMLNamespaces_t of this XMLToken_t. More...

LIBLAX_EXTERN int	XMLToken_hasNamespaceURI (const XMLToken_t token, const char uri)
	Returns `1` (true) or `0` (false) depending on whether an XML Namespace with the given URI is contained in the XMLNamespaces_t of this XMLToken_t. More...

LIBLAX_EXTERN int	XMLToken_isAttributesEmpty (const XMLToken_t *token)
	Returns `1` (true) or `0` (false) depending on whether the attribute set in this XMLToken_t set is empty. More...

LIBLAX_EXTERN int	XMLToken_isElement (const XMLToken_t *token)
	Returns `1` (true) or `0` (false) depending on whether this XMLToken_t structure is an XML element. More...

LIBLAX_EXTERN int	XMLToken_isEnd (const XMLToken_t *token)
	Returns `1` (true) or `0` (false) depending on whether this XMLToken_t structure is an XML end element. More...

LIBLAX_EXTERN int	XMLToken_isEndFor (const XMLToken_t token, const XMLToken_t element)
	Returns `1` (true) or `0` (false) depending on whether this XMLToken_t structure is an XML end element for the given start element. More...

LIBLAX_EXTERN int	XMLToken_isEOF (const XMLToken_t *token)
	Returns `1` (true) or `0` (false) depending on whether this XMLToken_t structure is an end of file marker. More...

LIBLAX_EXTERN int	XMLToken_isNamespacesEmpty (const XMLToken_t *token)
	Returns `1` (true) or `0` (false) depending on whether the XMLNamespaces_t of this XMLToken_t is empty. More...

LIBLAX_EXTERN int	XMLToken_isStart (const XMLToken_t *token)
	Returns `1` (true) or `0` (false) depending on whether this XMLToken_t structure is an XML start element. More...

LIBLAX_EXTERN int	XMLToken_isText (const XMLToken_t *token)
	Returns `1` (true) or `0` (false) depending on whether this XMLToken_t structure is an XML text element. More...

LIBLAX_EXTERN int	XMLToken_removeAttr (XMLToken_t *token, int n)
	Removes an attribute with the given index from the attribute set in this XMLToken_t. More...

LIBLAX_EXTERN int	XMLToken_removeAttrByName (XMLToken_t token, const char name)
	Removes an attribute with the given local name (without namespace URI) from the attribute set in this XMLToken_t. More...

LIBLAX_EXTERN int	XMLToken_removeAttrByNS (XMLToken_t token, const char name, const char *uri)
	Removes an attribute with the given local name and namespace URI from the attribute set in this XMLToken_t. More...

LIBLAX_EXTERN int	XMLToken_removeAttrByTriple (XMLToken_t token, const XMLTriple_t triple)
	Removes an attribute with the given XMLTriple_t from the attribute set in this XMLToken_t. More...

LIBLAX_EXTERN int	XMLToken_removeNamespace (XMLToken_t *token, int index)
	Removes an XML Namespace stored in the given position of the XMLNamespaces_t of this XMLNode_t. More...

LIBLAX_EXTERN int	XMLToken_removeNamespaceByPrefix (XMLToken_t token, const char prefix)
	Removes an XML Namespace with the given prefix. More...

LIBLAX_EXTERN int	XMLToken_setAttributes (XMLToken_t token, const XMLAttributes_t attributes)
	Sets an XMLAttributes_t to this XMLToken_t. More...

LIBLAX_EXTERN int	XMLToken_setCharacters (XMLToken_t token, const char text)
	Sets characters of this XML text content. More...

LIBLAX_EXTERN int	XMLToken_setEnd (XMLToken_t *token)
	Declares this XML start element is also an end element. More...

LIBLAX_EXTERN int	XMLToken_setEOF (XMLToken_t *token)
	Declares this XMLToken_t structure is an end-of-file (input) marker. More...

LIBLAX_EXTERN int	XMLToken_setNamespaces (XMLToken_t token, const XMLNamespaces_t namespaces)
	Sets an XMLnamespaces_t to this XML element. More...

LIBLAX_EXTERN int	XMLToken_setTriple (XMLToken_t token, const XMLTriple_t triple)
	Sets the XMLTriple_t (name, uri and prefix) of this XML element. More...

LIBLAX_EXTERN int	XMLToken_unsetEnd (XMLToken_t *token)
	Declares this XML start/end element is no longer an end element. More...

Member Function Documentation

LIBLAX_EXTERN int XMLToken_addAttr	(	XMLToken_t *	token,
		const char *	name,
		const char *	value
	)

Adds an attribute with the given local name to the attribute set in this XMLToken_t.

(namespace URI and prefix are empty) Nothing will be done if this XMLToken_t is not a start element.

Parameters

token	XMLToken_t structure to which an attribute to be added.
name	a string, the local name of the attribute.
value	a string, the value of the attribute.

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:

Note: if the local name without namespace URI already exists in the attribute set, its value will be replaced.

LIBLAX_EXTERN int XMLToken_addAttrWithNS	(	XMLToken_t *	token,
		const char *	name,
		const char *	value,
		const char *	namespaceURI,
		const char *	prefix
	)

Adds an attribute with a prefix and namespace URI to the attribute set in this XMLToken_t.

Nothing will be done if this XMLToken_t is not a start element.

Parameters

token	XMLToken_t structure to which an attribute to be added.
name	a string, the local name of the attribute.
value	a string, the value of the attribute.
namespaceURI	a string, the namespace URI of the attribute.
prefix	a string, the prefix of the namespace.

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:

Note: If an attribute with the same name and XML namespace URI already exists on this XMLToken_t object, then the previous value will be replaced with the new value provided to this method.

LIBLAX_EXTERN int XMLToken_addAttrWithTriple	(	XMLToken_t *	token,
		const XMLTriple_t *	triple,
		const char *	value
	)

Adds an attribute with the given XMLTriple_t/value pair to the attribute set in this XMLToken_t.

Nothing will be done if this XMLToken_t is not a start element.

Parameters

token	XMLToken_t structure to which an attribute to be added.
triple	an XMLTriple_t, the XML triple of the attribute.
value	a string, the value of the attribute.

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:

Note: If an attribute with the same name and XML namespace URI already exists on this XMLToken_t object, then the previous value will be replaced with the new value provided to this method.

LIBLAX_EXTERN int XMLToken_addNamespace	(	XMLToken_t *	token,
		const char *	uri,
		const char *	prefix
	)

Appends an XML namespace prefix and URI pair to this XMLToken_t.

If there is an XML namespace with the given prefix in this XMLToken_t, then the existing XML namespace will be overwritten by the new one.

Nothing will be done if this XMLToken_t is not a start element.

Parameters

token	XMLToken_t structure to be queried.
uri	a string, the uri for the namespace.
prefix	a string, the prefix for the namespace.

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:

LIBLAX_EXTERN int XMLToken_append	(	XMLToken_t *	token,
		const char *	text
	)

Appends characters to this XML text content.

Parameters

token	XMLToken_t structure to be appended to.
text	string, characters to append.

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:

LIBLAX_EXTERN int XMLToken_clearAttributes ( XMLToken_t * token )

Clears (deletes) all attributes in this XMLToken_t.

Nothing will be done if this XMLToken_t is not a start element.

Parameters

token XMLToken_t structure from which attributes to be removed.

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:

LIBLAX_EXTERN int XMLToken_clearNamespaces ( XMLToken_t * token )

Clears (deletes) all XML namespace declarations in the XMLNamespaces_t of this XMLNode_t.

Nothing will be done if this XMLToken_t is not a start element.

Parameters

token XMLToken_t structure to be queried.

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:

LIBLAX_EXTERN XMLToken_t * XMLToken_clone ( const XMLToken_t * token )

Creates a deep copy of the given XMLToken_t structure.

Parameters

token the XMLToken_t structure to be copied.

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

LIBLAX_EXTERN XMLToken_t * XMLToken_create ( void )

Creates a new empty XMLToken_t structure and returns a pointer to it.

Returns: pointer to new XMLToken_t structure.

LIBLAX_EXTERN XMLToken_t * XMLToken_createWithText ( const char * text )

Creates a text XMLToken_t structure.

Parameters

text	a string, the text to be added to the XMLToken_t structure.

Returns: pointer to new XMLToken_t structure.

LIBLAX_EXTERN XMLToken_t * XMLToken_createWithTriple ( const XMLTriple_t * triple )

Creates a new end element XMLToken_t structure with XMLTriple_t structure set and returns a pointer to it.

Parameters

triple XMLTriple_t structure to be set.

Returns: pointer to new XMLToken_t structure.

LIBLAX_EXTERN XMLToken_t * XMLToken_createWithTripleAttr	(	const XMLTriple_t *	triple,
		const XMLAttributes_t *	attr
	)

Creates a new start element XMLToken_t structure with XMLTriple_t and XMLAttributes_t structures set and returns a pointer to it.

Parameters

triple	XMLTriple_t structure to be set.
attr	XMLAttributes_t structure to be set.

Returns: pointer to new XMLToken_t structure.

Examples:: addingEvidenceCodes_2.c.

LIBLAX_EXTERN XMLToken_t * XMLToken_createWithTripleAttrNS	(	const XMLTriple_t *	triple,
		const XMLAttributes_t *	attr,
		const XMLNamespaces_t *	ns
	)

Creates a new start element XMLToken_t structure with XMLTriple_t, XMLAttributes_t and XMLNamespaces_t structures set and returns a pointer to it.

Parameters

triple	XMLTriple_t structure to be set.
attr	XMLAttributes_t structure to be set.
ns	XMLNamespaces_t structure to be set.

Returns: pointer to new XMLToken_t structure.

Examples:: addingEvidenceCodes_2.c.

LIBLAX_EXTERN void XMLToken_free ( XMLToken_t * token )

Destroys this XMLToken_t structure.

Parameters

token XMLToken_t structure to be freed.

LIBLAX_EXTERN const XMLAttributes_t * XMLToken_getAttributes ( const XMLToken_t * token )

Returns the attributes of this element.

Parameters

token XMLToken_t structure to be queried.

Returns: the XMLAttributes_t of this XML element.

LIBLAX_EXTERN int XMLToken_getAttributesLength ( const XMLToken_t * token )

Return the number of attributes in the attributes set.

Parameters

token XMLToken_t structure to be queried.

Returns: the number of attributes in the attributes set in this XMLToken_t.

LIBLAX_EXTERN int XMLToken_getAttrIndex	(	const XMLToken_t *	token,
		const char *	name,
		const char *	uri
	)

Return the index of an attribute with the given local name and namespace URI.

Parameters

token	XMLToken_t structure to be queried.
name	a string, the local name of the attribute.
uri	a string, the namespace URI of the attribute.

Returns: the index of an attribute with the given local name and namespace URI, or -1 if not present.

LIBLAX_EXTERN int XMLToken_getAttrIndexByTriple	(	const XMLToken_t *	token,
		const XMLTriple_t *	triple
	)

Return the index of an attribute with the given XMLTriple_t.

Parameters

token	XMLToken_t structure to be queried.
triple	an XMLTriple_t, the XML triple of the attribute for which the index is being sought.

Returns: the index of an attribute with the given XMLTriple_t, or -1 if not present.

LIBLAX_EXTERN char * XMLToken_getAttrName	(	const XMLToken_t *	token,
		int	index
	)

Return the local name of an attribute in the attributes set in this XMLToken_t (by position).

Parameters

token	XMLToken_t structure to be queried.
index	an integer, the position of the attribute whose local name is being sought.

Returns: the local name of an attribute in this list (by position).

Note: If index is out of range, an empty string will be returned. Use XMLToken_hasAttr() to test for the attribute existence.

LIBLAX_EXTERN char * XMLToken_getAttrPrefix	(	const XMLToken_t *	token,
		int	index
	)

Return the prefix of an attribute in the attribute set in this XMLToken_t (by position).

Parameters

token	XMLToken_t structure to be queried.
index	an integer, the position of the attribute whose prefix is required.

Returns: the namespace prefix of an attribute in the attribute set (by position).

Note: If index is out of range, an empty string will be returned. Use XMLToken_hasAttr() to test for the attribute existence.

LIBLAX_EXTERN char * XMLToken_getAttrPrefixedName	(	const XMLToken_t *	token,
		int	index
	)

Return the prefixed name of an attribute in the attribute set in this XMLToken_t (by position).

Parameters

token	XMLToken_t structure to be queried.
index	an integer, the position of the attribute whose prefixed name is being sought.

Returns: the prefixed name of an attribute in the attribute set (by position).

Note: If index is out of range, an empty string will be returned. Use XMLToken_hasAttr() to test for attribute existence.

LIBLAX_EXTERN char * XMLToken_getAttrURI	(	const XMLToken_t *	token,
		int	index
	)

Return the namespace URI of an attribute in the attribute set in this XMLToken_t (by position).

Parameters

token	XMLToken_t structure to be queried.
index	an integer, the position of the attribute whose namespace URI is being sought.

Returns: the namespace URI of an attribute in the attribute set (by position).

Note: If index is out of range, an empty string will be returned. Use XMLToken_hasAttr(index) to test for attribute existence.

LIBLAX_EXTERN char * XMLToken_getAttrValue	(	const XMLToken_t *	token,
		int	index
	)

Return the value of an attribute in the attribute set in this XMLToken_t (by position).

Parameters

token	XMLToken_t structure to be queried.
index	an integer, the position of the attribute whose value is required.

Returns: the value of an attribute in the attribute set (by position).

Note: If index is out of range, an empty string will be returned. Use XMLToken_hasAttr() to test for attribute existence.

LIBLAX_EXTERN char * XMLToken_getAttrValueByName	(	const XMLToken_t *	token,
		const char *	name
	)

Return a value of an attribute with the given local name (without namespace URI).

Parameters

token	XMLToken_t structure to be queried.
name	a string, the local name of the attribute whose value is being sought.

Returns: The attribute value as a string.

Note: If an attribute with the given local name (without namespace URI) does not exist, an empty string will be returned. Use XMLToken_hasAttr() to test for attribute existence.

LIBLAX_EXTERN char * XMLToken_getAttrValueByNS	(	const XMLToken_t *	token,
		const char *	name,
		const char *	uri
	)

Return a value of an attribute with the given local name and namespace URI.

Parameters

token	XMLToken_t structure to be queried.
name	a string, the local name of the attribute whose value is being sought.
uri	a string, the namespace URI of the attribute.

Returns: The attribute value as a string.

Note: If an attribute with the given local name and namespace URI does not exist, an empty string will be returned. Use XMLToken_hasAttr(name, uri) to test for attribute existence.

LIBLAX_EXTERN char * XMLToken_getAttrValueByTriple	(	const XMLToken_t *	token,
		const XMLTriple_t *	triple
	)

Return a value of an attribute with the given XMLTriple_t.

Parameters

token	XMLToken_t structure to be queried.
triple	an XMLTriple_t, the XML triple of the attribute whose value is being sought.

Returns: The attribute value as a string.

Note: If an attribute with the given XMLTriple_t does not exist, an empty string will be returned. Use XMLToken_hasAttr() to test for attribute existence.

LIBLAX_EXTERN const char * XMLToken_getCharacters ( const XMLToken_t * token )

Returns the text of this element.

Parameters

token XMLToken_t structure to be queried.

Returns: the characters of this XML text.

LIBLAX_EXTERN unsigned int XMLToken_getColumn ( const XMLToken_t * token )

Returns the column at which this XMLToken_t structure occurred.

Parameters

token XMLToken_t structure to be queried.

Returns: the column at which this XMLToken_t structure occurred.

LIBLAX_EXTERN unsigned int XMLToken_getLine ( const XMLToken_t * token )

Returns the line at which this XMLToken_t structure occurred.

Parameters

token XMLToken_t structure to be queried.

Returns: the line at which this XMLToken_t structure occurred.

LIBLAX_EXTERN const char * XMLToken_getName ( const XMLToken_t * token )

Returns the (unqualified) name of this XML element.

Parameters

token XMLToken_t structure to be queried.

Returns: the (unqualified) name of this XML element.

LIBLAX_EXTERN int XMLToken_getNamespaceIndex	(	const XMLToken_t *	token,
		const char *	uri
	)

Look up the index of an XML namespace declaration by URI.

Parameters

token	XMLToken_t structure to be queried.
uri	a string, uri of the required namespace.

Returns: the index of the given declaration, or -1 if not present.

LIBLAX_EXTERN int XMLToken_getNamespaceIndexByPrefix	(	const XMLToken_t *	token,
		const char *	prefix
	)

Look up the index of an XML namespace declaration by prefix.

Parameters

token	XMLToken_t structure to be queried.
prefix	a string, prefix of the required namespace.

Returns: the index of the given declaration, or -1 if not present.

LIBLAX_EXTERN char * XMLToken_getNamespacePrefix	(	const XMLToken_t *	token,
		int	index
	)

Look up the prefix of an XML namespace declaration by position.

Callers should use getNamespacesLength() to find out how many namespaces are stored in the XMLNamespaces_t.

Parameters

token	XMLToken_t structure to be queried.
index	an integer, position of the removed namespace.

Returns: the prefix of an XML namespace declaration in the XMLNamespaces_t (by position).

Note: returned char* should be freed with safe_free() by the caller.

LIBLAX_EXTERN char * XMLToken_getNamespacePrefixByURI	(	const XMLToken_t *	token,
		const char *	uri
	)

Look up the prefix of an XML namespace declaration by its URI.

Parameters

token	XMLToken_t structure to be queried.
uri	a string, uri of the required namespace.

Returns: the prefix of an XML namespace declaration given its URI.

Note: returned char* should be freed with safe_free() by the caller.

LIBLAX_EXTERN const XMLNamespaces_t * XMLToken_getNamespaces ( const XMLToken_t * token )

Returns the XML namespace declarations for this XML element.

Parameters

token XMLToken_t structure to be queried.

Returns: the XML namespace declarations for this XML element.

LIBLAX_EXTERN int XMLToken_getNamespacesLength ( const XMLToken_t * token )

Returns the number of XML namespaces stored in the XMLNamespaces_t of this XMLNode_t.

Parameters

token XMLToken_t structure to be queried.

Returns: the number of namespaces in this list.

LIBLAX_EXTERN char * XMLToken_getNamespaceURI	(	const XMLToken_t *	token,
		int	index
	)

Look up the URI of an XML namespace declaration by its position.

Parameters

token	XMLToken_t structure to be queried.
index	an integer, position of the removed namespace.

Returns: the URI of an XML namespace declaration in the XMLNamespaces_t (by position).

Note: returned char* should be freed with safe_free() by the caller.

LIBLAX_EXTERN char * XMLToken_getNamespaceURIByPrefix	(	const XMLToken_t *	token,
		const char *	prefix
	)

Look up the URI of an XML namespace declaration by its prefix.

Parameters

token	XMLToken_t structure to be queried.
prefix	a string, prefix of the required namespace.

Returns: the URI of an XML namespace declaration given its prefix.

Note: returned char* should be freed with safe_free() by the caller.

LIBLAX_EXTERN const char * XMLToken_getPrefix ( const XMLToken_t * token )

Returns the namespace prefix of this XML element.

Parameters

token XMLToken_t structure to be queried.

Returns: the namespace prefix of this XML element.

Note: If no prefix exists, an empty string will be return.

LIBLAX_EXTERN const char * XMLToken_getURI ( const XMLToken_t * token )

Returns the namespace URI of this XML element.

Parameters

token XMLToken_t structure to be queried.

Returns: the namespace URI of this XML element.

LIBLAX_EXTERN int XMLToken_hasAttr	(	const XMLToken_t *	token,
		int	index
	)

Returns 1 (true) or 0 (false) depending on whether an attribute with the given index exists in the attribute set in this XMLToken_t.

Parameters

token	XMLToken_t structure to be queried.
index	an integer, the position of the attribute.

Returns: 1 (true) if an attribute with the given index exists in the attribute set in this XMLToken_t, 0 (false) otherwise.

LIBLAX_EXTERN int XMLToken_hasAttrWithName	(	const XMLToken_t *	token,
		const char *	name
	)

Returns 1 (true) or 0 (false) depending on whether an attribute with the given local name (without namespace URI) exists in the attribute set in this XMLToken_t.

Parameters

token	XMLToken_t structure to be queried.
name	a string, the local name of the attribute.

Returns: 1 (true) if an attribute with the given local name (without namespace URI) exists in the attribute set in this XMLToken_t, 0 (false) otherwise.

LIBLAX_EXTERN int XMLToken_hasAttrWithNS	(	const XMLToken_t *	token,
		const char *	name,
		const char *	uri
	)

Returns 1 (true) or 0 (false) depending on whether an attribute with the given local name and namespace URI exists in the attribute set in this XMLToken_t.

Parameters

token	XMLToken_t structure to be queried.
name	a string, the local name of the attribute.
uri	a string, the namespace URI of the attribute.

Returns: 1 (true) if an attribute with the given local name and namespace URI exists in the attribute set in this XMLToken_t, 0 (false) otherwise.

LIBLAX_EXTERN int XMLToken_hasAttrWithTriple	(	const XMLToken_t *	token,
		const XMLTriple_t *	triple
	)

Returns 1 (true) or 0 (false) depending on whether an attribute with the given XML triple exists in the attribute set in this XMLToken_t.

Parameters

token	XMLToken_t structure to be queried.
triple	an XMLTriple_t, the XML triple of the attribute.

Returns: 1 (true) if an attribute with the given XML triple exists in the attribute set in this XMLToken_t, 0 (false) otherwise.

LIBLAX_EXTERN int XMLToken_hasNamespaceNS	(	const XMLToken_t *	token,
		const char *	uri,
		const char *	prefix
	)

Returns 1 (true) or 0 (false) depending on whether an XML Namespace with the given uri/prefix pair is contained in the XMLNamespaces_t ofthis XMLToken_t.

Parameters

token	XMLToken_t structure to be queried.
uri	a string, the uri for the namespace.
prefix	a string, the prefix for the namespace.

Returns: 1 (true) if an XML Namespace with the given uri/prefix pair is contained in the XMLNamespaces_t of this XMLToken_t, 0 (false) otherwise.

LIBLAX_EXTERN int XMLToken_hasNamespacePrefix	(	const XMLToken_t *	token,
		const char *	prefix
	)

Returns 1 (true) or 0 (false) depending on whether an XML Namespace with the given prefix is contained in the XMLNamespaces_t of this XMLToken_t.

Parameters

token	XMLToken_t structure to be queried.
prefix	a string, the prefix for the namespace.

Returns: 1 (true) if an XML Namespace with the given URI is contained in the XMLNamespaces_t of this XMLToken_t, 0 (false) otherwise.

LIBLAX_EXTERN int XMLToken_hasNamespaceURI	(	const XMLToken_t *	token,
		const char *	uri
	)

Returns 1 (true) or 0 (false) depending on whether an XML Namespace with the given URI is contained in the XMLNamespaces_t of this XMLToken_t.

Parameters

token	XMLToken_t structure to be queried.
uri	a string, the uri for the namespace.

Returns: 1 (true) if an XML Namespace with the given URI is contained in the XMLNamespaces_t of this XMLToken_t, 0 (false) otherwise.

LIBLAX_EXTERN int XMLToken_isAttributesEmpty ( const XMLToken_t * token )

Returns 1 (true) or 0 (false) depending on whether the attribute set in this XMLToken_t set is empty.

Parameters

token XMLToken_t structure to be queried.

Returns: 1 (true) if the attribute set in this XMLToken_t is empty, 0 (false) otherwise.

LIBLAX_EXTERN int XMLToken_isElement ( const XMLToken_t * token )

Returns 1 (true) or 0 (false) depending on whether this XMLToken_t structure is an XML element.

Parameters

token XMLToken_t structure to be queried.

Returns: 1 (true) if this XMLToken_t structure is an XML element, 0 (false) otherwise.

LIBLAX_EXTERN int XMLToken_isEnd ( const XMLToken_t * token )

Returns 1 (true) or 0 (false) depending on whether this XMLToken_t structure is an XML end element.

Parameters

token XMLToken_t structure to be queried.

Returns: 1 (true) if this XMLToken_t structure is an XML end element, 0 (false) otherwise.

LIBLAX_EXTERN int XMLToken_isEndFor	(	const XMLToken_t *	token,
		const XMLToken_t *	element
	)

Returns 1 (true) or 0 (false) depending on whether this XMLToken_t structure is an XML end element for the given start element.

Parameters

token	XMLToken_t structure to be queried.
element	XMLToken_t structure, element for which query is made.

Returns: 1 (true) if this XMLToken_t structure is an XML end element for the given XMLToken_t structure start element, 0 (false) otherwise.

LIBLAX_EXTERN int XMLToken_isEOF ( const XMLToken_t * token )

Returns 1 (true) or 0 (false) depending on whether this XMLToken_t structure is an end of file marker.

Parameters

token XMLToken_t structure to be queried.

Returns: 1 (true) if this XMLToken_t structure is an end of file (input) marker, 0 (false) otherwise.

LIBLAX_EXTERN int XMLToken_isNamespacesEmpty ( const XMLToken_t * token )

Returns 1 (true) or 0 (false) depending on whether the XMLNamespaces_t of this XMLToken_t is empty.

Parameters

token XMLToken_t structure to be queried.

Returns: 1 (true) if the XMLNamespaces_t of this XMLToken_t is empty, 0 (false) otherwise.

LIBLAX_EXTERN int XMLToken_isStart ( const XMLToken_t * token )

Returns 1 (true) or 0 (false) depending on whether this XMLToken_t structure is an XML start element.

Parameters

token XMLToken_t structure to be queried.

Returns: true if this XMLToken_t structure is an XML start element, false otherwise.

LIBLAX_EXTERN int XMLToken_isText ( const XMLToken_t * token )

Returns 1 (true) or 0 (false) depending on whether this XMLToken_t structure is an XML text element.

Parameters

token XMLToken_t structure to be queried.

Returns: 1 (true) if this XMLToken_t structure is an XML text element, 0 (false) otherwise.

LIBLAX_EXTERN int XMLToken_removeAttr	(	XMLToken_t *	token,
		int	n
	)

Removes an attribute with the given index from the attribute set in this XMLToken_t.

Nothing will be done if this XMLToken_t is not a start element.

Parameters

token	XMLToken_t structure from which an attribute to be removed.
n	an integer the index of the resource to be deleted.

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:

LIBLAX_EXTERN int XMLToken_removeAttrByName	(	XMLToken_t *	token,
		const char *	name
	)

Removes an attribute with the given local name (without namespace URI) from the attribute set in this XMLToken_t.

Nothing will be done if this XMLToken_t is not a start element.

Parameters

token	XMLToken_t structure from which an attribute to be removed.
name	a string, the local name of the attribute.

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:

LIBLAX_EXTERN int XMLToken_removeAttrByNS	(	XMLToken_t *	token,
		const char *	name,
		const char *	uri
	)

Removes an attribute with the given local name and namespace URI from the attribute set in this XMLToken_t.

Nothing will be done if this XMLToken_t is not a start element.

Parameters

token	XMLToken_t structure from which an attribute to be removed.
name	a string, the local name of the attribute.
uri	a string, the namespace URI of the attribute.

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:

LIBLAX_EXTERN int XMLToken_removeAttrByTriple	(	XMLToken_t *	token,
		const XMLTriple_t *	triple
	)

Removes an attribute with the given XMLTriple_t from the attribute set in this XMLToken_t.

Nothing will be done if this XMLToken_t is not a start element.

Parameters

token	XMLToken_t structure from which an attribute to be removed.
triple	an XMLTriple_t, the XML triple of the attribute.

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:

LIBLAX_EXTERN int XMLToken_removeNamespace	(	XMLToken_t *	token,
		int	index
	)

Removes an XML Namespace stored in the given position of the XMLNamespaces_t of this XMLNode_t.

Nothing will be done if this XMLToken_t is not a start element.

Parameters

token	XMLToken_t structure to be queried.
index	an integer, position of the removed namespace.

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:

LIBLAX_EXTERN int XMLToken_removeNamespaceByPrefix	(	XMLToken_t *	token,
		const char *	prefix
	)

Removes an XML Namespace with the given prefix.

Nothing will be done if this XMLToken_t is not a start element.

Parameters

token	XMLToken_t structure to be queried.
prefix	a string, prefix of the required namespace.

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:

LIBLAX_EXTERN int XMLToken_setAttributes	(	XMLToken_t *	token,
		const XMLAttributes_t *	attributes
	)

Sets an XMLAttributes_t to this XMLToken_t.

Nothing will be done if this XMLToken_t is not a start element.

Parameters

token	XMLToken_t structure to be set.
attributes	XMLAttributes_t to be set to this XMLToken_t.

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:

Note: This function replaces the existing XMLAttributes_t with the new one.

LIBLAX_EXTERN int XMLToken_setCharacters	(	XMLToken_t *	token,
		const char *	text
	)

Sets characters of this XML text content.

Parameters

token	XMLToken_t structure whose characters to set.
text	string, characters to 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:

LIBLAX_EXTERN int XMLToken_setEnd ( XMLToken_t * token )

Declares this XML start element is also an end element.

Parameters

token XMLToken_t structure 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:

Examples:: addingEvidenceCodes_2.c.

LIBLAX_EXTERN int XMLToken_setEOF ( XMLToken_t * token )

Declares this XMLToken_t structure is an end-of-file (input) marker.

Parameters

token XMLToken_t structure 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:

LIBLAX_EXTERN int XMLToken_setNamespaces	(	XMLToken_t *	token,
		const XMLNamespaces_t *	namespaces
	)

Sets an XMLnamespaces_t to this XML element.

Nothing will be done if this XMLToken_t is not a start element.

Parameters

token	XMLToken_t structure to be queried.
namespaces	XMLNamespaces_t to be set to this XMLToken_t.

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:

Note: This function replaces the existing XMLNamespaces_t with the new one.

LIBLAX_EXTERN int XMLToken_setTriple	(	XMLToken_t *	token,
		const XMLTriple_t *	triple
	)

Sets the XMLTriple_t (name, uri and prefix) of this XML element.

Nothing will be done if this XML element is a text node.

Parameters

token	XMLToken_t structure to be queried.
triple	an XMLTriple_t, the XML triple to be set to this XML element.

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:

LIBLAX_EXTERN int XMLToken_unsetEnd ( XMLToken_t * token )

Declares this XML start/end element is no longer an end element.

Parameters

token XMLToken_t structure 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:

Detailed Description

Public Member Functions

Member Function Documentation