10. 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.

10.1. 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 buffered file writers	XMLBufferWriter, XMLFileWriter	Complete
Incremental file or stream writer	XMLStreamWriter	Complete modernization
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

10.2. 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
One file-writer name covered two storage models	XMLFileWriter is DOM-backed; XMLStreamWriter is explicitly incremental
Buffer-writer str() implicitly omitted the declaration	document_str and fragment_str state the intended representation explicitly

10.3. 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. In xmlio, the storage choice is part of the type: XMLFileWriter retains a DOM for normal configuration and result files, while XMLStreamWriter writes large graph and event documents with memory proportional to nesting depth. Both accept the same tag operations and typed write overloads.

ADAT’s XMLBufferWriter::str() returned a root fragment without an XML declaration. The established xmlio::str() default still returns a standalone document for compatibility with existing xmlio clients. New code should use document_str() or fragment_str() whenever that distinction matters.

10.4. 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.