.. _xmlio-serialization:

Types and XML Representations
=============================

Representation summary
----------------------

``xmlio`` deliberately uses a small set of predictable XML shapes.

.. list-table:: Built-in serialization forms
   :header-rows: 1
   :widths: 28 28 44

   * - C++ value
     - XML shape
     - Notes
   * - String, character, arithmetic value
     - One scalar element
     - Booleans are written as ``true`` or ``false``.
   * - ``std::complex<T>``
     - ``<re>`` and ``<im>`` children
     - Both components use the scalar representation.
   * - Arithmetic ``vector``, ``list``, or ``array``
     - Whitespace-separated scalar text
     - Arithmetic vectors also accept ``<elem>`` input.
   * - Structured ``vector``, ``list``, or ``array``
     - Repeated ``<elem>`` children
     - Includes strings and user-defined records.
   * - ``std::pair<A, B>``
     - ``<First>`` and ``<Second>`` children
     - Each side may itself be structured.
   * - ``std::map<K, V>``
     - ``<elem><Key>...<Val>...`` records
     - Duplicate keys within one document are rejected.
   * - ``std::optional<T>``
     - The normal representation of ``T``, or no element
     - An empty optional is omitted when writing.
   * - Repeated scalar siblings
     - Several elements with the same name
     - Use ``read_many`` and ``write_many``.

Scalar values
-------------

Floating-point output uses ``max_digits10`` so values can round trip without
precision loss. Scalar conversion is locale independent and rejects trailing
characters. Boolean input accepts ``true``, ``false``, their common uppercase
forms, and ``1`` or ``0``.

Complex numbers
---------------

.. code-block:: xml

   <offset>
     <re>1.25</re>
     <im>-0.5</im>
   </offset>

.. code-block:: cpp

   const auto offset =
       xmlio::read<std::complex<double>>(xml, "/settings/offset");

Sequential containers
---------------------

Arithmetic containers are compact:

.. code-block:: xml

   <weights>0.25 0.5 0.25</weights>

Strings and records use explicit elements:

.. code-block:: xml

   <labels>
     <elem>small</elem>
     <elem>portable</elem>
   </labels>

A fixed-size ``std::array`` additionally checks that the XML contains exactly
the required number of values.

Pairs and maps
--------------

A pair is represented as:

.. code-block:: xml

   <range>
     <First>0</First>
     <Second>10</Second>
   </range>

A map is represented as an array of key-value records:

.. code-block:: xml

   <catalog>
     <elem><Key>blue</Key><Val>1</Val></elem>
     <elem><Key>red</Key><Val>2</Val></elem>
   </catalog>

Ordinary ``read`` replaces the destination map. Catalog workflows that combine
several documents should use ``read_map_into`` and choose a collision policy:

``DuplicateKeyPolicy::error``
   Reject a collision and leave the destination unchanged. This is the default.

``DuplicateKeyPolicy::keep_existing``
   Keep the destination value and ignore an incoming value with the same key.

``DuplicateKeyPolicy::overwrite``
   Replace the destination value with the incoming value.

Duplicate keys inside one incoming XML map are always errors, independent of
the merge policy.

.. literalinclude:: examples/catalog_merge.cpp
   :language: cpp
   :linenos:

Optional values
---------------

Writing an empty ``std::optional`` omits the element. Reading into an optional
resets it when the path does not exist:

.. code-block:: cpp

   std::optional<int> retries;
   xmlio::read(xml, "/settings/retries", retries);

Use a required field with an explicit default in application code when absence
has a documented meaning:

.. code-block:: cpp

   int retries = 3;
   xmlio::read_optional(xml, "/settings/retries", retries);

Repeated siblings
-----------------

``write_many`` emits every range item under the same tag name. ``read_many``
reads scalar or string siblings selected by one XPath expression. Structured
collections should normally use the standard ``<elem>`` container form so a
single parent names and owns the collection.