Struct NodeRef 

pub struct NodeRef(/* private fields */);

A strong reference to a node.

A node is destroyed when the last strong reference to it dropped.

Each node holds a strong reference to its first child and next sibling (if any), but only a weak reference to its last child, previous sibling, and parent. This is to avoid strong reference cycles, which would cause memory leaks.

As a result, a single NodeRef is sufficient to keep alive a node and nodes that are after it in tree order (its descendants, its following siblings, and their descendants) but not other nodes in a tree.

To avoid detroying nodes prematurely, programs typically hold a strong reference to the root of a document until they’re done with that document.

Implementations

impl NodeRef

pub fn inclusive_ancestors(&self) -> Ancestors

Return an iterator of references to this node and its ancestors.

pub fn ancestors(&self) -> Ancestors

Return an iterator of references to this node’s ancestors.

pub fn inclusive_preceding_siblings(&self) -> Rev<Siblings>

Return an iterator of references to this node and the siblings before it.

Panics

Panics if the node has a parent but that parent has no first child (internal tree inconsistency).

pub fn preceding_siblings(&self) -> Rev<Siblings>

Return an iterator of references to this node’s siblings before it.

Panics

Panics if the node has a parent but that parent has no first child (internal tree inconsistency).

pub fn inclusive_following_siblings(&self) -> Siblings

Return an iterator of references to this node and the siblings after it.

Panics

Panics if the node has a parent but that parent has no last child (internal tree inconsistency).

pub fn following_siblings(&self) -> Siblings

Return an iterator of references to this node’s siblings after it.

Panics

Panics if the node has a parent but that parent has no last child (internal tree inconsistency).

pub fn children(&self) -> Siblings

Return an iterator of references to this node’s children.

pub fn inclusive_descendants(&self) -> Descendants

Return an iterator of references to this node and its descendants, in tree order.

Parent nodes appear before the descendants.

Note: this is the NodeEdge::Start items from traverse().

pub fn descendants(&self) -> Descendants

Return an iterator of references to this node’s descendants, in tree order.

Parent nodes appear before the descendants.

Note: this is the NodeEdge::Start items from traverse().

pub fn traverse_inclusive(&self) -> Traverse

Return an iterator of the start and end edges of this node and its descendants, in tree order.

pub fn traverse(&self) -> Traverse

Return an iterator of the start and end edges of this node’s descendants, in tree order.

pub fn select( &self, selectors: &str, ) -> Result<Select<Elements<Descendants>>, ()>

Return an iterator of the inclusive descendants element that match the given selector list.

Errors

Returns Err(()) if the selector string fails to parse.

pub fn select_first( &self, selectors: &str, ) -> Result<NodeDataRef<ElementData>, ()>

Return the first inclusive descendants element that match the given selector list.

Errors

Returns Err(()) if the selector string fails to parse or if no element matches.

impl NodeRef

pub fn into_element_ref(self) -> Option<NodeDataRef<ElementData>>

If this node is an element, return a strong reference to element-specific data.

pub fn into_text_ref(self) -> Option<NodeDataRef<RefCell<String>>>

If this node is a text node, return a strong reference to its contents.

pub fn into_comment_ref(self) -> Option<NodeDataRef<RefCell<String>>>

If this node is a comment, return a strong reference to its contents.

pub fn into_doctype_ref(self) -> Option<NodeDataRef<Doctype>>

If this node is a doctype, return a strong reference to doctype-specific data.

pub fn into_document_ref(self) -> Option<NodeDataRef<DocumentData>>

If this node is a document, return a strong reference to document-specific data.

pub fn into_processing_instruction_ref( self, ) -> Option<NodeDataRef<RefCell<(String, String)>>>

If this node is a processing instruction, return a strong reference to its contents.

pub fn into_document_fragment_ref(self) -> Option<NodeDataRef<()>>

If this node is a document fragment, return a strong reference to it.

impl NodeRef

Methods for HTML serialization.

Provides convenient methods for serializing DOM nodes to HTML strings, byte streams, and files.

pub fn serialize<W: Write>(&self, writer: &mut W) -> Result<()>

Serialize this node and its descendants in HTML syntax to the given stream.

Errors

Returns an io::Error if writing to the stream fails.

pub fn serialize_to_file<P: AsRef<Path>>(&self, path: P) -> Result<()>

Serialize this node and its descendants in HTML syntax to a new file at the given path.

Errors

Returns an io::Error if the file cannot be created or if writing fails.

impl NodeRef

Factory methods and tree manipulation for NodeRef.

Provides constructors for all node types (elements, text, comments, etc.) and methods for reading and modifying the tree structure.

