rwsf::XmlUtils Class Reference

Utility class for XML transformation, especially character set conversions between non-UTF-8 character encoding and UTF-8. More...

#include <rwsf/core/XmlUtils.h>

Static Public Member Functions
static std::string	changeName (rwsf::XmlName name, std::string element)
static bool	compareAttributeSet (const rwsf::XmlAttributeSet &a1, const rwsf::XmlAttributeSet &a2)
static bool	compareAttributeSet (const rwsf::XmlAttributeSet &a1, const rwsf::XmlAttributeSet &a2, std::string &compareInfo)
static std::string	convertCharset (const std::string &buffer, const std::string &from, const std::string &to)
static std::string	convertDateTimeToISOString (const rwsf::DateTime &dt, const std::string &format=ISO8601Format)
static rwsf::DateTime	convertISODateStringToDateTime (const std::string &anISODateStr)
static std::string	escapeText (const std::string &text)
static std::string	getElementValueAsString (const std::string &data)
static std::string	getPrefix (const std::string &qName)
static void	getPrefixAndLocalName (const std::string &qName, std::string &prefix, std::string &lname)
static bool	isWhiteSpace (const char c)
static std::string	stripTag (const std::string &str, bool ignoreProlog=false)
static std::string	stripTag (const std::string &str, const std::string &tag, bool ignoreProlog=false)
static std::string	stripWhiteSpaceAndNewlines (const std::string &str, rwsf::stdStripType toStrip=rwsf::both)
static std::string	unescapeText (const std::string &text)
static std::string	wrapStringInTag (const std::string &str, const rwsf::XmlName &tag)
static std::string	wrapStringInTag (const std::string &str, const std::string &tag)

Detailed Description

rwsf::XmlUtils is a utility class for XML manipulation and transformation.

In particular, this class can perform character set conversions between a non-UTF-8 character encoding and UTF-8, using its convertCharset() function. For more information regarding charset conversions, please see the Web Services Development Guide.

Member Function Documentation

changeName()

std::string rwsf::XmlUtils::changeName ( rwsf::XmlName name, std::string element )

static

Performs a simple, brute force change to the parent element name found in the string element. The string element should be a valid XML element fragment, starting with an opening element declaration (i.e. start tag). The name of the element will be changed to name along with its namespace, if any. An appropriate xmlns declaration is added if the namespace specified in name is not already defined in the element. If no element declaration is encountered, or the XML is malformed (eg. does not start with an element declaration), the string is returned as is, with no modifications.

Example:

string in =
    "<elementBefore><child1>text</child1><child2/></elementBefore>";
rwsf::XmlName afterName("elementAfter",
    rwsf::XmlNamespace("foo", "myUri"));
string out = rwsf::XmlUtils::changeName(afterName, in);
// out = <rw0:elementAfter xmlns:rw0="myUri">
//       <child1>text</child1><child2/>
//       </rw0:elementAfter>

compareAttributeSet() [1/2]

bool rwsf::XmlUtils::compareAttributeSet ( const rwsf::XmlAttributeSet & a1, const rwsf::XmlAttributeSet & a2 )

static

Returns true if set a1 is equal to set a2. Order may be different. This method checks that all namespaces in each attribute set are equivalent XML, but they need not be identical strings.

compareAttributeSet() [2/2]

bool rwsf::XmlUtils::compareAttributeSet ( const rwsf::XmlAttributeSet & a1, const rwsf::XmlAttributeSet & a2, std::string & compareInfo )

static

Returns true if set a1 is equal to set a2. Order may be different. This method checks that all namespaces in each attribute set are equivalent XML, but they need not be identical strings.

The compareInfo string contains diagnostic information about differences, if any are found.

convertCharset()

std::string rwsf::XmlUtils::convertCharset ( const std::string & buffer, const std::string & from, const std::string & to )

static

Converts a string buffer from the character encoding specified in from to the character encoding specified in to. Returns the string as an std::string. Valid values for from and to are governed by the ICU library. These are typically formatted as standard identifiers, but there are some ICU specific identifiers that may be used as well. See the ICU website for more information.

Exceptions

rwsf::XmlException

The conversion failed, see the message for more info.

convertDateTimeToISOString()

std::string rwsf::XmlUtils::convertDateTimeToISOString ( const rwsf::DateTime & dt, const std::string & format = ISO8601Format )

static

Converts an rwsf::DateTime dt to an ISO 8601 date string. The only format supported is ISO8601Format.

convertISODateStringToDateTime()

rwsf::DateTime rwsf::XmlUtils::convertISODateStringToDateTime ( const std::string & anISODateStr )

static

Converts an ISO 8601 date string anISODateStr to an rwsf::DateTime.

escapeText()

std::string rwsf::XmlUtils::escapeText ( const std::string & text )

static

Converts XML text to escaped text. For example, converts from:

