API Reference

A guided tour of the public surface. For the always-current, fully generated reference see docs.rs/draviavemal-xml_rs.

use draviavemal_xml_rs::{
    XmlDeserializer, XmlSerializer, SerializeOptions,
    XmlDocument, XmlElement, XmlAttribute,
    XmlElementContentType, NamespaceDeclaration,
};

Types

Type	Description
`NodeId`	`u32` identifier of a node within a document.
`Tag` / `NsTag`	`String` aliases for a local and namespaced tag name.
`NsAlias` / `NsUrl`	`String` aliases for a namespace prefix and its URI.
`XmlElementContentType`	Enum of an element’s possible children — see below.
`NamespaceDeclaration`	A URI + canonical alias pairing passed to the `*_ns` APIs — see below.
`SerializeOptions`	Controls namespace optimization on serialize — see below.

`XmlDeserializer`

XML → XmlDocument. Stateless; call the associated functions. Input is treated as UTF-8; the XML declaration (version, encoding, standalone), namespaces, attribute order, comments and mixed content are all preserved.

Function	Returns
`vec_to_xml_doc_tree(xml: Vec<u8>)`	`Result<XmlDocument>`
`file_to_xml_doc_tree(path: &str)`	`Result<XmlDocument>`

`XmlSerializer`

XmlDocument → XML. Round-trip safe — original prefixes, attribute order and comments are re-emitted. The document is borrowed immutably (&XmlDocument).

Function	Returns
`xml_tree_to_vec(doc: &XmlDocument)`	`Result<Vec<u8>>`
`xml_tree_to_vec_with(doc: &XmlDocument, opts: &SerializeOptions)`	`Result<Vec<u8>>`
`xml_doc_tree_to_file(doc: &XmlDocument, path: &str)`	`Result<()>`
`xml_doc_tree_to_file_with(doc: &XmlDocument, path: &str, opts: &SerializeOptions)`	`Result<()>`

`SerializeOptions`

Member	Purpose
`optimize_namespaces: bool`	When `true`, hoists every prefixed `xmlns` declaration to the lowest common ancestor of its uses and drops declarations that are never referenced. Defaults to `false`.
`default()`	The default options (`optimize_namespaces: false`).

`XmlDocument`

The DOM tree and node store. All elements are referenced by their NodeId.

Construction & document metadata

Method	Purpose
`new()` / `default()`	Create an empty document (version `1.0`, encoding `UTF-8`).
`clone()`	Deep-clone the document and its node store.
`get_root_id()`	`NodeId` of the root element.
`get_version()` / `set_version_mut(String)`	Read / set the XML declaration version.
`get_encoding()` / `set_encoding_mut(String)`	Read / set the XML declaration encoding.
`get_standalone()` / `set_standalone_mut(Option<String>)`	Read / set the `standalone` declaration value.
`get_prolog_comments()` / `add_prolog_comment_mut(String)`	Read / append comments that appear before the root element.

Method	Purpose
`get_element(id)` / `get_element_mut(id)`	Look up an element (immutable / mutable) → `Result<&XmlElement>`.
`get_parent(id)`	Parent `NodeId`, or `None` for the root.
`get_children(id)`	All direct child element ids, in document order.
`get_first_child_element(id)` / `get_last_child_element(id)`	First / last direct child element id.
`get_next_sibling(id)` / `get_previous_sibling(id)`	Following / preceding sibling element id under the same parent.

Creating elements

Method	Purpose
`create_root_element_mut(tag, attrs)`	Create the root element from a raw tag; returns its `NodeId`.
`create_root_element_ns_mut(local_name, &ns, attrs)`	Create the root element, declaring the namespace from `ns`.
`append_child_element_mut(parent, tag, attrs)`	Append a child from a raw tag; returns its `NodeId`.
`append_child_element_ns_mut(parent, local_name, &ns, attrs)`	Append a namespaced child, declaring `ns` only when not already in scope.
`insert_child_element_after_last_tag_mut(parent, tag, after_tag, attrs)`	Insert after the last matching tag (namespaced when `after_tag` contains `:`).
`insert_child_element_before_first_tag_mut(parent, tag, before_tag, attrs)`	Insert before the first matching tag.
`insert_child_element_after_last_tag_ns_mut(…)`	Namespaced variant; the reference tag is resolved through its own `NamespaceDeclaration`.
`insert_child_element_before_first_tag_ns_mut(…)`	Namespaced variant of the before-first insert.

Finding & querying

Method	Purpose
`find_first_child(parent, tag)` / `find_first_child_ns(parent, local_name, &ns)`	First direct child by tag → `Option<NodeId>`.
`find_all_child(parent, tag)` / `find_all_child_ns(parent, local_name, &ns)`	All direct children by tag → `Option<Vec<NodeId>>`.
`find_first_by_attribute(parent, name, value)` / `find_first_by_attribute_ns(parent, name, &ns, value)`	First direct child matching an attribute.
`find_all_by_attribute(parent, name, value)` / `find_all_by_attribute_ns(parent, name, &ns, value)`	All direct children matching an attribute.
`get_elements_by_tag_name(parent, tag)` / `get_elements_by_tag_name_ns(parent, local_name, &ns)`	All descendants matching a tag (whole subtree).
`get_element_text_content(id)`	Concatenated text of every descendant text node.
`lookup_namespace_uri(id, prefix)`	URI bound to `prefix` in the element’s scope.
`lookup_prefix(id, uri)`	In-scope prefix bound to `uri`.

