libSBML C++ API  5.18.0
XMLNamespaces Class Reference

Detailed Description

An XML Namespace.

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.

This class serves to organize functionality for tracking XML namespaces in a document or data stream. The namespace declarations are stored as a list of pairs of XML namespace URIs and prefix strings. These correspond to the parts of a namespace declaration on an XML element. For example, in the following XML fragment,

<annotation>
    <mysim:nodecolors xmlns:mysim="urn:lsid:mysim.org"
         mysim:bgcolor="green" mysim:fgcolor="white"/>
</annotation>

there is one namespace declaration. Its URI is urn:lsid:mysim.org and its prefix is mysim. This pair could be stored as one item in an XMLNamespaces list.

XMLNamespaces provides various methods for manipulating the list of prefix-URI pairs. Individual namespaces stored in a given XMLNamespace object instance can be retrieved based on their index using XMLNamespaces::getPrefix(int index), or by their characteristics such as their URI or position in the list.

Examples:
addingEvidenceCodes_2.cpp.

Public Member Functions

int add (const std::string &uri, const std::string prefix="")
 Appends an XML namespace prefix and URI pair to this list of namespace declarations. More...
 
int clear ()
 Clears (deletes) all XML namespace declarations in this XMLNamespaces object. More...
 
XMLNamespacesclone () const
 Creates and returns a deep copy of this XMLNamespaces object. More...
 
bool containsUri (const std::string &uri) const
 Tests whether the given uri is contained in this set of namespaces. More...
 
int getIndex (const std::string &uri) const
 Look up the index of an XML namespace declaration by URI. More...
 
int getIndexByPrefix (const std::string &prefix) const
 Look up the index of an XML namespace declaration by prefix. More...
 
int getLength () const
 Returns the total number of URI-and-prefix pairs stored in this particular XMLNamespaces instance. More...
 
int getNumNamespaces () const
 Returns the total number of URI-and-prefix pairs stored in this particular XMLNamespaces instance. More...
 
std::string getPrefix (int index) const
 Look up the prefix of an XML namespace declaration by its position. More...
 
std::string getPrefix (const std::string &uri) const
 Look up the prefix of an XML namespace declaration by its URI. More...
 
std::string getURI (int index) const
 Look up the URI of an XML namespace declaration by its position. More...
 
std::string getURI (const std::string prefix="") const
 Look up the URI of an XML namespace declaration by its prefix. More...
 
bool hasNS (const std::string &uri, const std::string &prefix) const
 Predicate returning true or false depending on whether an XML Namespace with the given URI and prefix pair is contained in this XMLNamespaces list. More...
 
bool hasPrefix (const std::string &prefix) const
 Predicate returning true or false depending on whether an XML Namespace with the given prefix is contained in this XMLNamespaces list. More...
 
bool hasURI (const std::string &uri) const
 Predicate returning true or false depending on whether an XML Namespace with the given URI is contained in this XMLNamespaces list. More...
 
bool isEmpty () const
 Predicate returning true or false depending on whether this XMLNamespaces list is empty. More...
 
XMLNamespacesoperator= (const XMLNamespaces &rhs)
 Assignment operator for XMLNamespaces. More...
 
int remove (int index)
 Removes an XML Namespace stored in the given position of this list. More...
 
int remove (const std::string &prefix)
 Removes an XML Namespace with the given prefix. More...
 
 XMLNamespaces ()
 Creates a new empty list of XML namespace declarations. More...
 
 XMLNamespaces (const XMLNamespaces &orig)
 Copy constructor; creates a copy of this XMLNamespaces list. More...
 
virtual ~XMLNamespaces ()
 Destroys this list of XML namespace declarations. More...
 

Constructor & Destructor Documentation

XMLNamespaces::XMLNamespaces ( )

Creates a new empty list of XML namespace declarations.

XMLNamespaces::~XMLNamespaces ( )
virtual

Destroys this list of XML namespace declarations.

XMLNamespaces::XMLNamespaces ( const XMLNamespaces orig)

Copy constructor; creates a copy of this XMLNamespaces list.

Parameters
origthe XMLNamespaces object to copy.

Member Function Documentation

int XMLNamespaces::add ( const std::string &  uri,
const std::string  prefix = "" 
)

Appends an XML namespace prefix and URI pair to this list of namespace declarations.

An XMLNamespaces object stores a list of pairs of namespaces and their prefixes. If there is an XML namespace with the given uri prefix in this list, then its corresponding URI will be overwritten by the new uri unless the uri represents the core sbml namespace. Calling programs could use one of the other XMLNamespaces methods, such as XMLNamespaces::hasPrefix() and XMLNamespaces::hasURI() to inquire whether a given prefix and/or URI is already present in this XMLNamespaces object. If the uri represents the sbml namespaces then it will not be overwritten, as this has potentially serious consequences. If it is necessary to replace the sbml namespace the namespace should be removed prior to adding the new namespace.

Parameters
uria string, the uri for the namespace.
prefixa 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:
Examples:
addingEvidenceCodes_2.cpp, and createExampleSBML.cpp.
int XMLNamespaces::clear ( )

