libSBML C++ API  5.18.0
XMLAttributes Class Reference

Detailed Description

A list of attributes on an XML element.

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.

In libSBML's XML interface layer, attributes on an element are stored as a list of values kept in an XMLAttributes object. XMLAttributes has methods for adding and removing individual attributes as well as performing other actions on the list of attributes. Classes in libSBML that represent nodes in an XML document (i.e., XMLNode and its parent class, XMLToken) use XMLAttributes objects to manage attributes on XML elements.

Attributes on an XML element can be written in one of two forms:

  • name="value"
  • prefix:name="value"

An attribute in XML must always have a value, and the value must always be a quoted string; i.e., it is always name="value" and not name=value. An empty value is represented simply as an empty string; i.e., name="".

In cases when a prefix is provided with an attribute name, general XML validity rules require that the prefix is an XML namespace prefix that has been declared somewhere else (possibly as an another attribute on the same element). However, the XMLAttributes class does not test for the proper existence or declaration of XML namespaces—callers must arrange to do this themselves in some other way. This class only provides facilities for tracking and manipulating attributes and their prefix/URI/name/value components.

Note
Note that although XMLAttributes provides operations that can manipulate attributes based on a numerical index, XML attributes are in fact unordered when they appear in files and data streams. The XMLAttributes class provides some list-like facilities, but it is only for the convenience of callers. (For example, it permits callers to loop across all attributes more easily.) Users should keep in mind that the order in which attributes are stored in XMLAttributes objects has no real impact on the order in which the attributes are read or written from an XML file or data stream.
See also
XMLTriple
XMLNode
XMLToken
Examples:
addingEvidenceCodes_2.cpp, and createExampleSBML.cpp.

Public Member Functions

int add (const std::string &name, const std::string &value, const std::string namespaceURI="", const std::string prefix="")
 Adds an attribute to this list of attributes. More...
 
int add (const XMLTriple &triple, const std::string &value)
 Adds an attribute to this list of attributes. More...
 
int clear ()
 Removes all attributes in this XMLAttributes object. More...
 
XMLAttributesclone () const
 Creates and returns a deep copy of this XMLAttributes object. More...
 
int getIndex (const std::string &name) const
 Returns the index of an attribute having a given name. More...
 
int getIndex (const std::string &name, const std::string &uri) const
 Returns the index of the attribute having a given name and XML namespace URI. More...
 
int getIndex (const XMLTriple &triple) const
 Returns the index of the attribute defined by the given XMLTriple object. More...
 
int getLength () const
 Returns the number of attributes in this list of attributes. More...
 
std::string getName (int index) const
 Returns the name of the nth attribute in this list of attributes. More...
 
int getNumAttributes () const
 Returns the number of attributes in this list of attributes. More...
 
std::string getPrefix (int index) const
 Returns the namespace prefix of the nth attribute in this attribute set. More...
 
std::string getPrefixedName (int index) const
 Returns the prefix name of the nth attribute in this attribute set. More...
 
std::string getURI (int index) const
 Returns the XML namespace URI of the nth attribute in this attribute set. More...
 
std::string getValue (int index) const
 Returns the value of the nth attribute in this list of attributes. More...
 
std::string getValue (const std::string &name) const
 Returns a named attribute's value. More...
 
std::string getValue (const std::string &name, const std::string &uri) const
 Returns a named attribute's value. More...
 
std::string getValue (const XMLTriple &triple) const
 Return the value of an attribute described by a given XMLTriple object. More...
 
bool hasAttribute (int index) const
 Returns true if an attribute exists at a given index. More...
 
bool hasAttribute (const std::string &name, const std::string uri="") const
 Returns true if an attribute with a given name and namespace URI exists. More...
 
bool hasAttribute (const XMLTriple &triple) const
 Returns true if an attribute with the given properties exists. More...
 
bool isEmpty () const
 Returns true if this list of attributes is empty. More...
 
XMLAttributesoperator= (const XMLAttributes &rhs)
 Assignment operator for XMLAttributes. More...
 
bool readInto (const std::string &name, bool &value, XMLErrorLog *log=NULL, bool required=false, const unsigned int line=0, const unsigned int column=0) const
 Interprets an attribute as a Boolean value. More...
 
bool readInto (const XMLTriple &triple, bool &value, XMLErrorLog *log=NULL, bool required=false, const unsigned int line=0, const unsigned int column=0) const
 Interprets an attribute as a Boolean value. More...
 
bool readInto (const std::string &name, double &value, XMLErrorLog *log=NULL, bool required=false, const unsigned int line=0, const unsigned int column=0) const
 Interprets an attribute as a double value. More...
 
bool readInto (const XMLTriple &triple, double &value, XMLErrorLog *log=NULL, bool required=false, const unsigned int line=0, const unsigned int column=0) const
 Interprets an attribute as a double value. More...
 
bool readInto (const std::string &name, long &value, XMLErrorLog *log=NULL, bool required=false, const unsigned int line=0, const unsigned int column=0) const
 Interprets an attribute as a long integer value. More...
 
bool readInto (const XMLTriple &triple, long &value, XMLErrorLog *log=NULL, bool required=false, const unsigned int line=0, const unsigned int column=0) const
 Interprets an attribute as a long integer value. More...
 
bool readInto (const std::string &name, int &value, XMLErrorLog *log=NULL, bool required=false, const unsigned int line=0, const unsigned int column=0) const
 Interprets an attribute as a int value. More...
 
bool readInto (const XMLTriple &triple, int &value, XMLErrorLog *log=NULL, bool required=false, const unsigned int line=0, const unsigned int column=0) const
 Interprets an attribute as a int value. More...
 
bool readInto (const std::string &name, unsigned int &value, XMLErrorLog *log=NULL, bool required=false, const unsigned int line=0, const unsigned int column=0) const
 Interprets an attribute as a unsigned int value. More...
 
bool readInto (const XMLTriple &triple, unsigned int &value, XMLErrorLog *log=NULL, bool required=false, const unsigned int line=0, const unsigned int column=0) const
 Interprets an attribute as a unsigned int value. More...
 
bool readInto (const std::string &name, std::string &value, XMLErrorLog *log=NULL, bool required=false, const unsigned int line=0, const unsigned int column=0) const
 Interprets an attribute as a string value. More...
 