Editing

Method	Purpose
`set_element_text_mut(id, text)`	Replace an element’s entire content with a single text node.
`resolve_alias_mut(id, &ns)`	Resolve (declaring if needed) the alias for `ns` in an element’s scope.
`clear_element_content_mut(id)`	Remove all children of an element, keeping the element.
`remove_element_mut(id)`	Remove an element and its entire subtree.

`XmlElement`

A single element node.

Identity & tag

Method	Purpose
`get_id()` / `get_parent_id()`	Node id / parent id (`Option<NodeId>`).
`get_tag()` / `get_tag_ns()`	Local / namespaced (`prefix:tag`) tag name.
`get_prefix()`	The tag’s namespace prefix, or `None` when unprefixed.
`get_namespace_uri()`	URI bound to the tag in the element’s own scope.

Reading content

Method	Purpose
`get_child_contents()` / `get_child_contents_mut()`	The list of `XmlElementContentType` (immutable / mutable).
`get_child_element_count()`	Count of child elements only.
`get_child_element_ids()`	Ids of all direct child elements, in document order.
`get_first_child_element()` / `get_last_child_element()`	First / last direct child element id.
`get_element_text_value()`	The first direct text node’s value, if any.
`get_text_content()`	All direct text nodes concatenated.
`find_first_child(tag)` / `find_first_child_ns(local_name, &ns)`	First child element by tag.
`find_all_child(tag)` / `find_all_child_ns(local_name, &ns)`	All child elements by tag.

Attributes

Method	Purpose
`get_attribute(name)` / `get_attribute_ns(name, &ns)`	Read an attribute (`_ns` matches by URI, alias-independent).
`get_attribute_by_uri(uri, local_name)`	Read an attribute by explicit namespace URI + local name.
`get_attribute_value(name)` / `get_attribute_value_ns(name, &ns)`	Read just the value → `Option<&str>`.
`has_attribute(name)` / `has_attribute_ns(name, &ns)`	Presence check.
`get_attribute_keys()` / `get_attribute_ns_keys()`	Local / namespaced names of all attributes.
`add_attribute_mut(name, value)` / `add_attribute_ns_mut(local_name, &ns, value)`	Add an attribute; errors if the name already exists.
`add_replace_attribute_mut(name, value)` / `add_replace_attribute_ns_mut(local_name, &ns, value)`	Add or replace an attribute of the same name.
`set_attribute_mut(Vec<XmlAttribute>)`	Set initial attributes; errors if attributes already exist.
`remove_attribute_mut(name)` / `remove_attribute_ns_mut(local_name, &ns)`	Remove an attribute.
`clear_attribute_mut()`	Remove all attributes; returns the count removed.

Text, comments & namespaces

Method	Purpose
`add_text_mut(text)`	Append a text node.
`set_text_mut(text)`	Replace every direct text node with a single one (elements/comments untouched).
`add_comments_mut(comment)`	Append a comment node.
`add_namespaces_mut(&[NamespaceDeclaration])`	Declare namespaces on this element’s scope for later manual use.
`resolve_alias_mut(&ns)`	Resolve (declaring if needed) the alias for `ns` in this scope.
`get_alias_for_uri(uri)`	The in-scope alias currently bound to `uri`.

`XmlAttribute`

Member	Purpose
`new(name: String, value: String)`	Construct; a `prefix:name` is split into prefix + local name.
`get_name()`	Local name without prefix → `&str`.
`get_ns_name()`	Namespaced name (`prefix:name`) when a prefix is present → `String`.
`get_value()`	Attribute value → `&str`.
`get_ns_alias()`	The stored prefix, or `None` → `Option<&str>`.

`NamespaceDeclaration`

A Copy value pairing a namespace URI with its canonical alias, passed to every *_ns API. Resolution precedence is alias_override > the alias already in scope for the URI > default_alias.

Member	Purpose
`uri: &‘static str`	The W3C namespace URI.
`default_alias: &‘static str`	Alias used when the URI is not already declared in scope.
`alias_override: Option<&‘static str>`	Forces this alias regardless of any alias already bound to the URI.
`new(uri, default_alias)`	`const` constructor with no override.
`with_override(uri, default_alias, alias_override)`	`const` constructor that forces a specific prefix.

const MAIN_NS: NamespaceDeclaration = NamespaceDeclaration::new(
    "http://schemas.openxmlformats.org/spreadsheetml/2006/main",
    "main",
);

`XmlElementContentType`

Enum of an element’s possible children:

Variant	Holds
`Element((NodeId, Tag, NsTag))`	A child element reference.
`Text(String)`	A text node.
`Comment(String)`	A comment node.

API Reference

Types

XmlDeserializer

XmlSerializer

SerializeOptions

XmlDocument