Clears (deletes) all XML namespace declarations in this XMLNamespaces object.

Returns
integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:
See also
remove(int index)
XMLNamespaces * XMLNamespaces::clone ( ) const

Creates and returns a deep copy of this XMLNamespaces object.

Returns
the (deep) copy of this XMLNamespaces object.
bool XMLNamespaces::containsUri ( const std::string &  uri) const

Tests whether the given uri is contained in this set of namespaces.

int XMLNamespaces::getIndex ( const std::string &  uri) const

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

An XMLNamespaces object stores a list of pairs of namespaces and their prefixes. If this XMLNamespaces object contains a pair with the given URI uri, this method returns its index in the list.

Parameters
uria string, the URI of the sought-after namespace.
Returns
the index of the given declaration, or -1 if not present.
int XMLNamespaces::getIndexByPrefix ( const std::string &  prefix) const

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

An XMLNamespaces object stores a list of pairs of namespaces and their prefixes. If this XMLNamespaces object contains a pair with the given prefix prefix, this method returns its index in the list.

Parameters
prefixa string, the prefix string of the sought-after namespace.
Returns
the index of the given declaration, or -1 if not present.
int XMLNamespaces::getLength ( ) const

Returns the total number of URI-and-prefix pairs stored in this particular XMLNamespaces instance.

Returns
the number of namespaces in this list.
int XMLNamespaces::getNumNamespaces ( ) const

Returns the total number of URI-and-prefix pairs stored in this particular XMLNamespaces instance.

Returns
the number of namespaces in this list.

This function is an alias for getLength introduced for consistency with other XML classes.

std::string XMLNamespaces::getPrefix ( int  index) const

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

An XMLNamespaces object stores a list of pairs of namespaces and their prefixes. This method returns the prefix of the nth element in that list (if it exists). Callers should use XMLAttributes::getLength() first to find out how many namespaces are stored in the list.

Parameters
indexan integer, position of the sought-after prefix.
Returns
the prefix of an XML namespace declaration in this list (by position), or an empty string if the index is out of range.
See also
getLength()
std::string XMLNamespaces::getPrefix ( const std::string &  uri) const

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

An XMLNamespaces object stores a list of pairs of namespaces and their prefixes. This method returns the prefix for a pair that has the given uri.

Parameters
uria string, the URI of the prefix being sought.
Returns
the prefix of an XML namespace declaration given its URI, or an empty string if no such uri exists in this XMLNamespaces object.
std::string XMLNamespaces::getURI ( int  index) const

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

An XMLNamespaces object stores a list of pairs of namespaces and their prefixes. This method returns the URI of the nth element in that list (if it exists). Callers should use XMLAttributes::getLength() first to find out how many namespaces are stored in the list.

Parameters
indexan integer, position of the required URI.
Returns
the URI of an XML namespace declaration in this list (by position), or an empty string if the index is out of range.
See also
getLength()
std::string XMLNamespaces::getURI ( const std::string  prefix = "") const

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

An XMLNamespaces object stores a list of pairs of namespaces and their prefixes. This method returns the namespace URI for a pair that has the given prefix.

Parameters
prefixa string, the prefix of the required URI.
Returns
the URI of an XML namespace declaration having the given prefix, or an empty string if no such prefix-and-URI pair exists in this XMLNamespaces object.
See also
getURI()
bool XMLNamespaces::hasNS ( const std::string &  uri,
const std::string &  prefix 
) const

Predicate returning true or false depending on whether an XML Namespace with the given URI and prefix pair is contained in this XMLNamespaces list.

Parameters
uria string, the URI for the namespace.
prefixa string, the prefix for the namespace.
Returns
true if an XML Namespace with the given uri/prefix pair is contained in this XMLNamespaces list, false otherwise.
bool XMLNamespaces::hasPrefix ( const std::string &  prefix) const

Predicate returning true or false depending on whether an XML Namespace with the given prefix is contained in this XMLNamespaces list.

Parameters
prefixa string, the prefix for the namespace.
Returns
true if an XML Namespace with the given URI is contained in this XMLNamespaces list, false otherwise.
bool XMLNamespaces::hasURI ( const std::string &  uri) const

Predicate returning true or false depending on whether an XML Namespace with the given URI is contained in this XMLNamespaces list.

Parameters
uria string, the uri for the namespace.
Returns
true if an XML Namespace with the given URI is contained in this XMLNamespaces list, false otherwise.
bool XMLNamespaces::isEmpty ( ) const

Predicate returning true or false depending on whether this XMLNamespaces list is empty.

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

Assignment operator for XMLNamespaces.

Parameters
rhsthe XMLNamespaces object whose values are used as the basis of the assignment.
int XMLNamespaces::remove ( int  index)

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

Parameters
indexan integer, position of the namespace to remove.
Returns
integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:
int XMLNamespaces::remove ( const std::string &  prefix)

Removes an XML Namespace with the given prefix.

Parameters
prefixa 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:
See also
remove(int index)