bool readInto (const XMLTriple &triple, std::string &value, XMLErrorLog *log=NULL, bool required=false, const unsigned int line=0, const unsigned int column=0) const
 Interprets an attribute as a string value. More...
 
int remove (int n)
 Removes the nth attribute from this list of attributes. More...
 
int remove (const std::string &name, const std::string uri="")
 Removes a named attribute from this list of attributes. More...
 
int remove (const XMLTriple &triple)
 Removes a specific attribute from this list of attributes. More...
 
 XMLAttributes ()
 Creates a new, empty XMLAttributes object. More...
 
 XMLAttributes (const XMLAttributes &orig)
 Copy constructor; creates a copy of this XMLAttributes object. More...
 
virtual ~XMLAttributes ()
 Destroys this XMLAttributes object. More...
 

Constructor & Destructor Documentation

XMLAttributes::XMLAttributes ( )

Creates a new, empty XMLAttributes object.

XMLAttributes::~XMLAttributes ( )
virtual

Destroys this XMLAttributes object.

XMLAttributes::XMLAttributes ( const XMLAttributes orig)

Copy constructor; creates a copy of this XMLAttributes object.

orig the XMLAttributes object to copy.

Member Function Documentation

int XMLAttributes::add ( const std::string &  name,
const std::string &  value,
const std::string  namespaceURI = "",
const std::string  prefix = "" 
)

Adds an attribute to this list of attributes.

Some explanations are in order about the behavior of XMLAttributes with respect to namespace prefixes and namespace URIs. XMLAttributes does not verify the consistency of different uses of an XML namespace and the prefix used to refer to it in a given context. It cannot, because the prefix used for a given XML namespace in an XML document may intentionally be different on different elements in the document. Consequently, callers need to manage their own prefix-to-namespace mappings, and need to ensure that the desired prefix is used in any given context.

When called with attribute names, prefixes and namespace URIs, XMLAttributes pays attention to the namespace URIs and not the prefixes: a match is established by a combination of attribute name and namespace URI, and if on different occasions a different prefix is used for the same name/namespace combination, the prefix associated with the namespace on that attribute is overwritten.

Some examples will hopefully clarify this. Here are the results of a sequence of calls to the XMLAttributes add methods with different argument combinations. First, we create the object and add one attribute:

att->add("myattribute", "1", "myuri");

The above adds an attribute named myattribute in the namespace myuri, and with the attribute value 1. No namespace prefix is associated with the attribute (but the attribute is recorded to exist in the namespace myuri). If this attribute object were written out in XML, it would look like the following (and note that, since no namespace prefix was assigned, none is written out):

myattribute="1"
   

Continuing with this series of examples, suppose we invoke the add method again as follows:

att->add("myattribute", "2");

The above adds a new attribute also named myattribute, but in a different XML namespace: it is placed in the namespace with no URI, which is to say, the default XML namespace. Both attributes coexist on this XMLAttributes object; both can be independently retrieved.

att->add("myattribute", "3");

The code above now replaces the value of the attribute myattribute that resides in the default namespace. The attribute in the namespace myuri remains untouched.

att->add("myattribute", "4", "myuri");

The code above replaces the value of the attribute myattribute that resides in the myuri namespace. The attribute in the default namespace remains untouched.

att->add("myattribute", "5", "myuri", "foo");

The code above replaces the value of the attribute myattribute that resides in the myuri namespace. It also now assigns a namespace prefix, foo, to the attribute. The attribute myattribute in the default namespace remains untouched. If this XMLAttributes object were written out in XML, it would look like the following:

myattribute="3"
foo:myattribute="5"
   

Pressing on, now suppose we call the add method as follows:

att->add("myattribute", "6", "myuri", "bar");

The code above replaces the value of the attribute myattribute that resides in the myuri namespace. It also assigns a different prefix to the attribute. The namespace of the attribute remains myuri.

att->add("myattribute", "7", "", "foo");

The code above replaces the value of the attribute myattribute that resides in the default namespace. It also now assigns a namespace prefix, foo, to that attribute. If this XMLAttributes object were written out in XML, it would look like the following:

bar:myattribute="6"
foo:myattribute="7"
   
Parameters
namea string, the unprefixed name of the attribute.
valuea string, the value of the attribute.
namespaceURIa string, the namespace URI of the attribute.
prefixa string, a prefix for the XML 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 in the list of attributes held by this XMLAttributes object, then the previous value of that attribute will be replaced with the new value provided to this method.
See also
add(const XMLTriple& triple, const std::string& value)
getIndex(const std::string& name, const std::string& uri) const
getIndex(const XMLTriple& triple) const
hasAttribute(const std::string name, const std::string uri) const
hasAttribute(const XMLTriple& triple) const
Examples:
addingEvidenceCodes_2.cpp.
int XMLAttributes::add ( const XMLTriple triple,
const std::string &  value 
)

Adds an attribute to this list of attributes.

Some explanations are in order about the behavior of XMLAttributes with respect to namespace prefixes and namespace URIs. XMLAttributes does not verify the consistency of different uses of an XML namespace and the prefix used to refer to it in a given context. It cannot, because the prefix used for a given XML namespace in an XML document may intentionally be different on different elements in the document. Consequently, callers need to manage their own prefix-to-namespace mappings, and need to ensure that the desired prefix is used in any given context.

When called with attribute names, prefixes and namespace URIs, XMLAttributes pays attention to the namespace URIs and not the prefixes: a match is established by a combination of attribute name and namespace URI, and if on different occasions a different prefix is used for the same name/namespace combination, the prefix associated with the namespace on that attribute is overwritten.

Some examples will hopefully clarify this. Here are the results of a sequence of calls to the XMLAttributes add methods with different argument combinations. First, we create the object and add one attribute:

att->add("myattribute", "1", "myuri");

The above adds an attribute named myattribute in the namespace myuri, and with the attribute value 1. No namespace prefix is associated with the attribute (but the attribute is recorded to exist in the namespace myuri). If this attribute object were written out in XML, it would look like the following (and note that, since no namespace prefix was assigned, none is written out):

myattribute="1"
   

Continuing with this series of examples, suppose we invoke the add method again as follows:

