Struct Document 

pub struct Document {
    pub version: Option<String>,
    pub encoding: Option<String>,
    pub standalone: Option<bool>,
    pub diagnostics: Vec<ParseDiagnostic>,
    /* private fields */
}

An XML document.

The Document owns all nodes in an arena and provides methods for tree navigation and mutation. All tree operations go through &Document (navigation) or &mut Document (mutation).

Examples

use xmloxide::Document;

let doc = Document::parse_str("<root/>").unwrap();
let root = doc.root_element().unwrap();
assert_eq!(doc.node_name(root), Some("root"));

Fields

version: Option<String>

XML version from the XML declaration (e.g., “1.0”).

encoding: Option<String>

Encoding from the XML declaration (e.g., “UTF-8”).

standalone: Option<bool>

Standalone flag from the XML declaration.

diagnostics: Vec<ParseDiagnostic>

Diagnostics collected during parsing (warnings and recovered errors).

Implementations

impl Document

pub fn new() -> Self

Creates a new empty document.

The document contains a single root Document node.

pub fn with_capacity(n: usize) -> Self

Creates a new empty document with pre-allocated capacity for n nodes.

pub fn parse_str(input: &str) -> Result<Self, ParseError>

Parses an XML string into a Document.

Errors

Returns ParseError if the input is not well-formed XML.

Examples

use xmloxide::Document;

let doc = Document::parse_str("<root><child/></root>").unwrap();

pub fn parse_bytes(input: &[u8]) -> Result<Self, ParseError>

Parses XML from raw bytes, detecting encoding automatically.

Uses BOM sniffing and XML declaration inspection to determine the encoding, then transcodes to UTF-8 before parsing. See crate::encoding::decode_to_utf8 for the full detection pipeline.

Errors

Returns ParseError if the encoding cannot be determined, the bytes cannot be transcoded, or the resulting XML is not well-formed.

Examples

use xmloxide::Document;

let doc = Document::parse_bytes(b"<root/>").unwrap();
let root = doc.root_element().unwrap();
assert_eq!(doc.node_name(root), Some("root"));

pub fn parse_file<P: AsRef<Path>>(path: P) -> Result<Self, ParseError>

Parses an XML file from the filesystem.

Reads the file as raw bytes and uses automatic encoding detection (BOM sniffing and XML declaration inspection) before parsing.

Errors

Returns ParseError if the file cannot be read, the encoding cannot be determined, or the XML is not well-formed.

Examples

use xmloxide::Document;

let doc = Document::parse_file("document.xml").unwrap();

pub fn root(&self) -> NodeId

Returns the document root NodeId.

This is the synthetic Document node that sits above the root element, processing instructions, comments, and DOCTYPE in the prolog. To get the root element, use root_element.

pub fn root_element(&self) -> Option<NodeId>

Returns the root element of the document (the single top-level element).

Returns None if the document has no element children.

pub fn node(&self, id: NodeId) -> &NodeData

Returns a reference to the NodeData for the given node.

Use this to inspect a node’s kind and navigation links. For common queries, prefer the typed accessors like node_name and node_text.

Panics

Panics if id does not refer to a valid node in this document.

pub fn is_element(&self, id: NodeId) -> bool

Returns true if the node is an element.

pub fn node_name(&self, id: NodeId) -> Option<&str>

Returns the local name of a node, if applicable.

For elements, this is the tag name (e.g., "div"). For processing instructions, this is the target (e.g., "xml-stylesheet"). Text, comment, CDATA, and document nodes return None.

pub fn node_namespace(&self, id: NodeId) -> Option<&str>

Returns the namespace URI of an element node, if any.

Non-element nodes always return None. Elements that have no namespace declaration in scope also return None.

pub fn node_prefix(&self, id: NodeId) -> Option<&str>

Returns the namespace prefix of an element node, if any.

For example, returns Some("svg") for <svg:rect>. Non-element nodes always return None.

pub fn node_text(&self, id: NodeId) -> Option<&str>

Returns the direct text content of a text, comment, CDATA, or PI node.

For text, comment, and CDATA nodes, returns their string content. For processing instructions, returns the data portion (after the target). For element nodes, returns None — use text_content to get the concatenated text of all descendant text nodes.

pub fn text_content(&self, id: NodeId) -> String

Returns the concatenated text content of a node and all its descendants.

Recursively collects text from all descendant text and CDATA nodes. For a leaf text node, this is equivalent to node_text. For an element, this concatenates all nested text content (matching the DOM textContent property).

pub fn attributes(&self, id: NodeId) -> &[Attribute]

Returns the attributes of an element node as a slice.

Each Attribute contains the name, value, optional namespace prefix, and namespace URI. Returns an empty slice for non-element nodes.

pub fn attribute(&self, id: NodeId, name: &str) -> Option<&str>

Returns the value of an attribute by local name on an element node.

Performs a linear scan of the element’s attributes. Returns None if the attribute is not present or the node is not an element.

pub fn set_id(&mut self, id: &str, node: NodeId)

Associates an ID value with an element node.

Called during DTD validation when an attribute of type ID is found. Subsequent calls to element_by_id will return the associated node.

pub fn element_by_id(&self, id: &str) -> Option<NodeId>

Looks up an element by its ID attribute value.

Returns the NodeId of the element that was registered with set_id for the given ID string, or None if no such ID exists.

pub fn parent(&self, id: NodeId) -> Option<NodeId>

Returns the parent of a node, or None for the document root.

pub fn first_child(&self, id: NodeId) -> Option<NodeId>

Returns the first child of a node, or None if it has no children.

pub fn last_child(&self, id: NodeId) -> Option<NodeId>

