Struct roxmltree::Node

pub struct Node<'a, 'input: 'a> { /* private fields */ }

A node in a document.

Document Order

The implementation of the Ord traits for Node is based on the concept of document-order. In layman’s terms, document-order is the order in which one would see each element if one opened a document in a text editor or web browser and scrolled down. Document-order convention is followed in XPath, CSS Counters, and DOM selectors API to ensure consistent results from selection. One difference in roxmltree is that there is the notion of more than one document in existence at a time. While Nodes within the same document are in document-order, Nodes in different documents will be grouped together, but not in any particular order.

As an example, if we have a Document a with Nodes [a0, a1, a2] and a Document b with Nodes [b0, b1], these Nodes in order could be either [a0, a1, a2, b0, b1] or [b0, b1, a0, a1, a2] and roxmltree makes no guarantee which it will be.

Document-order is defined here in the W3C XPath Recommendation The use of document-order in DOM Selectors is described here in the W3C Selectors API Level 1

Implementations

impl<'a, 'input: 'a> Node<'a, 'input>

pub fn node_type(&self) -> NodeType

Returns node’s type.

pub fn is_root(&self) -> bool

Checks that node is a root node.

pub fn is_element(&self) -> bool

Checks that node is an element node.

pub fn is_pi(&self) -> bool

Checks that node is a processing instruction node.

pub fn is_comment(&self) -> bool

Checks that node is a comment node.

pub fn is_text(&self) -> bool

Checks that node is a text node.

pub fn document(&self) -> &'a Document<'input>

Returns node’s document.

pub fn tag_name(&self) -> ExpandedName<'a, 'input>

Returns node’s tag name.

Returns an empty name with no namespace if the current node is not an element.

Examples

let doc = roxmltree::Document::parse("<e xmlns='http://www.w3.org'/>").unwrap();

assert_eq!(doc.root_element().tag_name().namespace(), Some("http://www.w3.org"));
assert_eq!(doc.root_element().tag_name().name(), "e");

pub fn has_tag_name<'n, 'm, N>(&self, name: N) -> bool

where N: Into<ExpandedName<'n, 'm>>,

Checks that node has a specified tag name.

Examples

let doc = roxmltree::Document::parse("<e xmlns='http://www.w3.org'/>").unwrap();

assert!(doc.root_element().has_tag_name("e"));
assert!(doc.root_element().has_tag_name(("http://www.w3.org", "e")));

assert!(!doc.root_element().has_tag_name("b"));
assert!(!doc.root_element().has_tag_name(("http://www.w4.org", "e")));

pub fn default_namespace(&self) -> Option<&'a str>

Returns node’s default namespace URI.

Examples

let doc = roxmltree::Document::parse("<e xmlns='http://www.w3.org'/>").unwrap();

assert_eq!(doc.root_element().default_namespace(), Some("http://www.w3.org"));

let doc = roxmltree::Document::parse("<e xmlns:n='http://www.w3.org'/>").unwrap();

assert_eq!(doc.root_element().default_namespace(), None);

pub fn lookup_prefix(&self, uri: &str) -> Option<&'input str>

Returns a prefix for a given namespace URI.

Examples

let doc = roxmltree::Document::parse("<e xmlns:n='http://www.w3.org'/>").unwrap();

assert_eq!(doc.root_element().lookup_prefix("http://www.w3.org"), Some("n"));

let doc = roxmltree::Document::parse("<e xmlns:n=''/>").unwrap();

assert_eq!(doc.root_element().lookup_prefix(""), Some("n"));

pub fn lookup_namespace_uri(&self, prefix: Option<&str>) -> Option<&'a str>

Returns an URI for a given prefix.

Examples

let doc = roxmltree::Document::parse("<e xmlns:n='http://www.w3.org'/>").unwrap();

assert_eq!(doc.root_element().lookup_namespace_uri(Some("n")), Some("http://www.w3.org"));

let doc = roxmltree::Document::parse("<e xmlns='http://www.w3.org'/>").unwrap();

assert_eq!(doc.root_element().lookup_namespace_uri(None), Some("http://www.w3.org"));

pub fn attribute<'n, 'm, N>(&self, name: N) -> Option<&'a str>

where N: Into<ExpandedName<'n, 'm>>,

Returns element’s attribute value.

Examples

let doc = roxmltree::Document::parse("<e a='b'/>").unwrap();

assert_eq!(doc.root_element().attribute("a"), Some("b"));

let doc = roxmltree::Document::parse(
    "<e xmlns:n='http://www.w3.org' a='b' n:a='c'/>"
).unwrap();

assert_eq!(doc.root_element().attribute("a"), Some("b"));
assert_eq!(doc.root_element().attribute(("http://www.w3.org", "a")), Some("c"));

pub fn attribute_node<'n, 'm, N>( &self, name: N, ) -> Option<Attribute<'a, 'input>>

where N: Into<ExpandedName<'n, 'm>>,

Returns element’s attribute object.

The same as attribute(), but returns the Attribute itself instead of a value string.

