HydraExpress™ C++ API Reference Guide

Product Documentation:
   HydraExpress C++
Documentation Home
List of all members | Public Member Functions | Related Functions
rwsf::XmlName Class Reference

Represents a complete XML element name, containing a name as a string, and an instance of XmlNamespace. More...

#include <rwsf/core/XmlName.h>

Public Member Functions

 XmlName ()
 XmlName (const std::string &localName)
 XmlName (const std::string &localName, const rwsf::XmlNamespace &ns)
 XmlName (const XmlName &name)
std::string asString () const
int compareTo (const XmlName &other) const
bool empty () const
const std::string & getLocalName () const
const rwsf::XmlNamespacegetNamespace () const
rwsf::XmlNamespacegetNamespace ()
std::string getQualifiedName () const
std::string getUniqueName () const
bool isNull () const
XmlNameoperator= (const XmlName &n)
void setLocalName (const std::string &localName)
void setNamespace (const rwsf::XmlNamespace &ns)
void unsetNamespace ()

Related Functions

(Note that these are not member functions.)

bool operator!= (const XmlName &lhs, const XmlName &rhs)
bool operator< (const XmlName &lhs, const XmlName &rhs)
bool operator== (const XmlName &lhs, const XmlName &rhs)

Detailed Description

The complete information for an XML name consists of a local name and its namespace. rwsf::XmlName represents a complete XML name using a local name represented as a string and an rwsf::XmlNamespace. If the local name has no namespace qualification, the namespace component of an instance of this class will be equal to the namespace returned by rwsf::XmlNamespace::getEmptyNamespace().

For the element

<rw:book xmlns:rw="http://xml.roguewave.com/"/>

the rwsf::XmlName contains the local name book and an rwsf::XmlNamespace object that contains the prefix string "rw" and the URI string "http://xml.roguewave.com/". The combination of the prefix and the local name is the qualified name, rw:book in this example.

Every XML element must have a name. All classes that represent XML elements contain an rwsf::XmlName.

In rwsf::XmlName, the local name can be set to the empty string. This is not valid for XML, however, because all XML qualified names must have a non-empty local name. If the XML qualified name is empty at XML serialization, a serializer may choose to provide an arbitrary name in order to output valid XML.

In rwsf::XmlName, the local name can also be set to a qualified XML string, like "http://uri.com::elementName" or "pre:elementName". Be aware, however, that using a qualified string in place of a local name (while allowed by XmlName which provides no schema validation) will create an invalid local name. Use of this object where a valid XML qualified name is expected is likely to fail, because no namespace information will be stored with the XmlName, and the URI and prefixes ("http://uri.com" and "pre" in the examples above) will likely be undefined. If a qualified XmlName is needed, be sure to use the constructor that takes an XmlNamespace parameter, i.e. XmlName(const std::string&, const rwsf::XmlNamespace&).

Be aware that rwsf::XmlName does not represent the context of the name. An instance of this class contains no information about relationships among the namespace where the element resides and other namespace declarations in a document. The W3C specifies that the prefix of an XML name be an arbitrary placeholder for the URI. Therefore, a serializer for an rwsf::XmlName may not generate the same qualified name as the object itself. A serializer must preserve the unique name, but is free to replace the prefix with an equivalent prefix, generate a new prefix, or ignore the prefix entirely.

Constructor & Destructor Documentation

rwsf::XmlName::XmlName ( )

Constructs an XmlName instance with a blank local name and no namespace.

rwsf::XmlName::XmlName ( const std::string &  localName)

Constructs an XmlName with the local name localName and no namespace.

rwsf::XmlName::XmlName ( const std::string &  localName,
const rwsf::XmlNamespace ns 

Constructs an XmlName with the local name localName in the ns namespace.

rwsf::XmlName::XmlName ( const XmlName name)

Copy constructor. Creates a deep copy of name.

Member Function Documentation

std::string rwsf::XmlName::asString ( ) const

Returns the qualified name of self.

See also
int rwsf::XmlName::compareTo ( const XmlName other) const

Compares the components of the unique names of self and other. If self's unique name sorts before the name of other, returns a number less than zero. If the unique names are equal, returns zero. Otherwise, returns a number greater than zero.

bool rwsf::XmlName::empty ( ) const

Returns true if this rwsf::XmlName is blank (i.e., has an empty local name and no namespace).

const std::string& rwsf::XmlName::getLocalName ( ) const

Returns the local name. As stated in the class description, this can be the empty string, even though empty local names are not allowed once the XML is serialized.

const rwsf::XmlNamespace& rwsf::XmlName::getNamespace ( ) const

Returns the namespace of this rwsf::XmlName.

rwsf::XmlNamespace& rwsf::XmlName::getNamespace ( )

Returns the namespace of this rwsf::XmlName.

std::string rwsf::XmlName::getQualifiedName ( ) const

If this name is in a namespace with a non-empty prefix, returns the string prefix:localname. Otherwise, returns the string localname.

std::string rwsf::XmlName::getUniqueName ( ) const

Returns a unique name for this rwsf::XmlName. If this name is in a namespace, the unique name takes the form URI::localname. Otherwise, the unique name is the local name. Since the W3C does not specify a format for representing a unique name as text, the string returned by this function will not be understood by a parser, and should not be used for serialization.

bool rwsf::XmlName::isNull ( ) const

Returns true if this rwsf::XmlName is blank (i.e., has an empty local name and no namespace).

XmlName& rwsf::XmlName::operator= ( const XmlName n)

Assignment operator. Makes self a deep copy of n.

void rwsf::XmlName::setLocalName ( const std::string &  localName)

Sets the local name of this rwsf::XmlName to localName.

void rwsf::XmlName::setNamespace ( const rwsf::XmlNamespace ns)

Sets the namespace of this rwsf::XmlName to ns.

void rwsf::XmlName::unsetNamespace ( )

Removes the namespace from this rwsf::XmlName.

Friends And Related Function Documentation

bool operator!= ( const XmlName lhs,
const XmlName rhs 

Returns false if lhs and rhs have the same local name and the same namespace URI. Ignores prefixes.

bool operator< ( const XmlName lhs,
const XmlName rhs 

Returns true if the local name of lhs compares less than the local name of rhs, or false if the local name of lhs is greater than the local name of rhs. All comparisons use operator<() for std::string. If the local names compare equal, compares the contained rwsf::XmlNamespace objects and returns the results.

bool operator== ( const XmlName lhs,
const XmlName rhs 

Returns true if the two objects have the same local name and the same namespace URI. Ignores prefixes.

Copyright © 2020 Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave is registered trademark of Rogue Wave Software, Inc. in the United States and other countries, and HydraExpress is a trademark of Rogue Wave Software. All other trademarks are the property of their respective owners.
Provide feedback to Rogue Wave about its documentation.