pub fn new(data: NodeData) -> NodeRef

Create a new node.

pub fn new_element<I>(name: QualName, attributes: I) -> NodeRef

where I: IntoIterator<Item = (ExpandedName, Attribute)>,

Create a new element node.

pub fn new_text<T: Into<String>>(value: T) -> NodeRef

Create a new text node.

pub fn new_comment<T: Into<String>>(value: T) -> NodeRef

Create a new comment node.

pub fn new_processing_instruction<T1, T2>(target: T1, data: T2) -> NodeRef

where T1: Into<String>, T2: Into<String>,

Create a new processing instruction node.

pub fn new_doctype<T1, T2, T3>( name: T1, public_id: T2, system_id: T3, ) -> NodeRef

where T1: Into<String>, T2: Into<String>, T3: Into<String>,

Create a new doctype node.

pub fn new_document() -> NodeRef

Create a new document node.

pub fn text_contents(&self) -> String

Return the concatenation of all text nodes in this subtree.

pub fn append(&self, new_child: NodeRef)

Append a new child to this node, after existing children.

The new child is detached from its previous position.

pub fn prepend(&self, new_child: NodeRef)

Prepend a new child to this node, before existing children.

The new child is detached from its previous position.

pub fn insert_after(&self, new_sibling: NodeRef)

Insert a new sibling after this node.

The new sibling is detached from its previous position.

Panics

Panics in debug mode if internal tree invariants are violated.

pub fn insert_before(&self, new_sibling: NodeRef)

Insert a new sibling before this node.

The new sibling is detached from its previous position.

Panics

Panics in debug mode if internal tree invariants are violated.

Methods from Deref<Target = Node>

pub fn data(&self) -> &NodeData

Return a reference to this node’s node-type-specific data.

pub fn as_element(&self) -> Option<&ElementData>

If this node is an element, return a reference to element-specific data.

pub fn as_text(&self) -> Option<&RefCell<String>>

If this node is a text node, return a reference to its contents.

pub fn as_comment(&self) -> Option<&RefCell<String>>

If this node is a comment, return a reference to its contents.

pub fn as_doctype(&self) -> Option<&Doctype>

If this node is a document, return a reference to doctype-specific data.

pub fn as_document(&self) -> Option<&DocumentData>

If this node is a document, return a reference to document-specific data.

pub fn as_processing_instruction(&self) -> Option<&RefCell<(String, String)>>

If this node is a processing instruction, return a reference to its contents.

pub fn as_document_fragment(&self) -> Option<&()>

If this node is a document fragment, return a reference to the unit value.

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

Return a reference to the parent node, unless this node is the root of the tree.

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

Return a reference to the first child of this node, unless it has no child.

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

Return a reference to the last child of this node, unless it has no child.

pub fn previous_sibling(&self) -> Option<NodeRef>

Return a reference to the previous sibling of this node, unless it is a first child.

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

Return a reference to the next sibling of this node, unless it is a last child.

pub fn detach(&self)

Detach a node from its parent and siblings. Children are not affected.

To remove a node and its descendants, detach it and drop any strong reference to it.

Trait Implementations

impl Clone for NodeRef

fn clone(&self) -> NodeRef

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for NodeRef

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

Formats the value using the given formatter.

impl Deref for NodeRef

Implements Deref to allow transparent access to the underlying Node.

This allows NodeRef to be used like a reference to Node, automatically dereferencing to access Node’s methods and fields.

type Target = Node

The resulting type after dereferencing.

fn deref(&self) -> &Node

Dereferences the value.

impl Display for NodeRef

Implements Display for NodeRef.

Formats the node and its descendants as an HTML string. Uses the Serialize implementation to generate the HTML output.

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

Formats the value using the given formatter.

impl PartialEq for NodeRef

Implements PartialEq for NodeRef using pointer equality.

Compares the memory addresses of the underlying Node instances. Returns true only if both NodeRefs point to the exact same Node.

fn eq(&self, other: &NodeRef) -> 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 Serialize for NodeRef

Implements Serialize for NodeRef.

Enables HTML serialization of DOM nodes using html5ever’s serialization infrastructure. Handles all node types including elements, text, comments, doctypes, processing instructions, documents, and document fragments.

fn serialize<S: Serializer>( &self, serializer: &mut S, traversal_scope: TraversalScope, ) -> Result<()>

Take the serializer and call its methods to serialize this type. The type will dictate which methods are called and with what parameters.

impl Eq for NodeRef

Implements Eq for NodeRef.

Two NodeRefs are equal if they point to the same Node instance (pointer equality), not if their data is equivalent.