pub fn has_attribute<'n, 'm, N>(&self, name: N) -> bool

where N: Into<ExpandedName<'n, 'm>>,

Checks that element has a specified attribute.

Examples

let doc = roxmltree::Document::parse(
    "<e xmlns:n='http://www.w3.org' a='b' n:a='c'/>"
).unwrap();

assert!(doc.root_element().has_attribute("a"));
assert!(doc.root_element().has_attribute(("http://www.w3.org", "a")));

assert!(!doc.root_element().has_attribute("b"));
assert!(!doc.root_element().has_attribute(("http://www.w4.org", "a")));

pub fn attributes(&self) -> Attributes<'a, 'input>

Returns element’s attributes.

Examples

let doc = roxmltree::Document::parse(
    "<e xmlns:n='http://www.w3.org' a='b' n:a='c'/>"
).unwrap();

assert_eq!(doc.root_element().attributes().len(), 2);

pub fn namespaces(&self) -> NamespaceIter<'a, 'input>

Returns element’s namespaces.

Examples

let doc = roxmltree::Document::parse(
    "<e xmlns:n='http://www.w3.org'/>"
).unwrap();

assert_eq!(doc.root_element().namespaces().len(), 1);

pub fn text(&self) -> Option<&'a str>

Returns node’s text.

• for an element will return a first text child
• for a comment will return a self text
• for a text node will return a self text

Examples

let doc = roxmltree::Document::parse("\
<p>
    text
</p>
").unwrap();

assert_eq!(doc.root_element().text(),
           Some("\n    text\n"));
assert_eq!(doc.root_element().first_child().unwrap().text(),
           Some("\n    text\n"));

let doc = roxmltree::Document::parse("<!-- comment --><e/>").unwrap();

assert_eq!(doc.root().first_child().unwrap().text(), Some(" comment "));

pub fn text_storage(&self) -> Option<&'a StringStorage<'input>>

Returns node’s text storage.

Useful when you need a more low-level access to an allocated string.

pub fn tail(&self) -> Option<&'a str>

Returns element’s tail text.

Examples

let doc = roxmltree::Document::parse("\
<root>
    text1
    <p/>
    text2
</root>
").unwrap();

let p = doc.descendants().find(|n| n.has_tag_name("p")).unwrap();
assert_eq!(p.tail(), Some("\n    text2\n"));

pub fn tail_storage(&self) -> Option<&'a StringStorage<'input>>

Returns element’s tail text storage.

Useful when you need a more low-level access to an allocated string.

pub fn pi(&self) -> Option<PI<'input>>

Returns node as Processing Instruction.

pub fn parent(&self) -> Option<Self>

Returns the parent of this node.

pub fn parent_element(&self) -> Option<Self>

Returns the parent element of this node.

pub fn prev_sibling(&self) -> Option<Self>

Returns the previous sibling of this node.

pub fn prev_sibling_element(&self) -> Option<Self>

Returns the previous sibling element of this node.

pub fn next_sibling(&self) -> Option<Self>

Returns the next sibling of this node.

pub fn next_sibling_element(&self) -> Option<Self>

Returns the next sibling element of this node.

pub fn first_child(&self) -> Option<Self>

Returns the first child of this node.

pub fn first_element_child(&self) -> Option<Self>

Returns the first element child of this node.

pub fn last_child(&self) -> Option<Self>

Returns the last child of this node.

pub fn last_element_child(&self) -> Option<Self>

Returns the last element child of this node.

pub fn has_siblings(&self) -> bool

Returns true if this node has siblings.

pub fn has_children(&self) -> bool

Returns true if this node has children.

pub fn ancestors(&self) -> AxisIter<'a, 'input>

Returns an iterator over ancestor nodes starting at this node.

pub fn prev_siblings(&self) -> AxisIter<'a, 'input>

Returns an iterator over previous sibling nodes starting at this node.

pub fn next_siblings(&self) -> AxisIter<'a, 'input>

Returns an iterator over next sibling nodes starting at this node.

pub fn first_children(&self) -> AxisIter<'a, 'input>

Returns an iterator over first children nodes starting at this node.

pub fn last_children(&self) -> AxisIter<'a, 'input>

Returns an iterator over last children nodes starting at this node.

pub fn children(&self) -> Children<'a, 'input>

Returns an iterator over children nodes.

pub fn descendants(&self) -> Descendants<'a, 'input>

Returns an iterator over this node and its descendants.

pub fn range(&self) -> Range<usize>

Returns node’s range in bytes in the original document.

pub fn id(&self) -> NodeId

Returns node’s NodeId

Trait Implementations

impl<'a, 'input: 'a> Clone for Node<'a, 'input>

fn clone(&self) -> Node<'a, 'input>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a, 'input: 'a> Debug for Node<'a, 'input>

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

Formats the value using the given formatter.

impl Hash for Node<'_, '_>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Node<'_, '_>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl PartialEq for Node<'_, '_>

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Node<'_, '_>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<'a, 'input: 'a> Copy for Node<'a, 'input>

impl Eq for Node<'_, '_>