Struct XPathEvaluator 

pub struct XPathEvaluator<'expr, 'ctx> { /* private fields */ }

Builder for evaluating a compiled XPath expression.

Use this to set variables, context nodes, and other evaluation options before running the expression. The builder pattern allows fluent API usage:

let result = expr.evaluator(&ctx)
    .with_variable("x", 10).unwrap()
    .with_variable("y", 32).unwrap()
    .run::<RoXmlNavigator<'static>>().unwrap();

Implementations

impl<'expr, 'ctx> XPathEvaluator<'expr, 'ctx>

pub fn with_variable( self, name: &str, value: impl Into<EvalValue>, ) -> Result<Self, XPathError>

Set an external variable’s value.

The variable must have been declared when compiling the expression (via compile_with_vars()). Variable names should not include the $ prefix.

Errors

Returns XPST0008 if the variable was not declared at compile time.

Example

let expr = XPathExpr::compile_with_vars("$price * $qty", &ctx, &["price", "qty"]).unwrap();

let eval = expr.evaluator(&ctx)
    .with_variable("price", 19.99).unwrap()
    .with_variable("qty", 3).unwrap();

pub fn run<N: DomNavigator>(self) -> Result<XPathValue<N>, XPathError>

Evaluate the expression and return the full result.

This is the most flexible method, returning the raw XPathValue which can be empty, a single item, or a sequence.

Type Parameter

• N: The navigator type (e.g., RoXmlNavigator<'doc>)

Errors

Returns an error if evaluation fails (e.g., type errors, undefined context).

pub fn run_with_node<N: DomNavigator>( self, node: N, ) -> Result<XPathValue<N>, XPathError>

Evaluate the expression with a context node.

Sets the context item to the given node before evaluation. This is necessary for expressions that use . or axis steps like child::*.

Example

let expr = XPathExpr::compile("child::item", &ctx).unwrap();

// Parse some XML and get a navigator
let doc = roxmltree::Document::parse("<root><item/></root>").unwrap();
let mut nav = RoXmlNavigator::new(&doc);
nav.move_to_first_child(); // move to <root>

let result = expr.evaluator(&ctx)
    .run_with_node(nav).unwrap();

pub fn run_bool<N: DomNavigator>(self) -> Result<bool, XPathError>

Evaluate and return the result as a boolean.

Uses the XPath effective boolean value rules:

• Empty sequence → false
• Boolean → its value
• String → false if empty, true otherwise
• Number → false if 0 or NaN, true otherwise
• Node sequence → true if non-empty

Errors

Returns an error if evaluation fails or if effective boolean value cannot be computed (e.g., sequence of multiple atomic values).

pub fn run_string<N: DomNavigator>(self) -> Result<String, XPathError>

Evaluate and return the result as a string.

Atomizes the result and converts to string. For sequences, returns the string value of the first item (or empty string for empty sequence).

Errors

Returns an error if evaluation fails.

pub fn run_number<N: DomNavigator>(self) -> Result<f64, XPathError>

Evaluate and return the result as a number (f64).

Atomizes the result and converts to double. Returns NaN for values that cannot be converted to numbers.

Errors

Returns an error if evaluation fails.

pub fn run_nodes<N: DomNavigator>(self) -> Result<Vec<N>, XPathError>

Evaluate and return the result as a vector of nodes.

Filters the result to include only nodes, discarding atomic values. Useful for path expressions that return node sequences.

Errors

Returns an error if evaluation fails.

pub fn run_with<N, F>(self, setup: F) -> Result<XPathValue<N>, XPathError>

where N: DomNavigator, F: for<'a> FnOnce(&mut TypedEvaluator<'_, '_, 'a, N>),

Evaluate with a setup callback for advanced variable binding.

This method allows binding variables that cannot be represented as EvalValue, such as:

• Node values
• Sequences of items
• Empty sequences

The setup callback receives a mutable reference to the DynamicContext and can use set_variable_by_name() or context.set_variable() directly.

Example

let expr = XPathExpr::compile_with_vars("count($items)", &ctx, &["items"]).unwrap();

// Bind a sequence of integers
let result = expr.evaluator(&ctx)
    .run_with::<RoXmlNavigator<'static>, _>(|eval| {
        // Create a sequence value
        let seq = XPathValue::from_sequence(vec![
            xsd_schema::xpath::XmlItem::Atomic(xsd_schema::types::XmlValue::integer(1.into())),
            xsd_schema::xpath::XmlItem::Atomic(xsd_schema::types::XmlValue::integer(2.into())),
            xsd_schema::xpath::XmlItem::Atomic(xsd_schema::types::XmlValue::integer(3.into())),
        ]);
        eval.set_variable_by_name("items", seq).unwrap();
    })
    .unwrap();

pub fn run_with_node_and_setup<N, F>( self, context_node: Option<N>, setup: F, ) -> Result<XPathValue<N>, XPathError>

where N: DomNavigator, F: for<'a> FnOnce(&mut TypedEvaluator<'_, '_, 'a, N>),

Evaluate with a context node and setup callback for advanced variable binding.

Combines run_with_node and run_with functionality.