Struct TextReader 

pub struct TextReader { /* private fields */ }

A safe wrapper over libxml2’s xmlTextReader pull parser.

Owns the underlying reader (and the file handle it opened); dropping the TextReader frees both.

Implementations

impl TextReader

pub fn from_file(path: &str, options: i32) -> Result<Self, ()>

Open path for streaming. options is the libxml2 parser-option bitmask (0 for defaults). Fails if the reader could not be created (e.g. the file does not exist).

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

Advance to the next node in document order (descending into children).

Ok(true) = positioned on a node, Ok(false) = end of input, Err(()) = a parse error occurred.

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

Advance to the next node that is not a descendant of the current node (i.e. skip the current subtree). Use after materializing a subtree to move past it without walking its children. Same Ok(true/false)/Err semantics as read.

pub fn node_type(&self) -> Option<NodeType>

The current node’s type. Returns None for reader events that have no NodeType equivalent — most usefully the end-of-element event, which lets a caller distinguish an opening <x> (Some(ElementNode)) from a closing </x> (None).

pub fn is_element(&self) -> bool

True when positioned on an element start tag.

pub fn event(&self) -> ReaderEvent

The current reader event, losslessly (see ReaderEvent). Unlike node_type, this distinguishes a closing </x> (EndElement) from inter-element whitespace (Whitespace / SignificantWhitespace).

pub fn depth(&self) -> i32

The current node’s depth in the tree (root element = 0).

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

The current node’s local name (no namespace prefix), if any.

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

The current node’s namespace URI, if any.

pub fn expand(&self) -> Option<RoNode>

Fully build the current node’s subtree and borrow it read-only.

Zero-copy. The returned RoNode is owned by the reader and is invalidated by the next read/read_next — do not retain it across an advance. For a subtree you can keep, use expand_to_document. Returns None at end of input or on error.

pub fn expand_to_document(&self) -> Option<Document>

Copy the current node’s subtree into a fresh, independently-owned Document whose root element is the copy.

Namespaces declared on un-copied ancestors (e.g. the default xmlns on the real document root) are reconciled onto the copy via xmlDOMWrapCloneNode, so the result is self-contained — safe to hold, mutate, transform and serialize after the reader has advanced and freed its own copy of the subtree. Returns None at end of input or on error.

pub fn attributes_qname(&mut self) -> Vec<(String, String)>

The current element’s attributes as (qualified-name, value) pairs in document order, including namespace declarations (xmlns, xmlns:pfx), without expanding the subtree.

This is the streaming way to inspect an element before deciding whether to materialize it — expand would build the whole subtree, which for a large container element defeats the point of streaming. Returns an empty vec on non-element nodes.

Values are fully entity/charref-decoded (libxml2 reader semantics); a caller re-serializing them must re-escape.

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

The current node’s text value (text/CDATA content, comment text, or processing-instruction body). None for valueless nodes (e.g. an element start).

pub fn is_empty_element(&self) -> bool

True when positioned on an empty element tag (<x/>), which the reader reports as a start event with no matching end-element event.

pub fn outer_xml(&self) -> Option<String>

Serialize the current node’s subtree exactly as it appears in the input (no XML declaration, no added namespace declarations, attribute order preserved). Position is unchanged; call read_next to move past the subtree. Returns None at end of input or on error.

Deliberately NOT xmlTextReaderReadOuterXml: that API deep-copies the expanded node parentless first, and for content in a default namespace declared on an un-copied ancestor the copy’s namespace fixup (xmlNewReconciledNs) then mints a default: prefix onto every element — <para> serializes as <default:para xmlns:default="…">. Dumping the reader-owned node directly keeps its ancestors (and their namespace declarations) reachable, so elements serialize with their original prefixes and no fabricated declarations — the fragment re-parses correctly inside any wrapper that re-declares the same namespaces.

pub fn read_to_next<F>(&mut self, want: F) -> Result<bool, ()>

where F: Fn(Option<&str>, &str) -> bool,

Advance until positioned on the next element whose (namespace, localname) satisfies want, or the end of input.

This is the streaming analogue of a downward //name XPath step: the only XPath subset that is actually streamable. Returns Ok(true) when positioned on a match (then call expand / expand_to_document, and read_next to skip past it), Ok(false) at end of input.

want receives the namespace URI (None if the element is in no namespace) and the local name.

Trait Implementations

impl Drop for TextReader

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.