att->add("myattribute", "2");

The above adds a new attribute also named myattribute, but in a different XML namespace: it is placed in the namespace with no URI, which is to say, the default XML namespace. Both attributes coexist on this XMLAttributes object; both can be independently retrieved.

att->add("myattribute", "3");

The code above now replaces the value of the attribute myattribute that resides in the default namespace. The attribute in the namespace myuri remains untouched.

att->add("myattribute", "4", "myuri");

The code above replaces the value of the attribute myattribute that resides in the myuri namespace. The attribute in the default namespace remains untouched.

att->add("myattribute", "5", "myuri", "foo");

The code above replaces the value of the attribute myattribute that resides in the myuri namespace. It also now assigns a namespace prefix, foo, to the attribute. The attribute myattribute in the default namespace remains untouched. If this XMLAttributes object were written out in XML, it would look like the following:

myattribute="3"
foo:myattribute="5"
   

Pressing on, now suppose we call the add method as follows:

att->add("myattribute", "6", "myuri", "bar");

The code above replaces the value of the attribute myattribute that resides in the myuri namespace. It also assigns a different prefix to the attribute. The namespace of the attribute remains myuri.

att->add("myattribute", "7", "", "foo");

The code above replaces the value of the attribute myattribute that resides in the default namespace. It also now assigns a namespace prefix, foo, to that attribute. If this XMLAttributes object were written out in XML, it would look like the following:

bar:myattribute="6"
foo:myattribute="7"
   
Parameters
triplean XMLTriple object describing the attribute to be added.
valuea 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 in the list of attributes held by this XMLAttributes object, then the previous value of that attribute will be replaced with the new value provided to this method.
See also
add(const std::string& name, const std::string& value, const std::string& namespaceURI, const std::string& prefix)
getIndex(const std::string& name, const std::string& uri) const
getIndex(const XMLTriple& triple) const
hasAttribute(const std::string name, const std::string uri) const
hasAttribute(const XMLTriple& triple) const
int XMLAttributes::clear ( )

Removes all attributes in this XMLAttributes object.

Returns
integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. This particular function only does one thing irrespective of user input or object state, and thus will only return a single value:
See also
remove(int n)
remove(const XMLTriple& triple)
remove(const std::string& name, const std::string& uri)
Examples:
addingEvidenceCodes_2.cpp.
XMLAttributes * XMLAttributes::clone ( ) const

Creates and returns a deep copy of this XMLAttributes object.

Returns
the (deep) copy of this XMLAttributes object.
int XMLAttributes::getIndex ( const std::string &  name) const

Returns the index of an attribute having a given name.

Note
This method does not check XML namespaces. Thus, if there are multiple attributes with the same local name but different namespaces, this method will return the first one found. Callers should use the more specific methods XMLAttributes::getIndex(const std::string& name, const std::string& uri) const or XMLAttributes::getIndex(const XMLTriple& triple) const to find attributes in particular namespaces.
Parameters
namea string, the name of the attribute whose index is begin sought.
Returns
the index of an attribute with the given local name, or -1 if no such attribute is present.
See also
hasAttribute(const std::string name, const std::string uri) const
hasAttribute(const XMLTriple& triple) const
int XMLAttributes::getIndex ( const std::string &  name,
const std::string &  uri 
) const

Returns the index of the attribute having a given name and XML namespace URI.

Parameters
namea string, the name of the attribute being sought.
uria string, the namespace URI of the attribute being sought.
Returns
the index of an attribute with the given local name and namespace URI, or -1 if no such attribute is present.
See also
hasAttribute(const std::string name, const std::string uri) const
hasAttribute(const XMLTriple& triple) const
int XMLAttributes::getIndex ( const XMLTriple triple) const

Returns the index of the attribute defined by the given XMLTriple object.

Parameters
triplean XMLTriple describing the attribute being sought.
Returns
the index of an attribute described by the given XMLTriple object, or -1 if no such attribute is present.
See also
hasAttribute(const std::string name, const std::string uri) const
hasAttribute(const XMLTriple& triple) const
int XMLAttributes::getLength ( ) const

Returns the number of attributes in this list of attributes.

Returns
the number of attributes contained in this XMLAttributes object.
std::string XMLAttributes::getName ( int  index) const

Returns the name of the nth attribute in this list of attributes.

Parameters
indexan integer, the position of the attribute whose name is being sought.
Returns
the local name of the nth attribute.
Note
If index is out of range, this method will return an empty string. Callers should use XMLAttributes::getLength() to check the number of attributes contained in this object or XMLAttributes::hasAttribute(int index) const to test for the existence of an attribute at a given position.
Note that although XMLAttributes provides operations that can manipulate attributes based on a numerical index, XML attributes are in fact unordered when they appear in files and data streams. The XMLAttributes class provides some list-like facilities, but it is only for the convenience of callers. (For example, it permits callers to loop across all attributes more easily.) Users should keep in mind that the order in which attributes are stored in XMLAttributes objects has no real impact on the order in which the attributes are read or written from an XML file or data stream.
See also
getLength()
hasAttribute(int index) const
int XMLAttributes::getNumAttributes ( ) const

Returns the number of attributes in this list of attributes.

This function is merely an alias of XMLAttributes::getLength() introduced for consistency with other libXML classes.

Returns
the number of attributes contained in this XMLAttributes object.
std::string XMLAttributes::getPrefix ( int  index) const

Returns the namespace prefix of the nth attribute in this attribute set.

Parameters
indexan integer, the position of the attribute whose namespace prefix is being sought.
Returns
the XML namespace prefix of the nth attribute.
Note
If index is out of range, this method will return an empty string. Callers should use XMLAttributes::getLength() to check the number of attributes contained in this object or XMLAttributes::hasAttribute(int index) const to test for the existence of an attribute at a given position.
Note that although XMLAttributes provides operations that can manipulate attributes based on a numerical index, XML attributes are in fact unordered when they appear in files and data streams. The XMLAttributes class provides some list-like facilities, but it is only for the convenience of callers. (For example, it permits callers to loop across all attributes more easily.) Users should keep in mind that the order in which attributes are stored in XMLAttributes objects has no real impact on the order in which the attributes are read or written from an XML file or data stream.
See also
getLength()
hasAttribute(int index) const
std::string XMLAttributes::getPrefixedName ( int  index) const

