HydraExpress™ C++ API Reference Guide

 Product Documentation:
   HydraExpress C++
Documentation Home
List of all members | Static Public Member Functions | Related Functions
rwsf::XmlUtils Class Reference
Core Basic » Core XML

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)
 

Related Functions

(Note that these are not member functions.)

enum  stdStripType
 

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

static 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/></elementAfter>
static 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.

static 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.

static 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::XmlExceptionThe conversion failed, see the message for more info.
static 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.

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

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

static 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:

&lt;name&gt;Your name here&lt;/name&gt;

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

static 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
XmlParseExceptionThe XML specified by data was malformed.
static std::string rwsf::XmlUtils::getPrefix ( const std::string &  qName)
static

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

static 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.

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

Returns true if c is whitespace.

static 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/>
static 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/>
static 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.

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

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

lt;name&gt;Your name here&lt;/name&gt;

to:

<name>Your name here</name>
static 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/></elementAfter>
static 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/></elementAfter>

Friends And Related Function Documentation

enum stdStripType
related

Enumeration that governs how whitespace is stripped in utility functions.

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.