9. API Reference

This reference documents the public C++ interface exposed by include/xmlio/. Function overloads are presented together under their owning namespace.

namespace xmlio

ADAT-style, C++23 XML reading, writing, and serialization facilities.

The public API deliberately exposes no libxml2 types. XMLReader provides XPath-based access, XMLWriter builds documents through a tag stack, and free read/write overloads map XML representations to C++ values. Applications extend serialization by placing overloads beside their own types so normal argument-dependent lookup finds them.

ADAT-compatible group helper spellings

inline GroupXML_t readXMLGroup(XMLReader &xml, std::string_view path, std::string_view type_name): Compatibility wrapper for read_xml_group.

inline std::vector<GroupXML_t> readXMLVectorGroup(XMLReader &xml, std::string_view path, std::string_view type_name): Compatibility wrapper for read_xml_vector_group.

inline std::vector<GroupXML_t> readXMLArrayGroup(XMLReader &xml, std::string_view path, std::string_view type_name): Historical array spelling for read_xml_vector_group.

Scalar and structured reads

inline void read(XMLReader &xml, std::string_view path, std::string &output)

Read one string value from path.

Parameters:

xml – Reader that supplies the query context.
path – XPath selecting exactly one scalar node.
output – String replaced with the selected text, without trimming.

Throws:

QueryError – if the query does not select one scalar node.

inline void read(XMLReader &xml, std::string_view path, char &output)

Read one character from path.

Throws:: ConversionError – unless the untrimmed content has length one.

template<detail::XmlArithmetic T> inline void read(XMLReader &xml, std::string_view path, T &output)

Strictly read one arithmetic value from path.

Parameters:

xml – Reader that supplies the query context.
path – XPath selecting exactly one scalar node.
output – Destination assigned after successful conversion.

Throws:

QueryError – if the query is not uniquely scalar.
ConversionError – if the complete text cannot be converted to T.

template<typename T> void read(XMLReader &xml, std::string_view path, std::complex<T> &output)

Read a complex value represented by <re> and <im> children.

<z><re>1.5</re><im>-0.25</im></z>

Template Parameters:

T – Component type with an available read overload.

Parameters:

xml – Reader that supplies the query context.
path – XPath selecting the complex-value wrapper.
output – Complex value assigned after both components are read.

Throws:

QueryError – when the wrapper or a component is missing or non-unique.

template<typename First, typename Second> void read(XMLReader &xml, std::string_view path, std::pair<First, Second> &output)

Read a pair represented by <First> and <Second> children.

Component names are capitalized for compatibility with ADAT data.

Template Parameters:

First – Type read from <First>.
Second – Type read from <Second>.

template<typename Key, typename Value, typename Compare, typename Allocator> void read(XMLReader &xml, std::string_view path, std::map<Key, Value, Compare, Allocator> &output)

Replace a map from <elem><Key>...<Val>... records.

<masses>
  <elem><Key>pi</Key><Val>0.06906</Val></elem>
  <elem><Key>K</Key><Val>0.09698</Val></elem>
</masses>

Elements are inserted through the map’s comparator. Two XML keys that compare equivalent are therefore duplicates even if their textual forms differ.

Note

A failure after reading begins may leave output partially populated.

Parameters:

xml – Reader that supplies the query context.
path – XPath selecting the map wrapper.
output – Map cleared before records are read.

Throws:

QueryError – for malformed records or duplicate keys.

template<typename Key, typename Value, typename Compare, typename Allocator> void read_map_into(XMLReader &xml, std::string_view path, std::map<Key, Value, Compare, Allocator> &output, DuplicateKeyPolicy policy = DuplicateKeyPolicy::error)

Read an XML map and merge it into an existing destination map.

Ordinary read replaces a map’s contents. This explicit operation is for catalog-style workflows that combine several XML documents. The incoming document is validated completely before the destination is changed.

Note

The destination is unchanged if parsing the incoming map fails. With DuplicateKeyPolicy::error it is also unchanged when a collision is detected.

Parameters:

