[−][src]Struct marked::Document
A DOM-like container for a tree of markup elements and text.
Unlike RcDom
, this uses a simple vector of Node
s 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
[src]
NodeRef
convenence accessor methods.
pub fn document_node_ref(&self) -> NodeRef<'_>
[src]
Return the (single, always present) document node as a NodeRef
.
pub fn root_element_ref(&self) -> Option<NodeRef<'_>>
[src]
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
[src]
Serialize convenience method.
pub fn serialize<W>(&self, writer: &mut W) -> Result<()> where
W: Write,
[src]
W: Write,
Serialize the contents of the document node and descendants in HTML syntax to the given stream.
impl Document
[src]
Mutating filter methods.
pub fn filter<F>(&mut self, f: F) where
F: Fn(NodeRef<'_>, &mut NodeData) -> Action,
[src]
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,
[src]
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,
[src]
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 Node
s 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,
[src]
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
[src]
Core implementation.
pub const DOCUMENT_NODE_ID: NodeId
[src]
The constant NodeId
for the document node of all Document
s.
pub fn new() -> Self
[src]
Construct a new Document
with the single empty document node.
pub fn with_capacity(count: u32) -> Self
[src]
Construct a new Document
with the single empty document node and
specified capacity.
pub fn len(&self) -> u32
[src]
Return total number of Node
s.
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
[src]
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>
[src]
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
[src]
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)
[src]
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)
[src]
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
[src]
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
[src]
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
[src]
Insert node before the given sibling and return its new ID.
pub fn text(&self, id: NodeId) -> Option<StrTendril>
[src]
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> + '_
[src]
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> + '_
[src]
&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> + '_
[src]
&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> + '_
[src]
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> + '_
[src]
Return an iterator over all descendants in tree order, starting with the specified node.
pub fn compact(&mut self)
[src]
Compact in place, by removing Node
s that are no longer referenced
from the document node.
pub fn deep_clone(&self, id: NodeId) -> Document
[src]
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)
[src]
Clone node oid in odoc and all its descendants, appending to id in self.
pub fn bulk_clone(&self) -> Document
[src]
Return a clone of self by bulk clone of all Node
s.
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
[src]
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
[src]
impl Default for Document
[src]
impl Index<NodeId> for Document
[src]
impl IndexMut<NodeId> for Document
[src]
impl ToString for Document
[src]
Implemented via Document::serialize
.
Auto Trait Implementations
impl !RefUnwindSafe for Document
[src]
impl !Send for Document
[src]
impl !Sync for Document
[src]
impl Unpin for Document
[src]
impl UnwindSafe for Document
[src]
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
pub fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,