Returns the prefix name of the nth attribute in this attribute set.

Parameters
indexan integer, the position of the attribute whose prefixed name is being sought.
Returns
the prefixed name of the nth attribute.
Note
If index is out of range, this method will return an empty string. Callers should use XMLAttributes::getLength() to check the number of attributes contained in this object or XMLAttributes::hasAttribute(int index) const to test for the existence of an attribute at a given position.
Note that although XMLAttributes provides operations that can manipulate attributes based on a numerical index, XML attributes are in fact unordered when they appear in files and data streams. The XMLAttributes class provides some list-like facilities, but it is only for the convenience of callers. (For example, it permits callers to loop across all attributes more easily.) Users should keep in mind that the order in which attributes are stored in XMLAttributes objects has no real impact on the order in which the attributes are read or written from an XML file or data stream.
See also
getLength()
hasAttribute(int index) const
std::string XMLAttributes::getURI ( int  index) const

Returns the XML namespace URI of the nth attribute in this attribute set.

Parameters
indexan integer, the position of the attribute whose namespace URI is being sought.
Returns
the XML namespace URI of the nth attribute.
Note
If index is out of range, this method will return an empty string. Callers should use XMLAttributes::getLength() to check the number of attributes contained in this object or XMLAttributes::hasAttribute(int index) const to test for the existence of an attribute at a given position.
Note that although XMLAttributes provides operations that can manipulate attributes based on a numerical index, XML attributes are in fact unordered when they appear in files and data streams. The XMLAttributes class provides some list-like facilities, but it is only for the convenience of callers. (For example, it permits callers to loop across all attributes more easily.) Users should keep in mind that the order in which attributes are stored in XMLAttributes objects has no real impact on the order in which the attributes are read or written from an XML file or data stream.
See also
getLength()
hasAttribute(int index) const
std::string XMLAttributes::getValue ( int  index) const

Returns the value of the nth attribute in this list of attributes.

Parameters
indexan integer, the position of the attribute whose value is being sought.
Returns
the XML value of the nth attribute.
Note
If index is out of range, this method will return an empty string. Callers should use XMLAttributes::getLength() to check the number of attributes contained in this object or XMLAttributes::hasAttribute(int index) const to test for the existence of an attribute at a given position.
Note that although XMLAttributes provides operations that can manipulate attributes based on a numerical index, XML attributes are in fact unordered when they appear in files and data streams. The XMLAttributes class provides some list-like facilities, but it is only for the convenience of callers. (For example, it permits callers to loop across all attributes more easily.) Users should keep in mind that the order in which attributes are stored in XMLAttributes objects has no real impact on the order in which the attributes are read or written from an XML file or data stream.
See also
getLength()
hasAttribute(int index) const
std::string XMLAttributes::getValue ( const std::string &  name) const

Returns a named attribute's value.

Parameters
namea string, the unprefixed 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 does not exist in this XMLAttributes object, this method will return an empty string. Callers can use XMLAttributes::hasAttribute(const std::string name, const std::string uri) const to test for an attribute's existence. This method also does not check the XML namespace of the named attribute. Thus, if there are multiple attributes with the same local name but different namespaces, this method will return the value of the first such attribute found. Callers should use the more specific methods XMLAttributes::getIndex(const std::string& name, const std::string& uri) const or XMLAttributes::getIndex(const XMLTriple& triple) const to find attributes in particular namespaces.
See also
hasAttribute(const std::string name, const std::string uri) const
hasAttribute(const XMLTriple& triple) const
std::string XMLAttributes::getValue ( const std::string &  name,
const std::string &  uri 
) const

Returns a named attribute's value.

Parameters
namea string, the name of the attribute whose value is being sought.
uria string, the XML namespace URI of the attribute.
Returns
The attribute value as a string.
Note
If an attribute with the given name and namespace uri does not exist in this XMLAttributes object, this method will return an empty string. Callers can use XMLAttributes::hasAttribute(const std::string name, const std::string uri) const to test for an attribute's existence.
See also
hasAttribute(const std::string name, const std::string uri) const
hasAttribute(const XMLTriple& triple) const
std::string XMLAttributes::getValue ( const XMLTriple triple) const

Return the value of an attribute described by a given XMLTriple object.

Parameters
triplean XMLTriple describing the attribute whose value is being sought.
Returns
The attribute value as a string.
Note
If an attribute with the properties given by triple does not exist in this XMLAttributes object, this method will return an empty string. Callers can use XMLAttributes::hasAttribute(const std::string name, const std::string uri) const to test for an attribute's existence.
See also
hasAttribute(const std::string name, const std::string uri) const
hasAttribute(const XMLTriple& triple) const
bool XMLAttributes::hasAttribute ( int  index) const

Returns true if an attribute exists at a given index.

Parameters
indexan integer, the position of the attribute to be tested.
Returns
true if an attribute with the given index exists in this XMLAttributes object, false otherwise.
Note
Note that although XMLAttributes provides operations that can manipulate attributes based on a numerical index, XML attributes are in fact unordered when they appear in files and data streams. The XMLAttributes class provides some list-like facilities, but it is only for the convenience of callers. (For example, it permits callers to loop across all attributes more easily.) Users should keep in mind that the order in which attributes are stored in XMLAttributes objects has no real impact on the order in which the attributes are read or written from an XML file or data stream.
bool XMLAttributes::hasAttribute ( const std::string &  name,
const std::string  uri = "" 
) const

Returns true if an attribute with a given name and namespace URI exists.

Parameters
namea string, the unprefixed name of the attribute.
uria string, the XML namespace URI of the attribute.
Returns
true if an attribute with the given local name and XML namespace URI exists in this XMLAttributes object, false otherwise.
See also
add(const std::string& name, const std::string& value, const std::string& namespaceURI, const std::string& prefix)
add(const XMLTriple& triple, const std::string& value)
bool XMLAttributes::hasAttribute ( const XMLTriple triple) const

Returns true if an attribute with the given properties exists.

