zenXML
Straightforward C++ XML Processing
Public Member Functions
zen::XmlIn Class Reference

Proxy class to conveniently convert XML structure to user data. More...

#include <zenxml_bind.h>

List of all members.

Public Member Functions

 XmlIn (const XmlDoc &doc)
 Construct an input proxy for an XML document.
 XmlIn (const XmlElement *element)
 Construct an input proxy for a single XML element, may be NULL.
 XmlIn (const XmlElement &element)
 Construct an input proxy for a single XML element.
template<class String >
XmlIn operator[] (const String &name) const
 Retrieve a handle to an XML child element for reading.
void next ()
 Refer to next sibling element with the same name.
template<class T >
bool operator() (T &value) const
 Read user data from the underlying XML element.
template<class String , class T >
bool attribute (const String &name, T &value) const
 Read user data from an XML attribute.
const XmlElementget () const
 Return a pointer to the underlying Xml element, may be NULL.
 operator int ConversionToBool::* () const
 Test whether underlying XML element exists.
bool errorsOccured () const
 Indicate whether errors occurred while mapping the XML to user data.
template<class String >
std::vector< String > getErrorsAs () const
 Get a list of XML element and attribute names which failed to convert to user data.

Detailed Description

Proxy class to conveniently convert XML structure to user data.


Constructor & Destructor Documentation

zen::XmlIn::XmlIn ( const XmlDoc doc)

Construct an input proxy for an XML document.

        zen::XmlDoc doc;
          ... //load document
        zen::XmlIn in(doc);
        in["elem1"](value1); //
        in["elem2"](value2); //write data of XML elements into variables "value1", "value2", "value3"
        in["elem3"](value3); //
zen::XmlIn::XmlIn ( const XmlElement element)

Construct an input proxy for a single XML element, may be NULL.

See also:
XmlIn(const XmlDoc& doc)
zen::XmlIn::XmlIn ( const XmlElement element)

Construct an input proxy for a single XML element.

See also:
XmlIn(const XmlDoc& doc)

Member Function Documentation

template<class String , class T >
bool zen::XmlIn::attribute ( const String &  name,
T &  value 
) const

Read user data from an XML attribute.

This conversion requires a specialization of zen::readText() for type T.

        zen::XmlDoc doc;
          ... //load document
        zen::XmlIn in(doc);
        in["elem"].attribute("attr1", value1); //
        in["elem"].attribute("attr2", value2); //write data of XML attributes into variables "value1", "value2", "value3"
        in["elem"].attribute("attr3", value3); //
Template Parameters:
StringArbitrary string-like type: e.g. std::string, wchar_t*, char[], wchar_t, wxString, MyStringClass, ...
TUser type that is converted into an XML attribute value.
See also:
XmlElement::getAttribute()
bool zen::XmlIn::errorsOccured ( ) const

Indicate whether errors occurred while mapping the XML to user data.

Error logging is shared by each hiearchy of XmlIn proxy instances that are created from each other. Consequently it doesn't matter which instance you query for errors:

        XmlIn in(doc);
        XmlIn inItem = in["item1"];

        int value = 0;
        inItem(value); //assume this conversion failed

        assert(in.errorsOccured() == inItem.errorsOccured());
        assert(in.getErrorsAs<std::string>() == inItem.getErrorsAs<std::string>());

Note that error logging is NOT global, but owned by all instances of a hierarchy of XmlIn proxies. So the library does not compromise correctness in multithreaded application.

However be aware that the chain of connected proxy instances will be broken once you call XmlIn::get() to retrieve the underlying pointer. Errors that occur when working with this pointer are not logged by the original set of related instances.

template<class String >
std::vector<String> zen::XmlIn::getErrorsAs ( ) const

Get a list of XML element and attribute names which failed to convert to user data.

Template Parameters:
StringArbitrary string class: e.g. std::string, std::wstring, wxString, MyStringClass, ...
Returns:
A list of XML element and attribute names, empty list if no errors occured.
void zen::XmlIn::next ( )

Refer to next sibling element with the same name.

Example: Loop over all XML child elements named "Item"

    <?xml version="1.0" encoding="UTF-8"?>
    <Root>
        <Item>1</Item>
        <Item>3</Item>
        <Item>5</Item>
    </Root>
    
    zen::XmlIn in(doc);
    ...
    for (zen::XmlIn child = in["Item"]; child; child.next())
    {
        ...
    }
zen::XmlIn::operator int ConversionToBool::* ( ) const

Test whether underlying XML element exists.

         XmlIn in(doc);
         XmlIn child = in["elem1"];
         if (child)
           ...

Use member pointer as implicit conversion to bool (C++ Templates - Vandevoorde/Josuttis; chapter 20)

template<class T >
bool zen::XmlIn::operator() ( T &  value) const

Read user data from the underlying XML element.

This conversion requires a specialization of zen::readText() or zen::readValue() for type T.

Template Parameters:
TUser type that receives the data
Returns:
"true" if data was read successfully
template<class String >
XmlIn zen::XmlIn::operator[] ( const String &  name) const

Retrieve a handle to an XML child element for reading.

It is not an error if the child element does not exist, but a subsequent conversion to user data will fail.

Template Parameters:
StringArbitrary string-like type: e.g. std::string, wchar_t*, char[], wchar_t, wxString, MyStringClass, ...
Parameters:
nameThe name of the child element
 All Classes Namespaces Functions Variables