Struct marked::Document

pub struct Document { /* fields omitted */ }

A DOM-like container for a tree of markup elements and text.

Unlike RcDom, this uses a simple vector of Nodes and indexes for parent/child and sibling ordering. Attributes are stored as separately allocated vectors for each element. For memory efficiency, a single document is limited to 4 billion (2^32 - 1) total nodes.

All Document instances, even logically "empty" ones as freshly constructed, contain a synthetic document node at the fixed DOCUMENT_NODE_ID that serves as a container for N top level nodes, including the root_element if present.

Methods

impl Document

NodeRef convenence accessor methods.

pub fn document_node_ref(&self) -> NodeRef

Return the (single, always present) document node as a NodeRef.

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

Return the root element NodeRef for this Document, or None if there is no such qualified element.

A node with NodeData::Element is a root element, if it is a direct child of the document node, with no other element nor text sibling.

impl Document

Serialize convenience method.

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

Serialize the contents of the document node and descendants in HTML syntax to the given stream.

impl Document

Mutating filter methods.

pub fn filter<F>(&mut self, f: F) where
    F: Fn(NodeRef, &mut NodeData) -> Action, 

Perform a depth-first (children before parent nodes) walk of the entire Document, including synthetic document node, applying the provided function.

See Document::filter_at for additional details.

pub fn filter_breadth<F>(&mut self, f: F) where
    F: Fn(NodeRef, &mut NodeData) -> Action, 

Perform a breadth-first (children after parent nodes) walk of the entire Document, including synthetic document node, applying the provided function.

See Document::filter_at for additional details.

pub fn filter_at<F>(&mut self, id: NodeId, f: F) where
    F: Fn(NodeRef, &mut NodeData) -> Action, 

Perform a depth-first (children before parent nodes) walk from the specified node ID, applying the provided function.

Traversal order

This variant performs a depth-first (children before parent nodes) tree walk, but there is also Document::filter_at_breadth, a breadth-first (parent before children) variant. Filter functions such as detach_banned_elements may perform better breadth-first (but are compatible with both traversal orders). Other functions such as fold_empty_inline and text_normalize will only yield complete results when run depth-first. See individual functions for compatibility with traversal orders.

Filter functions

The f parameter can be a closure or free-function in the form:

fn a_filter_fn(pos: NodeRef<'_>, data: &mut NodeData) -> Action;

Where data provides read-write access to the the NodeData of the current node being visited, and pos gives a read-only view to the remainder of the Document, e.g. parent, children, and siblings of the current node. Note that to avoid aliasing issues, the NodeData is actually moved out of the Document and replaced with a NodeData::Hole value which could be observed via pos. The potentially modified NodeData is moved back to the Document if the function returns Action::Continue. The function may also modify the Document by returning other Action values.

For convenience and efficiency, multiple filter functions can be combined via the chain_filters macro and run in one pass.

Note that to free up all memory associated with filtered Nodes that have been detached, use Document::deep_clone and drop the original Document..

pub fn filter_at_breadth<F>(&mut self, id: NodeId, f: F) where
    F: Fn(NodeRef, &mut NodeData) -> Action, 

Perform a breadth-first (children after parent nodes) walk from the specified node ID, applying the provided function.

See Document::filter_at for additional details.

impl Document

Core implementation.

pub const DOCUMENT_NODE_ID: NodeId

The constant NodeId for the document node of all Documents.

pub fn new() -> Self

Construct a new Document with the single empty document node.

pub fn with_capacity(count: u32) -> Self

Construct a new Document with the single empty document node and specified capacity.

pub fn len(&self) -> usize

Return total number of Nodes.

This includes the document node and all occupied nodes, some of which may not be accessable from the document node. The value returned may be more than the accessable nodes counted via nodes().count(), unless Document::compact or Document::deep_clone is first used.

pub fn is_empty(&self) -> bool

Return true if this document only contains the single empty document node.

Note that when "empty" the Document::len is still one (1).

pub fn root_element(&self) -> Option<NodeId>

Return the root element NodeId for this Document, or None if there is no such qualified element.

A node with NodeData::Element is a root element, if it is a direct child of the document node, with no other element or text sibling.

pub fn detach(&mut self, id: NodeId)

Detach the specified node ID.

Panics if called with the synthetic DOCUMENT_NODE_ID. Detaching the root element results in an empty document with no root element.

Detach just removes references from other nodes. To free up the memory associated with the node and its children, use Document::compact.

pub fn append_child(&mut self, parent: NodeId, node: Node) -> NodeId

Append node as new last child of parent, and return its new ID.

pub fn insert_before_sibling(&mut self, sibling: NodeId, node: Node) -> NodeId

Insert node before the given sibling and return its new ID.

pub fn text(&self, id: NodeId) -> Option<StrTendril>

Return all decendent text content (character data) of the given node ID.

If node is a text node, return that text. If this is an element node or the document node, return the concatentation of all text descendants, in tree order. Return None for all other node types.

pub fn children<'a>(&'a self, id: NodeId) -> impl Iterator<Item = NodeId> + 'a

Return an iterator over this node's direct children.

Will be empty if the node can not or does not have children.

pub fn node_and_following_siblings<'a>(
    &'a self,
    id: NodeId
) -> impl Iterator<Item = NodeId> + 'a

Return an iterator over the specified node and all its following, direct siblings, within the same parent.

pub fn node_and_ancestors<'a>(
    &'a self,
    id: NodeId
) -> impl Iterator<Item = NodeId> + 'a

Return an iterator over the specified node and all its ancestors, terminating at the document node.

pub fn nodes<'a>(&'a self) -> impl Iterator<Item = NodeId> + 'a

Return an iterator over all nodes, starting with the document node, and including all descendants in tree order.

pub fn compact(&mut self)

Compact in place, by removing Nodes that are no longer referenced from the document node.

pub fn deep_clone(&self, id: NodeId) -> Document

Create a new Document from the ordered sub-tree rooted in the node referenced by ID.

pub fn append_deep_clone(&mut self, id: NodeId, odoc: &Document, oid: NodeId)

Clone node oid in odoc and all its descendants, appending to id in self.

pub fn bulk_clone(&self) -> Document

Return a clone of self by bulk clone of all Nodes.

This clone is performed without regard for what nodes are reachable from the document node. The Document::len of the clone will be the same as the original. As compared with deep_clone(DOCUMENT_NODE_ID) this is faster but potentially much less memory efficient.

pub fn fold(&mut self, id: NodeId)

Replace the specified node ID with its children.

Panics if called with the synthetic DOCUMENT_NODE_ID. Folding the root element may result in a Document with no single root element, or which is otherwise invalid based on its doctype, e.g. the HTML or XML specifications.

After repositioning children the specified node is detached, which only removes references. To free up the memory associated with the node, use Document::compact. For a node with no children, fold is equivalent to Document::detach.

Trait Implementations

impl Debug for Document

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

Formats the value using the given formatter.

impl Default for Document

fn default() -> Document

Returns the "default value" for a type.

impl Index<NodeId> for Document

type Output = Node

The returned type after indexing.

fn index(&self, id: NodeId) -> &Node

Performs the indexing (container[index]) operation.

impl IndexMut<NodeId> for Document

fn index_mut(&mut self, id: NodeId) -> &mut Node

Performs the mutable indexing (container[index]) operation.

impl ToString for Document

Implemented via Document::serialize.

fn to_string(&self) -> String

Converts the given value to a String.