Struct Node

source

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

Expand description

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§

source §

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

source

pub fn node_type(&self) -> NodeType

Returns node’s type.

source

pub fn is_root(&self) -> bool

Checks that node is a root node.

source

pub fn is_element(&self) -> bool

Checks that node is an element node.

source

pub fn is_pi(&self) -> bool

Checks that node is a processing instruction node.

source

pub fn is_comment(&self) -> bool

Checks that node is a comment node.

source

pub fn is_text(&self) -> bool

Checks that node is a text node.

source

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

Returns node’s document.

source

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");

source

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")));

source

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);

source

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"));

source

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"));

source

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"));

source

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.

source

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")));

source

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);

source

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);

source

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 "));

source

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.

source

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"));

source