<name>Your name here</name>

to:

<name>Your name here</name>

This conversion is necessary when passing XML as an xsd:string over the wire.

getElementValueAsString()

std::string rwsf::XmlUtils::getElementValueAsString ( const std::string & data )

static

Returns the contents of the element data as a string. If the XML in data is malformed, an exception is thrown. Otherwise, this method acts much like stripTag().

Exceptions

XmlParseException

The XML specified by data was malformed.

getPrefix()

std::string rwsf::XmlUtils::getPrefix ( const std::string & qName )

static

Returns the prefix in qName, or the empty string if no prefix is found.

getPrefixAndLocalName()

void rwsf::XmlUtils::getPrefixAndLocalName ( const std::string & qName, std::string & prefix, std::string & lname )

static

Extracts the prefix and local name from qName, storing the results in prefix and lname respectively. These are set to the empty string if one or the other is not present in qName.

isWhiteSpace()

bool rwsf::XmlUtils::isWhiteSpace ( const char c )

static

Returns true if c is whitespace.

stripTag() [1/2]

std::string rwsf::XmlUtils::stripTag ( const std::string & str, bool ignoreProlog = false )

static

Removes the outermost XML element tag from the given string str. If the string str does not start with an element declaration, or is malformed in any way (eg. the end tag isn't present or doesn't match the start tag), the string is returned untouched. Otherwise a string is returned with the outermost tag removed from the XML string.

Example:

string in =
    "<elementBefore><child1>text</child1><child2/></elementBefore>";
string out = rwsf::XmlUtils::stripTag(in);
// out = <child1>text</child1><child2/>

stripTag() [2/2]

std::string rwsf::XmlUtils::stripTag ( const std::string & str, const std::string & tag, bool ignoreProlog = false )

static

Deprecated

Please use stripTag(const std::string&, bool) instead.

This function acts just like stripTag(const std::string&, bool). The extra tag parameter is obsolete, and is not used.

Example:

string in =
    "<elementBefore><child1>text</child1><child2/></elementBefore>";
string out = rwsf::XmlUtils::stripTag(in);
// out = <child1>text</child1><child2/>

stripWhiteSpaceAndNewlines()

std::string rwsf::XmlUtils::stripWhiteSpaceAndNewlines ( const std::string & str, rwsf::stdStripType toStrip = rwsf::both )

static

Removes whitespace and newlines surrounding string str.

The parameter toStrip defines from which direction characters are stripped. See the enumeration stdStripType for details on the possible values. The default behavior is to strip from both the back and front of the string.

unescapeText()

std::string rwsf::XmlUtils::unescapeText ( const std::string & text )

static

Converts from escaped XML text to XML text. For example, converts from:

lt;name>Your name here</name>

to:

<name>Your name here</name>

wrapStringInTag() [1/2]

std::string rwsf::XmlUtils::wrapStringInTag ( const std::string & str, const rwsf::XmlName & tag )

static

Wraps the string str with an XML element declaration matching the XmlName given in tag. The string str need not be valid XML; it can be any string. If str is empty, the tag returned is an empty tag (<tagName/>) instead of a start and end tag. The namespace specified in tag is added to the element declaration with a prefix that does not collide with any specified in the string str.

Note

If a qualified name is required for tag, the parameter tag must be an instance of XmlName. Any element or type name used in an std::string is considered an unqualified local name, even if it contains a namespace prefix and/or URI.

Example:

string in = "<child1>text</child1><child2/>";
rwsf::XmlName afterName ("elementAfter",
                         rwsf::XmlNamespace("foo", "myUri"));
string out = rwsf::XmlUtils::wrapStringInTag(in, afterName);
// out = <rw0:elementAfter xmlns:rw0="myUri">
//       <child1>text</child1><child2/>
//       </rw0:elementAfter>

wrapStringInTag() [2/2]

std::string rwsf::XmlUtils::wrapStringInTag ( const std::string & str, const std::string & tag )

static

Wraps the string str with an XML element declaration matching the XmlName given in tag. The string str need not be valid XML; it can be any string. If str is empty, the tag returned is an empty tag (<tagName/>) instead of a start and end tag. The namespace specified in tag is added to the element declaration with a prefix that does not collide with any specified in the string str.

Note

If a qualified name is required for tag, the parameter tag must be an instance of XmlName. Any element or type name used in an std::string is considered an unqualified local name, even if it contains a namespace prefix and/or URI.

Example:

string in = "<child1>text</child1><child2/>";
rwsf::XmlName afterName ("elementAfter",
                         rwsf::XmlNamespace("foo", "myUri"));
string out = rwsf::XmlUtils::wrapStringInTag(in, afterName);
// out = <rw0:elementAfter xmlns:rw0="myUri">
//       <child1>text</child1><child2/>
//       </rw0:elementAfter>