Parameters
triplean XMLTriple describing the attribute to be tested.
Returns
true if an attribute with the given XML triple exists in this XMLAttributes object, false otherwise.
See also
add(const std::string& name, const std::string& value, const std::string& namespaceURI, const std::string& prefix)
add(const XMLTriple& triple, const std::string& value)
bool XMLAttributes::isEmpty ( ) const

Returns true if this list of attributes is empty.

Returns
true if this XMLAttributes object is empty, false otherwise.
XMLAttributes & XMLAttributes::operator= ( const XMLAttributes rhs)

Assignment operator for XMLAttributes.

Parameters
rhsthe XMLAttributes object whose values are used as the basis of the assignment.
bool XMLAttributes::readInto ( const std::string &  name,
bool &  value,
XMLErrorLog log = NULL,
bool  required = false,
const unsigned int  line = 0,
const unsigned int  column = 0 
) const

Interprets an attribute as a Boolean value.

This method reads the value associated with the attribute name in this XMLAttributes object and attempts to interpret it as a Boolean. If successful, this method stores the value into the variable passed in as value. If no attribute named name can be found in this XMLAttributes object or the value of the attribute could not be interpreted as a Boolean, value is left unmodified.

According to the specification of XML Schema, the valid Boolean values are: "true", "false", "1", and "0", read in a case-insensitive manner.

Errors in attempting to interpret the format are logged to log, if an error log object is supplied. If the parameter required is true, then if no attribute named name exists, an error will be logged to log with a description that explains the error is due to a missing required attribute. If the parameter required is false (the default), then if no attribute name exists, no error will be logged and this method will simply return false to indicate an unsuccessful assignment. Finally, if log is provided, name exists, but the value associated with name could not be parsed as a Boolean, then the error logged to log indicates that a value type mismatch occurred.

Values are read using the "C" locale.

Parameters
namea string, the name of the attribute.
valuea Boolean, the return parameter into which the value should be assigned.
logan XMLErrorLog object, an optional error log for reporting problems.
requireda Boolean flag, to indicate whether it should be considered an error if the attribute name cannot be found in this XMLAttributes object.
linean unsigned int, the line number at which the error occurred. Callers can supply this value if it makes sense for their applications.
columnan unsigned int, the column number at which the error occurred. Callers can supply this value if it makes sense for their applications.
Returns
true if the attribute was successfully read into value, false otherwise.
bool XMLAttributes::readInto ( const XMLTriple triple,
bool &  value,
XMLErrorLog log = NULL,
bool  required = false,
const unsigned int  line = 0,
const unsigned int  column = 0 
) const

Interprets an attribute as a Boolean value.

This method reads the value associated with the attribute described by triple in this XMLAttributes object and attempts to interpret it as a Boolean. If successful, this method stores the value into the variable passed in as value. If no attribute named name can be found in this XMLAttributes object or the value of the attribute could not be interpreted as a Boolean, value is left unmodified.

According to the specification of XML Schema, the valid Boolean values are: "true", "false", "1", and "0", read in a case-insensitive manner.

Errors in attempting to interpret the format are logged to log, if an error log object is supplied. If the parameter required is true, then if no attribute named name exists, an error will be logged to log with a description that explains the error is due to a missing required attribute. If the parameter required is false (the default), then if no attribute name exists, no error will be logged and this method will simply return false to indicate an unsuccessful assignment. Finally, if log is provided, name exists, but the value associated with name could not be parsed as a Boolean, then the error logged to log indicates that a value type mismatch occurred.

Values are read using the "C" locale.

Parameters
triplean XMLTriple object describing the attribute to read.
valuea Boolean, the return parameter into which the value should be assigned.
logan XMLErrorLog object, an optional error log for reporting problems.
requireda Boolean flag, to indicate whether it should be considered an error if the attribute name cannot be found in this XMLAttributes object.
linean unsigned int, the line number at which the error occurred. Callers can supply this value if it makes sense for their applications.
columnan unsigned int, the column number at which the error occurred. Callers can supply this value if it makes sense for their applications.
Returns
true if the attribute was successfully read into value, false otherwise.
bool XMLAttributes::readInto ( const std::string &  name,
double &  value,
XMLErrorLog log = NULL,
bool  required = false,
const unsigned int  line = 0,
const unsigned int  column = 0 
) const

Interprets an attribute as a double value.

This method reads the value associated with the attribute name in this XMLAttributes object and attempts to interpret it as a double. If successful, this method stores the value into the variable passed in as value. If no attribute named name can be found in this XMLAttributes object or the value of the attribute could not be interpreted as a double, value is left unmodified.

According to the specification of XML Schema, valid doubles are the same as valid doubles for the C language and in addition, the special values "INF", "-INF", and "NaN", read in a case-insensitive manner.

Errors in attempting to interpret the format are logged to log, if an error log object is supplied. If the parameter required is true, then if no attribute named name exists, an error will be logged to log with a description that explains the error is due to a missing required attribute. If the parameter required is false (the default), then if no attribute name exists, no error will be logged and this method will simply return false to indicate an unsuccessful assignment. Finally, if log is provided, name exists, but the value associated with name could not be parsed as a double, then the error logged to log indicates that a value type mismatch occurred.

Values are read using the "C" locale.

Parameters
namea string, the name of the attribute.
valuea double, the return parameter into which the value should be assigned.
logan XMLErrorLog object, an optional error log for reporting problems.
requireda Boolean flag, to indicate whether it should be considered an error if the attribute name cannot be found in this XMLAttributes object.
linean unsigned int, the line number at which the error occurred. Callers can supply this value if it makes sense for their applications.
columnan unsigned int, the column number at which the error occurred. Callers can supply this value if it makes sense for their applications.
Returns
true if the attribute was successfully read into value, false otherwise.
Note
The XML namespace associated with the attribute named name is not considered when looking up the attribute. If more than one attribute with the same name exists with different XML namespace URI associations, this method will operate on the first one it encounters; this behavior is identical to XMLAttributes::getIndex (const std::string& name) const. To have XML namespaces be considered too, callers should use the variant method that takes an XMLTriple object instead of a string name argument.
bool XMLAttributes::readInto ( const XMLTriple triple,
double &  value,
XMLErrorLog log = NULL,
bool  required = false,
const unsigned int  line = 0,
const unsigned int  column = 0 
) const

