# ADAT XML compatibility

This appendix records the compatibility target explicitly. "Compatible" means
the same useful XML shapes and query behavior, not source compatibility with
ADAT classes or preservation of every historical mutation and failure mode.

## Implemented in the core package

| Legacy capability | `xmlio` replacement | Status |
|---|---|---|
| File and stream readers | `XMLReader`, `from_file`, `from_string` | Complete |
| Reader rooted at an XPath subtree | `XMLReader(parent, path)` | Complete |
| Full XPath expressions | libxml2-backed reader queries | Complete |
| Registered XPath namespaces | `registerNamespace` | Complete |
| Primitive reads and writes | `read`, `write`, `get`, `operator<<` | Complete |
| Attribute reads and writes | XPath `@name`, `getAttribute`, `set_attr` | Complete |
| Query count and existence | `count`, `exists` | Complete |
| Query result and subtree printing | `print*`, `str`, `context_str`, `xpath_str` | Complete |
| Destructive scalar replacement | `set`, `set_text` | Complete |
| Tag stack and empty tags | `push`, `pop`, `openTag`, `closeTag`, `emptyTag` | Complete |
| In-memory and file writers | `XMLBufferWriter`, `XMLFileWriter` | Complete |
| Raw XML composition | `writeXML`, reader/writer `operator<<` | Complete |
| Complex values | `<re>` and `<im>` serialization | Complete |
| Primitive arrays | compact whitespace `std::vector`/`std::array` | Complete |
| Structured arrays | `<elem>`-based `std::vector`/`std::list` | Complete |
| Maps and pairs | `<Key>/<Val>` and `<First>/<Second>` | Complete representation |
| Merge several map documents | `read_map_into` with an explicit policy | Complete extension |
| Optional values | `std::optional`, `read_optional` | Complete extension |
| Repeated sibling values | `read_many`, `write_many` | Complete extension |
| Factory XML groups | `GroupXml`, `read_xml_*_group` and legacy spellings | Complete |

## Deliberate modernization

| Legacy behavior | Modern behavior |
|---|---|
| Exceptions thrown as `std::string`, or process termination | Typed `XmlError` exceptions |
| `XMLArray::Array<T>` | `std::vector<T>` or `std::array<T, N>` |
| One-based `ADAT::Array1dO<T>` | Zero-based standard containers |
| 7/15 digit floating output | `max_digits10` round-trip precision |
| Ambiguous source handling only through constructors | Explicit `from_*` and `load_from_*` APIs |
| Map reads insert silently into existing contents | `read` replaces; `read_map_into` makes collisions explicit |
| File writers stream tags directly to disk | `XMLFileWriter` buffers one DOM and serializes the complete document |

## Important behavioral differences

ADAT's `std::map` reader inserted entries without clearing the destination and
silently retained an existing value when keys collided. Some catalog-loading
code used that behavior to combine several files. In `xmlio`, ordinary `read`
has conventional replacement semantics and rejects duplicate keys within one
document. Use `read_map_into` with `DuplicateKeyPolicy::error`,
`keep_existing`, or `overwrite` when combining catalogs.

ADAT's file writer emitted XML incrementally. The current `XMLFileWriter` uses
the same DOM-backed implementation as `XMLBufferWriter`; `flush` and `close`
serialize the complete current document. This gives consistent validation and
subtree composition for normal configuration and result files, but it is not a
streaming solution for extremely large graph exports.

## Compatibility adapters not in the core

The following APIs are not used by `scattering_devel` and are intentionally not
part of the core package:

- `XMLArrayWriter`, the stateful fixed-size streaming array writer.
- `XMLStructWriterBase` and its pointer-owned child-writer API.
- `XMLSimpleSchemaWriter` and `XMLSchemaWriter`, which emit XSD alongside XML.
- Source-level aliases in the old `ADATXML`, `XMLWriterAPI`, and `XMLArray`
  namespaces.

If legacy applications need source-level migration, these belong in a separate
`xmlio_adat_compat` adapter. Keeping them out of the core prevents obsolete
ownership and one-based-container conventions from becoming dependencies of
the new analysis suite.