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::DOCUMENT_NODE_ID that serves as a container for N top level nodes, including the Document::root_element(), if present.

Implementations

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 the 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 the 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. See also the filter module for included functions.

Note that to free up all memory associated with filtered Nodes that have been unlinked (Action::Detach or Action::Fold), use Document::compact, or 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) -> u32

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.

#[must_use = "If the fragment isn't needed, use `unlink()` instead."]pub fn detach(&mut self, id: NodeId) -> Document

Detach the specified node ID and return it and its children moved into a new independent Document fragment.

If the complete Document sub-tree fragment isn't needed, use Document::unlink instead.

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

Detach just removes references and replaces all node data in self with NodeData::Hole. To free up the Vec<Node> slots for these nodes as well, use Document::compact.

pub fn attach_child(&mut self, parent: NodeId, other: Document)

Attach the contents of an other Document to self, by appending its nodes under the given parent node.

The Document is consumed (its contents moved to self). This is an inverse of Document::detach.

pub fn attach_before_sibling(&mut self, sibling: NodeId, other: Document)

Attach the contents of an other Document to self, by inserting its nodes before the given sibling node.

The Document is consumed (its contents moved to self). This is an inverse of Document::detach.

pub fn unlink(&mut self, id: NodeId) -> NodeData

Unlink the specified node ID from the Document, and return the replaced NodeData.

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

Unlink removes references and replaces the single node data with NodeData::Hole, leaving all children in place but un-referenced. Use Document::detach to instead obtain the entire sub-tree. To free up the Vec<Node> slots for the node and any children, use Document::compact.

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

Append node as new last child of given 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 descendant text content (character data) of the given node.

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(&self, id: NodeId) -> impl Iterator<Item = NodeId> + '_

Return an iterator over the given node's direct children.

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

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

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

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

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

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

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

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

Return an iterator over all descendants in tree order, starting with the specified node.

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

Replace the specified node ID with its children, and return the replaced NodeData.

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 unlinked, removing references, then its data is replaced with NodeData::Hole and the original is returned. To free up the remaining Vec<Node> slot for the node, use Document::compact. For a node with no children, fold is equivalent to Document::unlink.

Trait Implementations

impl Debug for Document

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

Formats the value using the given formatter.

impl Default for Document

pub fn default() -> Document

Returns the "default value" for a type.

impl Index<NodeId> for Document

type Output = Node

The returned type after indexing.

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

Performs the indexing (container[index]) operation.

impl IndexMut<NodeId> for Document

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

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

impl ToString for Document

Implemented via Document::serialize.

pub fn to_string(&self) -> String

Converts the given value to a String.