Interprets an attribute as a double value.

This method reads the value associated with the attribute described by triple in this XMLAttributes object and attempts to interpret it as a double. If successful, this method stores the value into the variable passed in as value. If no attribute named name can be found in this XMLAttributes object or the value of the attribute could not be interpreted as a double, value is left unmodified.

According to the specification of XML Schema, valid doubles are the same as valid doubles for the C language and in addition, the special values "INF", "-INF", and "NaN", read in a case-insensitive manner.

Errors in attempting to interpret the format are logged to log, if an error log object is supplied. If the parameter required is true, then if no attribute named name exists, an error will be logged to log with a description that explains the error is due to a missing required attribute. If the parameter required is false (the default), then if no attribute name exists, no error will be logged and this method will simply return false to indicate an unsuccessful assignment. Finally, if log is provided, name exists, but the value associated with name could not be parsed as a double, then the error logged to log indicates that a value type mismatch occurred.

Values are read using the "C" locale.

Parameters
triplean XMLTriple object describing the attribute to read.
valuea double, the return parameter into which the value should be assigned.
logan XMLErrorLog object, an optional error log for reporting problems.
requireda Boolean flag, to indicate whether it should be considered an error if the attribute name cannot be found in this XMLAttributes object.
linean unsigned int, the line number at which the error occurred. Callers can supply this value if it makes sense for their applications.
columnan unsigned int, the column number at which the error occurred. Callers can supply this value if it makes sense for their applications.
Returns
true if the attribute was successfully read into value, false otherwise.
bool XMLAttributes::readInto ( const std::string &  name,
long &  value,
XMLErrorLog log = NULL,
bool  required = false,
const unsigned int  line = 0,
const unsigned int  column = 0 
) const

Interprets an attribute as a long integer value.

This method reads the value associated with the attribute name in this XMLAttributes object and attempts to interpret it as a long. If successful, this method stores the value into the variable passed in as value. If no attribute named name can be found in this XMLAttributes object or the value of the attribute could not be interpreted as a long, value is left unmodified.

According to the specification of XML Schema, valid long-type values are zero, all positive whole numbers and all negative whole numbers. This is unfortunately a larger space of values than can be represented in a long integer, so libSBML limits the possible values to those that can be stored in a long data type.

Errors in attempting to interpret the format are logged to log, if an error log object is supplied. If the parameter required is true, then if no attribute named name exists, an error will be logged to log with a description that explains the error is due to a missing required attribute. If the parameter required is false (the default), then if no attribute name exists, no error will be logged and this method will simply return false to indicate an unsuccessful assignment. Finally, if log is provided, name exists, but the value associated with name could not be parsed as a long, then the error logged to log indicates that a value type mismatch occurred.

Values are read using the "C" locale.

Parameters
namea string, the name of the attribute.
valuea long, the return parameter into which the value should be assigned.
logan XMLErrorLog object, an optional error log for reporting problems.
requireda Boolean flag, to indicate whether it should be considered an error if the attribute name cannot be found in this XMLAttributes object.
linean unsigned int, the line number at which the error occurred. Callers can supply this value if it makes sense for their applications.
columnan unsigned int, the column number at which the error occurred. Callers can supply this value if it makes sense for their applications.
Returns
true if the attribute was successfully read into value, false otherwise.
Note
The XML namespace associated with the attribute named name is not considered when looking up the attribute. If more than one attribute with the same name exists with different XML namespace URI associations, this method will operate on the first one it encounters; this behavior is identical to XMLAttributes::getIndex (const std::string& name) const. To have XML namespaces be considered too, callers should use the variant method that takes an XMLTriple object instead of a string name argument.
bool XMLAttributes::readInto ( const XMLTriple triple,
long &  value,
XMLErrorLog log = NULL,
bool  required = false,
const unsigned int  line = 0,
const unsigned int  column = 0 
) const

Interprets an attribute as a long integer value.

This method reads the value associated with the attribute described by triple in this XMLAttributes object and attempts to interpret it as a long. If successful, this method stores the value into the variable passed in as value. If no attribute named name can be found in this XMLAttributes object or the value of the attribute could not be interpreted as a long, value is left unmodified.

According to the specification of XML Schema, valid long-type values are zero, all positive whole numbers and all negative whole numbers. This is unfortunately a larger space of values than can be represented in a long, so libSBML limits the possible values to those that can be stored in a long data type.

Errors in attempting to interpret the format are logged to log, if an error log object is supplied. If the parameter required is true, then if no attribute named name exists, an error will be logged to log with a description that explains the error is due to a missing required attribute. If the parameter required is false (the default), then if no attribute name exists, no error will be logged and this method will simply return false to indicate an unsuccessful assignment. Finally, if log is provided, name exists, but the value associated with name could not be parsed as a long, then the error logged to log indicates that a value type mismatch occurred.

Values are read using the "C" locale.

Parameters
triplean XMLTriple object describing the attribute
valuea long, the return parameter into which the value should be assigned.
logan XMLErrorLog object, an optional error log for reporting problems.
requireda Boolean flag, to indicate whether it should be considered an error if the attribute name cannot be found in this XMLAttributes object.
linean unsigned int, the line number at which the error occurred. Callers can supply this value if it makes sense for their applications.
columnan unsigned int, the column number at which the error occurred. Callers can supply this value if it makes sense for their applications.
Returns
true if the attribute was successfully read into value, false otherwise.
Note
The XML namespace associated with the attribute named name is not considered when looking up the attribute. If more than one attribute with the same name exists with different XML namespace URI associations, this method will operate on the first one it encounters; this behavior is identical to XMLAttributes::getIndex (const std::string& name) const. To have XML namespaces be considered too, callers should use the variant method that takes an XMLTriple object instead of a string name argument.
bool XMLAttributes::readInto ( const std::string &  name,
int &  value,
XMLErrorLog log = NULL,
bool  required = false,
const unsigned int  line = 0,
const unsigned int  column = 0 
) const

Interprets an attribute as a int value.

This method reads the value associated with the attribute name in this XMLAttributes object and attempts to interpret it as an int. If successful, this method stores the value into the variable passed in as value. If no attribute named name can be found in this XMLAttributes object or the value of the attribute could not be interpreted as an int, value is left unmodified.

