Struct XmlReader 

pub struct XmlReader<'a> { /* private fields */ }

A pull-based streaming XML reader.

The reader parses an XML document incrementally, advancing one node at a time. This is memory-efficient for large documents because it does not build a full tree.

Examples

use xmloxide::reader::{XmlReader, XmlNodeType};

let mut reader = XmlReader::new("<doc attr=\"val\">text</doc>");

// Advance to <doc>
assert!(reader.read().unwrap());
assert_eq!(reader.node_type(), XmlNodeType::Element);
assert_eq!(reader.name(), Some("doc"));
assert_eq!(reader.depth(), 0);
assert_eq!(reader.attribute_count(), 1);
assert_eq!(reader.get_attribute("attr"), Some("val"));

// Advance to text content
assert!(reader.read().unwrap());
assert_eq!(reader.node_type(), XmlNodeType::Text);
assert_eq!(reader.value(), Some("text"));

// Advance to </doc>
assert!(reader.read().unwrap());
assert_eq!(reader.node_type(), XmlNodeType::EndElement);

// End of document
assert!(!reader.read().unwrap());

Implementations

impl<'a> XmlReader<'a>

pub fn new(input: &'a str) -> Self

Creates a new XmlReader from a string slice with default options.

Examples

use xmloxide::reader::XmlReader;

let mut reader = XmlReader::new("<root/>");
assert!(reader.read().unwrap());

pub fn with_options(input: &'a str, options: ParseOptions) -> Self

Creates a new XmlReader from a string slice with custom parse options.

Examples

use xmloxide::reader::XmlReader;
use xmloxide::parser::ParseOptions;

let opts = ParseOptions::default().recover(true);
let mut reader = XmlReader::with_options("<root/>", opts);
assert!(reader.read().unwrap());

pub fn read(&mut self) -> Result<bool, ParseError>

Advances the reader to the next node in the document.

Returns Ok(true) if the reader successfully advanced to a node, or Ok(false) if the end of the document has been reached.

Errors

Returns ParseError if the XML is malformed and recovery mode is not enabled.

Examples

use xmloxide::reader::XmlReader;

let mut reader = XmlReader::new("<root/>");
while reader.read().unwrap() {
    // process each node
}

pub fn node_type(&self) -> XmlNodeType

Returns the type of the current node.

Before the first call to read, returns XmlNodeType::None.

pub fn name(&self) -> Option<&str>

Returns the qualified name of the current node.

For elements, this returns prefix:localname if a prefix is present, or just localname otherwise. For processing instructions, this is the target. For DocumentType nodes, this is the root element name. For other node types, returns None.

pub fn local_name(&self) -> Option<&str>

Returns the local name of the current node (without namespace prefix).

For elements and attributes, this is the local part of the qualified name. For processing instructions, this is the target.

pub fn prefix(&self) -> Option<&str>

Returns the namespace prefix of the current node, if any.

For elements and attributes with a prefix (e.g., svg in <svg:rect>), returns the prefix string. For unprefixed elements, processing instructions, text, comments, and other node types, returns None.

pub fn namespace_uri(&self) -> Option<&str>

Returns the namespace URI of the current node, if any.

Namespace URIs are resolved for elements and attributes that are in a namespace (either via a prefix or a default namespace declaration). Returns None for nodes that have no namespace or for node types that do not carry namespace information (text, comments, etc.).

pub fn value(&self) -> Option<&str>

Returns the value of the current node, if applicable.

For text, CDATA, comment, whitespace, and attribute nodes, this is the text content. For processing instructions, this is the data portion. For elements and end elements, returns None.

pub fn has_value(&self) -> bool

Returns whether the current node has a value.

Returns true for node types that carry text content: text, CDATA, comment, whitespace, attribute, and processing instruction nodes. Returns false for elements, end elements, and the document type.

pub fn is_empty_element(&self) -> bool

Returns whether the current element is a self-closing (empty) element.

Returns true for elements like <br/>, false for elements like <div>...</div>. Always returns false for non-element nodes.

pub fn depth(&self) -> u32

Returns the depth of the current node in the document tree.

The root element is at depth 0, its children at depth 1, and so on. Nodes in the prolog (XML declaration, DOCTYPE) are at depth 0.

pub fn attribute_count(&self) -> usize

Returns the number of attributes on the current element.

Returns 0 for non-element nodes.

pub fn get_attribute(&self, name: &str) -> Option<&str>

Returns the value of an attribute by name on the current element.

Searches by the full attribute name (qualified name). Returns None if the attribute is not present or the current node is not an element.

Examples

use xmloxide::reader::{XmlReader, XmlNodeType};

let mut reader = XmlReader::new("<root id=\"42\"/>");
reader.read().unwrap();
assert_eq!(reader.get_attribute("id"), Some("42"));
assert_eq!(reader.get_attribute("missing"), None);

pub fn get_attribute_ns( &self, local_name: &str, namespace_uri: &str, ) -> Option<&str>

Returns the value of an attribute by local name and namespace URI.

Returns None if the attribute is not present, the namespace does not match, or the current node is not an element.

pub fn move_to_first_attribute(&mut self) -> bool

Moves the reader to the first attribute of the current element.

Returns true if the element has attributes and the reader was moved to the first one. Returns false if there are no attributes or the current node is not an element.

Examples

use xmloxide::reader::{XmlReader, XmlNodeType};

let mut reader = XmlReader::new("<root a=\"1\" b=\"2\"/>");
reader.read().unwrap();

assert!(reader.move_to_first_attribute());
assert_eq!(reader.node_type(), XmlNodeType::Attribute);
assert_eq!(reader.name(), Some("a"));
assert_eq!(reader.value(), Some("1"));

pub fn move_to_next_attribute(&mut self) -> bool

Moves the reader to the next attribute of the current element.

Returns true if there is a next attribute. Returns false if there are no more attributes or the reader is not on an attribute.

Examples

use xmloxide::reader::{XmlReader, XmlNodeType};

let mut reader = XmlReader::new("<root a=\"1\" b=\"2\"/>");
reader.read().unwrap();

assert!(reader.move_to_first_attribute());
assert_eq!(reader.name(), Some("a"));

assert!(reader.move_to_next_attribute());
assert_eq!(reader.name(), Some("b"));

assert!(!reader.move_to_next_attribute());

pub fn move_to_element(&mut self) -> bool

Moves the reader back to the element that owns the current attribute.

Returns true if the reader was on an attribute and was moved back to the element. Returns false if the reader was not on an attribute.

Examples

use xmloxide::reader::{XmlReader, XmlNodeType};

let mut reader = XmlReader::new("<root a=\"1\"/>");
reader.read().unwrap();
reader.move_to_first_attribute();
assert_eq!(reader.node_type(), XmlNodeType::Attribute);

assert!(reader.move_to_element());
assert_eq!(reader.node_type(), XmlNodeType::Element);
assert_eq!(reader.name(), Some("root"));

pub fn diagnostics(&self) -> &[ParseDiagnostic]

Returns the diagnostics collected during parsing.

In recovery mode, this includes warnings and errors that were encountered but did not halt parsing.