Struct Document 

pub struct Document { /* private fields */ }

The main XML document container.

Owns the node arena, root node, and tracks the current parse state/error.

Implementations

impl Document

pub fn new() -> Self

Creates a new, empty XML document containing only a root Document node.

pub fn with_options(options: ParseOptions) -> Self

Creates a new, empty XML document with custom parse options.

pub const fn root(&self) -> NodeId

Returns the root NodeId of the document.

pub fn node_kind(&self, node: NodeId) -> Option<&NodeKind>

Returns the kind of the specified node, if it exists.

pub fn line_num(&self, node: NodeId) -> Option<u32>

Returns the 1-based source line number where this node was parsed.

pub fn error(&self) -> Option<XmlError>

Returns the current error state of the document, if any.

pub fn error_line(&self) -> Option<u32>

Returns the line number of the last error, if available.

pub fn clear(&mut self)

Resets the document to an empty state, invalidating all existing NodeIds.

pub const fn has_bom(&self) -> bool

Returns whether a Byte Order Mark (BOM) was detected during parsing.

pub fn set_bom(&mut self, use_bom: bool)

Sets whether to output a Byte Order Mark (BOM) when serializing.

pub const fn options(&self) -> &ParseOptions

Returns a reference to the document’s parse options.

pub fn options_mut(&mut self) -> &mut ParseOptions

Returns a mutable reference to the document’s parse options.

pub fn parse_str(&mut self, xml: &str) -> Result<()>

Parses an XML document from a string slice in place.

Any existing DOM structure is cleared.

pub fn parse_bytes_mut(&mut self, bytes: &[u8]) -> Result<()>

Parses an XML document from a byte slice in place.

Rejects non-UTF-8 inputs. Any existing DOM structure is cleared.

pub fn load_file_mut(&mut self, path: impl AsRef<Path>) -> Result<()>

Loads and parses an XML file from the given path in place.

Any existing DOM structure is cleared.

pub fn parse(xml: &str) -> Result<Self>

Parses an XML document from a string slice, returning the new Document.

pub fn parse_bytes(bytes: &[u8]) -> Result<Self>

Parses an XML document from a byte slice, returning the new Document.

Rejects non-UTF-8 inputs.

pub fn load_file(path: impl AsRef<Path>) -> Result<Self>

Loads and parses an XML file from the given path, returning the new Document.

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

Creates a new detached Element node in the document’s arena.

pub fn new_text(&mut self, text: &str) -> NodeId

Creates a new detached Text node in the document’s arena.

pub fn new_cdata(&mut self, text: &str) -> NodeId

Creates a new detached CDATA Text node in the document’s arena.

pub fn new_comment(&mut self, text: &str) -> NodeId

Creates a new detached Comment node in the document’s arena.

pub fn new_declaration(&mut self, decl: &str) -> NodeId

Creates a new detached Declaration node in the document’s arena.

pub fn new_unknown(&mut self, text: &str) -> NodeId

Creates a new detached Unknown node in the document’s arena.

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

Returns the parent of the specified node, if it exists.

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

Returns the first child of the specified node, if it exists.

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

Returns the last child of the specified node, if it exists.

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

Returns the previous sibling of the specified node, if it exists.

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

Returns the next sibling of the specified node, if it exists.

pub fn first_child_element( &self, node: NodeId, name: Option<&str>, ) -> Option<NodeId>

Returns the first child Element of the specified node, optionally matching a tag name.

pub fn last_child_element( &self, node: NodeId, name: Option<&str>, ) -> Option<NodeId>

Returns the last child Element of the specified node, optionally matching a tag name.

pub fn next_sibling_element( &self, node: NodeId, name: Option<&str>, ) -> Option<NodeId>

Returns the next sibling Element of the specified node, optionally matching a tag name.

pub fn prev_sibling_element( &self, node: NodeId, name: Option<&str>, ) -> Option<NodeId>

Returns the previous sibling Element of the specified node, optionally matching a tag name.

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

Returns the root Element of the document (the first element child of the root document node).

pub fn insert_end_child( &mut self, parent: NodeId, child: NodeId, ) -> Result<NodeId>

Inserts child as the last child of parent.

pub fn insert_first_child( &mut self, parent: NodeId, child: NodeId, ) -> Result<NodeId>

Inserts child as the first child of parent.

pub fn insert_after_child( &mut self, after: NodeId, child: NodeId, ) -> Result<NodeId>

Inserts child immediately after after.

pub fn delete_child(&mut self, parent: NodeId, child: NodeId) -> Result<()>

Removes child from parent and deallocates it recursively.

pub fn delete_children(&mut self, parent: NodeId) -> Result<()>

Removes and deallocates all children of parent.

pub fn delete_node(&mut self, node: NodeId) -> Result<()>

Unlinks node from its parent and recursively deallocates it.

pub fn shallow_clone(&mut self, node: NodeId) -> Result<NodeId>

Creates a shallow clone of the node (clones type & data only; no children, detached).

pub fn deep_clone(&mut self, node: NodeId) -> Result<NodeId>

Recursively clones a node and all of its descendants.

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

Returns the string value of the attribute on element el if it exists.

pub fn set_attribute( &mut self, el: NodeId, name: &str, value: &str, ) -> Result<()>