xml – Source document.
path – Path selecting a map represented by <elem> records.
output – Existing map that receives the incoming entries.
policy – Action to take when an incoming key already exists in output.

Throws:

QueryError – for duplicate keys in one document or, with DuplicateKeyPolicy::error, a collision with output.

template<typename T, typename Allocator> void read(XMLReader &xml, std::string_view path, std::vector<T, Allocator> &output)

Read a compact arithmetic vector or a structured <elem> vector.

Arithmetic vectors also accept <elem> input to ease migration between historical formats.

Note

A read failure may leave output partially populated.

Parameters:

xml – Reader that supplies the query context.
path – XPath selecting the sequence wrapper.
output – Vector replaced by values in document order.

Throws:

QueryError – for a malformed wrapper or structured element.
ConversionError – for an invalid arithmetic token.

template<typename T, typename Allocator> void read(XMLReader &xml, std::string_view path, std::list<T, Allocator> &output)

Read a list using the same representation as a vector.

Parameters:

xml – Reader that supplies the query context.
path – XPath selecting the sequence wrapper.
output – List replaced only after the temporary vector is read fully.

template<typename T, std::size_t Size> void read(XMLReader &xml, std::string_view path, std::array<T, Size> &output)

Read exactly Size values into a fixed-size array.

Parameters:

xml – Reader that supplies the query context.
path – XPath selecting the sequence wrapper.
output – Array replaced only after conversion and size validation succeed.

Throws:

QueryError – if the input value count differs from Size.

template<typename T> void read(XMLReader &xml, std::string_view path, std::optional<T> &output)

Read a value when present, otherwise reset the optional.

Note

Invalid present values still propagate their query or conversion error.

Parameters:

xml – Reader that supplies the query context.
path – XPath tested for existence and read when present.
output – Optional reset for a missing path and replaced after a successful read.

template<typename T> T read(XMLReader &xml, std::string_view path)

Return a newly constructed value read from path.

Template Parameters:: T – Default-constructible type with a discoverable read overload.
Returns:: Fully populated value.

template<typename T> bool read_optional(XMLReader &xml, std::string_view path, T &output)

Conditionally read into an existing destination.

Note

Query and conversion errors from a present value still propagate.

Returns:: false without modifying output when path is missing; true after a successful read.

template<typename T> std::optional<T> read_optional(XMLReader &xml, std::string_view path)

Conditionally construct and return a value.

Note

Query and conversion errors from a present value still propagate.

Returns:: std::nullopt for a missing path, otherwise a populated optional.

template<typename T> void read_many(XMLReader &xml, std::string_view path, std::vector<T> &output)

Read every scalar sibling selected by one XPath expression.

Unlike container read, path selects the repeated values themselves, for example "hadron/mass", rather than their common parent.

Parameters:

xml – Reader that supplies the query context.
path – XPath selecting zero or more scalar nodes.
output – Vector replaced in XPath document order.

Throws:

QueryError – if path is not a node-set query or selects a structured value.
ConversionError – for an invalid arithmetic item; the diagnostic path includes its zero-based result index.

Scalar and structured writes

inline void write(XMLWriter &xml, std::string_view path, std::string_view value)

Write one string child element.

Parameters:

xml – Writer whose current element becomes the new child’s parent.
path – Name of the child element, not an XPath expression.
value – Unescaped text; XMLWriter performs XML escaping.

inline void write(XMLWriter &xml, std::string_view path, const std::string &value): std::string overload for writing one string child element.

inline void write(XMLWriter &xml, std::string_view path, const char *value): C-string overload; a null pointer writes an empty child element.

inline void write(XMLWriter &xml, std::string_view path, char value): Write one character in a child element.

template<detail::XmlArithmetic T> inline void write(XMLWriter &xml, std::string_view path, const T &value)

Write one arithmetic child element.

Conversion is locale-independent, floating-point values use round-trip precision, and booleans are written as true or false.

template<typename T> void write(XMLWriter &xml, std::string_view path, const std::complex<T> &value)

Write a complex value using <re> and <im> children.