Returns the last child of a node, or None if it has no children.

pub fn next_sibling(&self, id: NodeId) -> Option<NodeId>

Returns the next sibling of a node, or None if it is the last child.

pub fn prev_sibling(&self, id: NodeId) -> Option<NodeId>

Returns the previous sibling of a node, or None if it is the first child.

pub fn children(&self, id: NodeId) -> Children<'_>

Returns an iterator over the direct children of a node.

Yields each child NodeId in document order (first child to last). For a depth-first traversal that includes nested descendants, use descendants.

pub fn ancestors(&self, id: NodeId) -> Ancestors<'_>

Returns an iterator over a node and its ancestors, walking up to the document root.

The first item yielded is id itself, followed by its parent, then grandparent, and so on up to the document root node.

pub fn descendants(&self, id: NodeId) -> Descendants<'_>

Returns an iterator over all descendants of a node in depth-first (pre-order) traversal.

Does not yield id itself — only its children, grandchildren, etc. For iterating only the direct children, use children.

pub fn create_node(&mut self, kind: NodeKind) -> NodeId

Allocates a new node in the arena and returns its NodeId.

The new node is detached (has no parent). Use append_child, prepend_child, or insert_before to attach it to the tree.

pub fn append_child(&mut self, parent: NodeId, child: NodeId)

Appends a child node to the end of a parent’s child list.

The child becomes the new last_child of parent. If the parent had no children, the child also becomes the first_child.

Panics

Panics (debug-only) if child already has a parent. Call detach first to re-parent an existing node.

pub fn insert_before(&mut self, reference: NodeId, new_child: NodeId)

Inserts new_child immediately before reference in the sibling list.

The new child is given the same parent as reference and is linked as its previous sibling.

Panics

Panics if reference has no parent or if new_child already has a parent (detach it first).

pub fn prepend_child(&mut self, parent: NodeId, child: NodeId)

Prepends a child node as the first child of a parent.

If the parent already has children, the new child is inserted before the current first child. Otherwise, it becomes the only child.

pub fn remove_node(&mut self, id: NodeId)

Removes a node from the tree by detaching it from its parent.

The node and its subtree remain allocated in the arena but become unreachable through tree navigation. This is an alias for detach.

pub fn detach(&mut self, id: NodeId)

Detaches a node from its parent without freeing it from the arena.

Updates sibling and parent links so the node is no longer reachable through tree traversal. The node’s own children are left intact, so the detached subtree remains internally connected. If the node has no parent, this is a no-op.

pub fn clone_node(&mut self, id: NodeId, deep: bool) -> NodeId

Deep-copies a node and all its descendants within this document.

The cloned subtree is detached (has no parent). If deep is false, only the node itself is cloned without its children.

Examples

use xmloxide::Document;

let mut doc = Document::parse_str("<root><child>Hello</child></root>").unwrap();
let root = doc.root_element().unwrap();
let child = doc.first_child(root).unwrap();
let cloned = doc.clone_node(child, true);
doc.append_child(root, cloned);

pub fn set_text_content(&mut self, id: NodeId, content: &str) -> bool

Sets the text content of a text, CDATA, or comment node.

For element nodes, this removes all children and replaces them with a single text node containing the given content.

Returns true if the content was set, false if the node type does not support text content (e.g., the document root).

Examples

use xmloxide::Document;

let mut doc = Document::parse_str("<root>old</root>").unwrap();
let root = doc.root_element().unwrap();
let text_node = doc.first_child(root).unwrap();
assert!(doc.set_text_content(text_node, "new"));
assert_eq!(doc.text_content(root), "new");

pub fn create_element(&mut self, name: &str) -> NodeId

Creates a new element node (detached) and returns its NodeId.

Use append_child, prepend_child, or insert_before to attach it.

pub fn create_text(&mut self, content: &str) -> NodeId

Creates a new text node (detached) and returns its NodeId.

pub fn create_comment(&mut self, content: &str) -> NodeId

Creates a new comment node (detached) and returns its NodeId.

pub fn create_processing_instruction( &mut self, target: &str, data: Option<&str>, ) -> NodeId

Creates a new processing instruction node (detached) and returns its NodeId.

pub fn insert_after(&mut self, reference: NodeId, new_child: NodeId)

Inserts new_child immediately after reference in the sibling list.

If reference is the last child, this is equivalent to appending to the parent.

Panics

Panics if reference has no parent or if new_child already has a parent.

pub fn replace_node(&mut self, old_node: NodeId, new_node: NodeId) -> NodeId

Replaces old_node with new_node in the tree.

The old node is detached and the new node takes its place in the sibling list. Returns the id of the old (now detached) node.

Panics

Panics if old_node has no parent or if new_node already has a parent.

pub fn set_attribute(&mut self, id: NodeId, name: &str, value: &str) -> bool

Sets an attribute on an element node. If the attribute already exists, its value is updated. Returns true on success, false if the node is not an element.

pub fn remove_attribute(&mut self, id: NodeId, name: &str) -> bool

Removes an attribute by name from an element node.

Returns true if the attribute was found and removed, false if the attribute was not present or the node is not an element.

pub fn rename_element(&mut self, id: NodeId, new_name: &str) -> bool

Renames an element node. Returns true on success, false if the node is not an element.

pub fn node_count(&self) -> usize

Returns the total number of nodes in the document.

This includes all node types (elements, text, comments, etc.) but excludes the internal arena placeholder. Detached nodes that have not been garbage-collected are still counted.

Trait Implementations

impl Debug for Document

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Document

fn default() -> Self

Returns the “default value” for a type.