Sets the value of an attribute on element el (inserts or updates).

pub fn delete_attribute(&mut self, el: NodeId, name: &str) -> Result<()>

Removes an attribute from element el.

pub fn first_attribute(&self, el: NodeId) -> Option<&Attribute>

Returns a reference to the first Attribute on element el.

pub fn attribute_count(&self, el: NodeId) -> usize

Returns the number of attributes on element el.

pub fn find_attribute(&self, el: NodeId, name: &str) -> Option<&Attribute>

Finds a reference to the Attribute with the specified name.

pub fn iterate_attributes(&self, el: NodeId) -> impl Iterator<Item = &Attribute>

Returns an iterator over all attributes of element el.

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

Returns an iterator over the direct children of parent.

pub fn child_elements( &self, parent: NodeId, name: Option<&str>, ) -> ChildElements<'_>

Returns an iterator over the direct child elements of parent, optionally filtered by tag name.

pub fn siblings(&self, node: NodeId) -> Siblings<'_>

Returns an iterator over the following siblings of node.

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

Returns a depth-first pre-order iterator over all descendants of root.

pub fn attributes(&self, el: NodeId) -> Attributes<'_>

Returns an iterator over the attributes of element el.

pub fn handle(&self, node: NodeId) -> Handle<'_>

Creates an immutable navigation Handle for the given node.

pub fn handle_mut(&mut self, node: NodeId) -> HandleMut<'_>

Creates a mutable navigation HandleMut for the given node.

pub fn node_ref(&self, id: NodeId) -> Option<NodeRef<'_>>

Returns a NodeRef for the given node, if it exists.

pub fn element_ref(&self, id: NodeId) -> Option<ElementRef<'_>>

Returns an ElementRef for the given node, if it exists and is an Element.

pub fn accept(&self, visitor: &mut dyn XmlVisitor) -> bool

Walk the DOM tree starting at the document root, driving the visitor.

pub fn accept_node(&self, node: NodeId, visitor: &mut dyn XmlVisitor) -> bool

Walk the DOM tree starting at the specified node, driving the visitor.

pub fn to_string(&self) -> String

Pretty-prints the entire document to a String.

pub fn to_string_compact(&self) -> String

Compact-prints the entire document to a String.

pub fn save_file(&self, path: impl AsRef<Path>) -> Result<()>

Saves the pretty-printed document to the given file path.

pub fn save_file_compact(&self, path: impl AsRef<Path>) -> Result<()>

Saves the compact-printed document to the given file path.

pub fn save_writer(&self, writer: impl Write) -> Result<()>

Pretty-prints the document to the given std::io::Write sink.

pub fn save_writer_compact(&self, writer: impl Write) -> Result<()>

Compact-prints the document to the given std::io::Write sink.

impl Document

pub fn query_int_attribute(&self, el: NodeId, name: &str) -> Result<i32>

Queries the value of the attribute as an i32.

pub fn query_unsigned_attribute(&self, el: NodeId, name: &str) -> Result<u32>

Queries the value of the attribute as a u32.

pub fn query_int64_attribute(&self, el: NodeId, name: &str) -> Result<i64>

Queries the value of the attribute as an i64.

pub fn query_bool_attribute(&self, el: NodeId, name: &str) -> Result<bool>

Queries the value of the attribute as a bool.

pub fn query_double_attribute(&self, el: NodeId, name: &str) -> Result<f64>

Queries the value of the attribute as an f64.

pub fn query_float_attribute(&self, el: NodeId, name: &str) -> Result<f32>

Queries the value of the attribute as an f32.

pub fn int_attribute(&self, el: NodeId, name: &str, default: i32) -> i32

Returns the value of the attribute as an i32, or default if it does not exist or cannot be parsed.

pub fn bool_attribute(&self, el: NodeId, name: &str, default: bool) -> bool

Returns the value of the attribute as a bool, or default if it does not exist or cannot be parsed.

pub fn double_attribute(&self, el: NodeId, name: &str, default: f64) -> f64

Returns the value of the attribute as an f64, or default if it does not exist or cannot be parsed.

pub fn float_attribute(&self, el: NodeId, name: &str, default: f32) -> f32

Returns the value of the attribute as an f32, or default if it does not exist or cannot be parsed.

pub fn get_text(&self, el: NodeId) -> Option<&str>

Returns the text content of the first child of el that is a Text node, if one exists.

pub fn set_text(&mut self, el: NodeId, text: &str) -> Result<()>

Sets or replaces the text content of the first child Text node of el.

If no child Text node exists, one is created and inserted as the first child.

pub fn query_int_text(&self, el: NodeId) -> Result<i32>

Queries the text content of the first child Text node as an i32.

pub fn query_bool_text(&self, el: NodeId) -> Result<bool>

Queries the text content of the first child Text node as a bool.

pub fn query_double_text(&self, el: NodeId) -> Result<f64>

Queries the text content of the first child Text node as an f64.

pub fn int_text(&self, el: NodeId, default: i32) -> i32

Returns the text content of the first child Text node as an i32, or default if it does not exist or cannot be parsed.

pub fn bool_text(&self, el: NodeId, default: bool) -> bool

Returns the text content of the first child Text node as a bool, or default if it does not exist or cannot be parsed.

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.

impl Display for Document

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

Formats the value using the given formatter.