Module transform 

Streaming XML transformation with zero-copy output.

This module provides APIs for transforming XML documents by selectively modifying elements that match XPath expressions, while preserving unchanged portions of the document with zero-copy efficiency.

Features

• Zero-copy output: Unchanged portions of the input are written directly without copying or re-serialization
• Selective DOM: Only matched elements are converted to a modifiable DOM
• Streaming: Single-pass processing for compatible XPath expressions
• Fallback: Automatic two-pass processing for complex XPath patterns
• Multiple handlers: Register multiple XPath-callback pairs

Streamable XPath Patterns

The following patterns can be processed in a single streaming pass:

• Absolute paths: /root/items/item
• Descendant search: //item
• Attribute predicates: //item[@id='2']
• Namespaced elements: //ns:item
• Position predicates with upper bound: //item[position() <= 3]

The following patterns require two-pass processing:

• last() function: //item[last()], //item[position()=last()]
• Backward axes: //item/parent::*, //item/ancestor::root
• Complex predicates requiring full tree evaluation

Examples

Transform with Multiple Handlers

use fastxml::transform::StreamTransformer;

let xml = r#"<root><item id="1">A</item><other>B</other></root>"#;

let result = StreamTransformer::new(xml)
    .on("//item", |node| {
        node.set_attribute("type", "item");
    })
    .on("//other", |node| {
        node.set_attribute("type", "other");
    })
    .run()?
    .to_string()?;

assert!(result.contains(r#"type="item""#));
assert!(result.contains(r#"type="other""#));

Collect Data

use fastxml::transform::StreamTransformer;

let xml = r#"<root><item id="1">A</item><item id="2">B</item></root>"#;

let ids: Vec<String> = StreamTransformer::new(xml)
    .collect("//item", |node| node.get_attribute("id").unwrap_or_default())?;

assert_eq!(ids, vec!["1", "2"]);

For Each (Side Effects Only)

use fastxml::transform::StreamTransformer;

let xml = r#"<root><item>A</item><other>B</other></root>"#;

let mut items = Vec::new();
let mut others = Vec::new();

StreamTransformer::new(xml)
    .on("//item", |node| {
        items.push(node.get_content().unwrap_or_default());
    })
    .on("//other", |node| {
        others.push(node.get_content().unwrap_or_default());
    })
    .for_each()?;

assert_eq!(items, vec!["A"]);
assert_eq!(others, vec!["B"]);

Re-exports

pub use context::AncestorInfo;

pub use context::TransformContext;

pub use editable::EditableNode;

pub use editable::EditableNodeBuilder;

pub use editable::EditableNodeRef;

pub use editable::Modification;

pub use editable::NewNode;

pub use error::ErrorLocation;

pub use error::TransformError;

pub use error::TransformResult;

pub use span::ByteSpan;

pub use xpath_analyze::AttributePredicate;

pub use xpath_analyze::NotStreamableReason;

pub use xpath_analyze::PositionPredicate;

pub use xpath_analyze::StreamableStep;

pub use xpath_analyze::StreamableXPath;

pub use xpath_analyze::XPathAnalysis;

pub use crate::xpath::Expr;

pub use crate::xpath::XPathSource;

Modules

context

Context information available during streaming transformation.

editable

Editable node for DOM manipulation during transformation.

error

Error types for the transform module.

fallback

Two-pass fallback processor for non-streamable XPath expressions.

span

Byte span tracking for zero-copy output.

streaming

Single-pass streaming processor for XML transformation.

xpath_analyze

XPath analysis for determining streamability.

Structs

StreamTransformBuilderDeprecated

A consuming builder that captures the transform function.

StreamTransformer

Builder for streaming XML transformations.

TransformOutput

Output from a transformation operation.

Enums

FallbackMode

Controls how non-streamable XPath expressions are handled.

Traits

CollectMulti

Trait for collecting multiple XPath results in a single pass.

Functions

analyze_xpath_str

Analyzes an XPath expression to determine if it can be processed in a single streaming pass.

get_not_streamable_reason

Returns the reason why an XPath is not streamable, if any.

is_streamable

Returns true if the XPath can be processed in streaming mode.

stream_transform

Simple function API for streaming XML transformation.

stream_transform_with_fallback

Streaming transform with fallback enabled for non-streamable XPath.

stream_transform_with_namespaces

Streaming transform with namespace support.