zen::Xml: zen::XmlIn Class Reference

| zen::Xml Simple C++ XML Processing

- Main Page
- Namespaces
- Classes

- Class List
- Class Index
- Class Hierarchy
- Class Members

All Classes Namespaces Functions Variables Pages
Public Member Functions | List of all members
zen::XmlIn Class Reference

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

`#include <bind.h>`

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

## 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); //read data from 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 nullptr.

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); //read data from XML attributes into variables "value1", "value2", "value3"
in["elem"].attribute("attr3", value3); //

Template Parameters

  String | Arbitrary string-like type: e.g. std::string, wchar_t*, char[], wchar_t, wxString, MyStringClass, ...
  T | String-convertible user data type: e.g. any string-like type, all built-in arithmetic numbers

Returns
  "true" if the attribute was found and the conversion to the output value was successful.

See also
  XmlElement::getAttribute()

bool zen::XmlIn::errorsOccured | ( |  | ) | const

Notifies errors 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); //let's 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. Therefore it's safe to use unrelated XmlIn proxies in multiple threads.
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

  String | Arbitrary 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 bool | ( |  | ) | const
| explicit

Test whether the 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::readStruc() for type T.

Template Parameters

  T | User 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 only later if a conversion to user data is attempted.

Template Parameters

  String | Arbitrary string-like type: e.g. std::string, wchar_t*, char[], wchar_t, wxString, MyStringClass, ...

Parameters

  name | The name of the child element