According to the specification of XML Schema, valid long-type values are zero, all positive whole numbers and all negative whole numbers. The present method is designed to interpret numbers as signed int values and cannot represent larger values. Note that variant methods on XMLAttributes are available to work with unsigned int type and long type values; users may wish to investigate those methods if they need to handle larger integer values.

Errors in attempting to interpret the format are logged to log, if an error log object is supplied. If the parameter required is true, then if no attribute named name exists, an error will be logged to log with a description that explains the error is due to a missing required attribute. If the parameter required is false (the default), then if no attribute name exists, no error will be logged and this method will simply return false to indicate an unsuccessful assignment. Finally, if log is provided, name exists, but the value associated with name could not be parsed as a long, then the error logged to log indicates that a value type mismatch occurred.

Values are read using the "C" locale.

Parameters
namea string, the name of the attribute.
valuean int, the return parameter into which the value should be assigned.
logan XMLErrorLog object, an optional error log for reporting problems.
requireda Boolean flag, to indicate whether it should be considered an error if the attribute name cannot be found in this XMLAttributes object.
linean unsigned int, the line number at which the error occurred. Callers can supply this value if it makes sense for their applications.
columnan unsigned int, the column number at which the error occurred. Callers can supply this value if it makes sense for their applications.
Returns
true if the attribute was successfully read into value, false otherwise.
Note
The XML namespace associated with the attribute named name is not considered when looking up the attribute. If more than one attribute with the same name exists with different XML namespace URI associations, this method will operate on the first one it encounters; this behavior is identical to XMLAttributes::getIndex (const std::string& name) const. To have XML namespaces be considered too, callers should use the variant method that takes an XMLTriple object instead of a string name argument.
bool XMLAttributes::readInto ( const XMLTriple triple,
int &  value,
XMLErrorLog log = NULL,
bool  required = false,
const unsigned int  line = 0,
const unsigned int  column = 0 
) const

Interprets an attribute as a int value.

This method reads the value associated with the attribute described by triple in this XMLAttributes object and attempts to interpret it as an int. If successful, this method stores the value into the variable passed in as value. If no attribute named name can be found in this XMLAttributes object or the value of the attribute could not be interpreted as an int, value is left unmodified.

According to the specification of XML Schema, valid long-type values are zero, all positive whole numbers and all negative whole numbers. The present method is designed to interpret numbers as signed int values and cannot represent larger values. Note that variant methods on XMLAttributes are available to work with unsigned int type and long type values; users may wish to investigate those methods if they need to handle larger integer values.

Errors in attempting to interpret the format are logged to log, if an error log object is supplied. If the parameter required is true, then if no attribute named name exists, an error will be logged to log with a description that explains the error is due to a missing required attribute. If the parameter required is false (the default), then if no attribute name exists, no error will be logged and this method will simply return false to indicate an unsuccessful assignment. Finally, if log is provided, name exists, but the value associated with name could not be parsed as a long, then the error logged to log indicates that a value type mismatch occurred.

Values are read using the "C" locale.

Parameters
triplean XMLTriple object describing the attribute
valuean int, the return parameter into which the value should be assigned.
logan XMLErrorLog object, an optional error log for reporting problems.
requireda Boolean flag, to indicate whether it should be considered an error if the attribute name cannot be found in this XMLAttributes object.
linean unsigned int, the line number at which the error occurred. Callers can supply this value if it makes sense for their applications.
columnan unsigned int, the column number at which the error occurred. Callers can supply this value if it makes sense for their applications.
Returns
true if the attribute was successfully read into value, false otherwise.
bool XMLAttributes::readInto ( const std::string &  name,
unsigned int &  value,
XMLErrorLog log = NULL,
bool  required = false,
const unsigned int  line = 0,
const unsigned int  column = 0 
) const

Interprets an attribute as a unsigned int value.

This method reads the value associated with the attribute name in this XMLAttributes object and attempts to interpret it as an unsigned int. If successful, this method stores the value into the variable passed in as value. If no attribute named name can be found in this XMLAttributes object or the value of the attribute could not be interpreted as an unsigned int, value is left unmodified.

According to the specification of XML Schema, valid long-type values are zero, all positive whole numbers and all negative whole numbers. The present method is designed to interpret numbers as unsigned int and cannot represent larger values. Note that a variant method on XMLAttributes is available to work with long type values; users may wish to investigate that method if they need to handle large integer values.

Errors in attempting to interpret the format are logged to log, if an error log object is supplied. If the parameter required is true, then if no attribute named name exists, an error will be logged to log with a description that explains the error is due to a missing required attribute. If the parameter required is false (the default), then if no attribute name exists, no error will be logged and this method will simply return false to indicate an unsuccessful assignment. Finally, if log is provided, name exists, but the value associated with name could not be parsed as a long, then the error logged to log indicates that a value type mismatch occurred.

Values are read using the "C" locale.

Parameters
namea string, the name of the attribute.
valuean int, the return parameter into which the value should be assigned.
logan XMLErrorLog object, an optional error log for reporting problems.
requireda Boolean flag, to indicate whether it should be considered an error if the attribute name cannot be found in this XMLAttributes object.
linean unsigned int, the line number at which the error occurred. Callers can supply this value if it makes sense for their applications.
columnan unsigned int, the column number at which the error occurred. Callers can supply this value if it makes sense for their applications.
Returns
true if the attribute was successfully read into value, false otherwise.
Note
The XML namespace associated with the attribute named name is not considered when looking up the attribute. If more than one attribute with the same name exists with different XML namespace URI associations, this method will operate on the first one it encounters; this behavior is identical to XMLAttributes::getIndex (const std::string& name) const. To have XML namespaces be considered too, callers should use the variant method that takes an XMLTriple object instead of a string name argument.
bool XMLAttributes::readInto ( const XMLTriple triple,
unsigned int &  value,
XMLErrorLog log = NULL,
bool  required = false,
const unsigned int  line = 0,
const unsigned int  column = 0 
) const

Interprets an attribute as a unsigned int value.

This method reads the value associated with the attribute described by triple in this XMLAttributes object and attempts to interpret it as an unsigned int. If successful, this method stores the value into the variable passed in as value. If no attribute named name can be found in this XMLAttributes object or the value of the attribute could not be interpreted as an unsigned int, value is left unmodified.

