Struct kuchiki::NodeRef

pub struct NodeRef(pub Rc<Node>);

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.

Methods

impl NodeRef

Important traits for Ancestors

impl Iterator for Ancestors type Item = NodeRef;

pub fn inclusive_ancestors(&self) -> Ancestors

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

Important traits for Ancestors

impl Iterator for Ancestors type Item = NodeRef;

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.

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

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

Important traits for Siblings

impl Iterator for Siblings type Item = NodeRef;

pub fn inclusive_following_siblings(&self) -> Siblings

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

Important traits for Siblings

impl Iterator for Siblings type Item = NodeRef;

pub fn following_siblings(&self) -> Siblings

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

Important traits for Siblings

impl Iterator for Siblings type Item = NodeRef;

pub fn children(&self) -> Siblings

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

Important traits for Descendants

impl Iterator for Descendants type Item = NodeRef;

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().

Important traits for Descendants

impl Iterator for Descendants type Item = NodeRef;

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().

Important traits for Traverse

impl Iterator for Traverse type Item = NodeEdge<NodeRef>;

pub fn traverse_inclusive(&self) -> Traverse

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

Important traits for Traverse

impl Iterator for Traverse type Item = NodeEdge<NodeRef>;

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.

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

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

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.

impl NodeRef

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

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

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.

impl NodeRef

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.

impl NodeRef

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.

pub fn insert_before(&self, new_sibling: NodeRef)

Insert a new sibling before this node.

The new sibling is detached from its previous position.

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 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 previous 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 Eq for NodeRef

impl PartialEq<NodeRef> for NodeRef

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

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

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

This method tests for !=.

impl ToString for NodeRef

fn to_string(&self) -> String

Converts the given value to a String.

impl Clone for NodeRef

fn clone(&self) -> NodeRef

Returns a copy 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

type Target = Node

The resulting type after dereferencing.

fn deref(&self) -> &Node

Dereferences the value.

impl Serialize for NodeRef

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.