According to the specification of XML Schema, valid long-type values are zero, all positive whole numbers and all negative whole numbers. The present method is designed to interpret numbers as unsigned int and cannot represent larger values. Note that a variant method on XMLAttributes is available to work with long type values; users may wish to investigate that method if they need to handle large integer values.

Errors in attempting to interpret the format are logged to log, if an error log object is supplied. If the parameter required is true, then if no attribute named name exists, an error will be logged to log with a description that explains the error is due to a missing required attribute. If the parameter required is false (the default), then if no attribute name exists, no error will be logged and this method will simply return false to indicate an unsuccessful assignment. Finally, if log is provided, name exists, but the value associated with name could not be parsed as a long, then the error logged to log indicates that a value type mismatch occurred.

Values are read using the "C" locale.

Parameters
triplean XMLTriple object describing the attribute
valuean int, the return parameter into which the value should be assigned.
logan XMLErrorLog object, an optional error log for reporting problems.
requireda Boolean flag, to indicate whether it should be considered an error if the attribute name cannot be found in this XMLAttributes object.
linean unsigned int, the line number at which the error occurred. Callers can supply this value if it makes sense for their applications.
columnan unsigned int, the column number at which the error occurred. Callers can supply this value if it makes sense for their applications.
Returns
true if the attribute was successfully read into value, false otherwise.
bool XMLAttributes::readInto ( const std::string &  name,
std::string &  value,
XMLErrorLog log = NULL,
bool  required = false,
const unsigned int  line = 0,
const unsigned int  column = 0 
) const

Interprets an attribute as a string value.

This method reads the value associated with the attribute name in this XMLAttributes object and stores the value into the variable passed in as value. If no attribute named name can be found in this XMLAttributes object, value is left unmodified.

Unlike the other variant methods on XMLAttributes, there are no format errors possible when reading strings, since XML attribute values are strings. However, the case of a missing attribute can still occur. Errors will be logged to log, if an error log object is supplied. If the parameter required is true, then if no attribute named name exists, an error will be logged to log with a description that explains the error is due to a missing required attribute. If the parameter required is false (the default), then if no attribute name exists, no error will be logged and this method will simply return false to indicate an unsuccessful assignment.

Values are read using the "C" locale.

Parameters
namea string, the name of the attribute.
valuea string, the return parameter into which the value should be assigned.
logan XMLErrorLog object, an optional error log for reporting problems.
requireda Boolean flag, to indicate whether it should be considered an error if the attribute name cannot be found in this XMLAttributes object.
linean unsigned int, the line number at which the error occurred. Callers can supply this value if it makes sense for their applications.
columnan unsigned int, the column number at which the error occurred. Callers can supply this value if it makes sense for their applications.
Returns
true if the attribute was successfully read into value, false otherwise.
Note
The XML namespace associated with the attribute named name is not considered when looking up the attribute. If more than one attribute with the same name exists with different XML namespace URI associations, this method will operate on the first one it encounters; this behavior is identical to XMLAttributes::getIndex (const std::string& name) const. To have XML namespaces be considered too, callers should use the variant method that takes an XMLTriple object instead of a string name argument.
bool XMLAttributes::readInto ( const XMLTriple triple,
std::string &  value,
XMLErrorLog log = NULL,
bool  required = false,
const unsigned int  line = 0,
const unsigned int  column = 0 
) const

Interprets an attribute as a string value.

This method reads the value associated with the attribute described by triple in this XMLAttributes object and stores the value into the variable passed in as value. If no attribute named name can be found in this XMLAttributes object, value is left unmodified.

Unlike the other variant methods on XMLAttributes, there are no format errors possible when reading strings, since XML attribute values are strings. However, the case of a missing attribute can still occur. Errors will be logged to log, if an error log object is supplied. If the parameter required is true, then if no attribute named name exists, an error will be logged to log with a description that explains the error is due to a missing required attribute. If the parameter required is false (the default), then if no attribute name exists, no error will be logged and this method will simply return false to indicate an unsuccessful assignment.

Values are read using the "C" locale.

Parameters
triplean XMLTriple object describing the attribute
valuea string, the return parameter into which the value should be assigned.
logan XMLErrorLog object, an optional error log for reporting problems.
requireda Boolean flag, to indicate whether it should be considered an error if the attribute name cannot be found in this XMLAttributes object.
linean unsigned int, the line number at which the error occurred. Callers can supply this value if it makes sense for their applications.
columnan unsigned int, the column number at which the error occurred. Callers can supply this value if it makes sense for their applications.
Returns
true if the attribute was successfully read into value, false otherwise.
int XMLAttributes::remove ( int  n)

Removes the nth attribute from this list of attributes.

Parameters
nan 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: The value LIBSBML_INDEX_EXCEEDS_SIZE is returned if there is no attribute at the given index n.
Note
Note that although XMLAttributes provides operations that can manipulate attributes based on a numerical index, XML attributes are in fact unordered when they appear in files and data streams. The XMLAttributes class provides some list-like facilities, but it is only for the convenience of callers. (For example, it permits callers to loop across all attributes more easily.) Users should keep in mind that the order in which attributes are stored in XMLAttributes objects has no real impact on the order in which the attributes are read or written from an XML file or data stream.
See also
getLength()
remove(const XMLTriple& triple)
remove(const std::string& name, const std::string& uri)
int XMLAttributes::remove ( const std::string &  name,
const std::string  uri = "" 
)

Removes a named attribute from this list of attributes.

Parameters
namea string, the unprefixed name of the attribute to be removed.
uria string, the namespace URI of the attribute 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: The value LIBSBML_INDEX_EXCEEDS_SIZE is returned if there is no attribute with the given name (and uri if specified).
See also
remove(int n)
remove(const XMLTriple& triple)
int XMLAttributes::remove ( const XMLTriple triple)

Removes a specific attribute from this list of attributes.

Parameters
triplean XMLTriple describing the attribute 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: The value LIBSBML_INDEX_EXCEEDS_SIZE is returned if there is no attribute matching the properties of the given triple.
See also
remove(int n)
remove(const std::string& name, const std::string& uri)