Struct DocumentImpl 

pub struct DocumentImpl<S: DocumentState = Queryable> { /* private fields */ }

An HTML document containing a tree of nodes.

The document owns all nodes via an arena allocator, ensuring cache-friendly contiguous storage. Navigation is performed using NodeId handles.

Architecture

Nodes are stored in a single contiguous Arena<Node>. Parent-child relationships use first_child/last_child links (O(1) append), and siblings are doubly linked via prev_sibling/next_sibling.

Navigation

The document provides both direct navigation methods and lazy iterators:

• parent, first_child, last_child - direct links
• children - iterate over direct children
• ancestors - iterate from parent to root
• descendants - depth-first subtree traversal

Typestate

Internally, the document uses typestate pattern to enforce lifecycle guarantees at compile time. The type parameter S tracks whether the document is being built, is queryable, or is sealed.

Implementations

impl DocumentImpl<Building>

pub fn new() -> Self

Creates a new empty document in building state.

The default capacity is 256 nodes, which is sufficient for typical HTML pages and reduces reallocations during parsing.

pub fn with_capacity(capacity: usize) -> Self

Creates a new empty document with the specified capacity.

Use this when you know the approximate number of nodes to avoid reallocations.

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

Sets the root node ID.

pub fn create_element( &mut self, name: impl Into<String>, attributes: HashMap<String, String>, ) -> NodeId

Creates a new element node and returns its ID.

pub fn create_text(&mut self, content: impl Into<String>) -> NodeId

Creates a new text node and returns its ID.

pub fn create_comment(&mut self, content: impl Into<String>) -> NodeId

Creates a new comment node and returns its ID.

pub fn append_child(&mut self, parent_id: NodeId, child_id: NodeId)

Appends a child node to a parent.

Updates parent, first_child, last_child, and sibling links.

Panics

Panics in debug builds if parent_id or child_id are invalid.

pub fn build(self) -> DocumentImpl<Queryable>

Transitions the document from Building to Queryable state.

This is a one-way transition. Once built, the document structure cannot be modified.

Examples

use std::collections::HashMap;

use scrape_core::{Building, DocumentImpl};

let mut doc = DocumentImpl::<Building>::new();
let root = doc.create_element("div", HashMap::new());
doc.set_root(root);

// Transition to queryable state
let doc = doc.build();

impl DocumentImpl<Queryable>

pub fn new() -> Self

Creates a new empty document in queryable state.

This is a convenience method for backward compatibility. Internally, it creates a Building document and immediately transitions to Queryable.

pub fn with_capacity(capacity: usize) -> Self

Creates a new empty document with the specified capacity in queryable state.

This is a convenience method for backward compatibility.

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

Sets the root node ID.

Available on Queryable for backward compatibility with tests.

pub fn create_element( &mut self, name: impl Into<String>, attributes: HashMap<String, String>, ) -> NodeId

Creates a new element node and returns its ID.

Available on Queryable for backward compatibility with tests.

pub fn create_text(&mut self, content: impl Into<String>) -> NodeId

Creates a new text node and returns its ID.

Available on Queryable for backward compatibility with tests.

pub fn create_comment(&mut self, content: impl Into<String>) -> NodeId

Creates a new comment node and returns its ID.

Available on Queryable for backward compatibility with tests.

pub fn append_child(&mut self, parent_id: NodeId, child_id: NodeId)

Appends a child node to a parent.

Available on Queryable for backward compatibility with tests.

Updates parent, first_child, last_child, and sibling links.

Panics

Panics in debug builds if parent_id or child_id are invalid.

pub fn seal(self) -> DocumentImpl<Sealed>

Seals the document, preventing any future modifications.

This is a one-way transition for when you need to guarantee the document will never change.

pub fn set_index(&mut self, index: DocumentIndex)

Sets the document index.

Only available in Queryable state since index would be invalidated by structural modifications.

impl<S: DocumentState> DocumentImpl<S>

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

Returns the root node ID, if any.

pub fn get(&self, id: NodeId) -> Option<&Node>

Returns a reference to the node with the given ID.

pub fn len(&self) -> usize

Returns the number of nodes in the document.

pub fn is_empty(&self) -> bool

Returns true if the document has no nodes.

pub fn nodes(&self) -> impl Iterator<Item = (NodeId, &Node)>

Returns an iterator over all nodes.

impl<S: MutableState> DocumentImpl<S>

pub fn get_mut(&mut self, id: NodeId) -> Option<&mut Node>

Returns a mutable reference to the node with the given ID.

Only available for documents in mutable states (Building).

impl<S: QueryableState> DocumentImpl<S>

pub fn index(&self) -> Option<&DocumentIndex>

Returns the document index, if built.

Only available in queryable states (Queryable, Sealed).

impl<S: DocumentState> DocumentImpl<S>

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

Returns the parent of a node.

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

Returns the first child of a node.

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

Returns the last child of a node.

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

Returns the next sibling of a node.

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

Returns the previous sibling of a node.

pub fn children(&self, id: NodeId) -> ChildrenIter<'_, S>

Returns an iterator over children of a node.

The iterator yields children in order from first to last.

Examples

use std::collections::HashMap;

use scrape_core::Document;

let mut doc = Document::new();
let parent = doc.create_element("div", HashMap::new());
let child1 = doc.create_element("span", HashMap::new());
let child2 = doc.create_element("span", HashMap::new());

doc.append_child(parent, child1);
doc.append_child(parent, child2);

let children: Vec<_> = doc.children(parent).collect();
assert_eq!(children.len(), 2);

pub fn ancestors(&self, id: NodeId) -> AncestorsIter<'_, S>

Returns an iterator over ancestors of a node.

The iterator yields ancestors from parent to root (does not include the node itself).

Examples

use std::collections::HashMap;

use scrape_core::Document;

let mut doc = Document::new();
let grandparent = doc.create_element("html", HashMap::new());
let parent = doc.create_element("body", HashMap::new());
let child = doc.create_element("div", HashMap::new());

doc.append_child(grandparent, parent);
doc.append_child(parent, child);

let ancestors: Vec<_> = doc.ancestors(child).collect();
assert_eq!(ancestors.len(), 2); // parent, grandparent

pub fn descendants(&self, id: NodeId) -> DescendantsIter<'_, S>

Returns an iterator over descendants in depth-first pre-order.

Does not include the starting node itself.

Examples

use std::collections::HashMap;

use scrape_core::Document;

let mut doc = Document::new();
let root = doc.create_element("html", HashMap::new());
let child1 = doc.create_element("head", HashMap::new());
let child2 = doc.create_element("body", HashMap::new());
let grandchild = doc.create_element("div", HashMap::new());

doc.append_child(root, child1);
doc.append_child(root, child2);
doc.append_child(child2, grandchild);

let descendants: Vec<_> = doc.descendants(root).collect();
assert_eq!(descendants.len(), 3); // head, body, div

pub fn next_siblings(&self, id: NodeId) -> NextSiblingsIter<'_, S>

Returns an iterator over siblings following a node.

Does not include the node itself.

Examples

use std::collections::HashMap;

use scrape_core::Document;

let mut doc = Document::new();
let parent = doc.create_element("ul", HashMap::new());
let child1 = doc.create_element("li", HashMap::new());
let child2 = doc.create_element("li", HashMap::new());
let child3 = doc.create_element("li", HashMap::new());

doc.append_child(parent, child1);
doc.append_child(parent, child2);
doc.append_child(parent, child3);

let next: Vec<_> = doc.next_siblings(child1).collect();
assert_eq!(next.len(), 2); // child2, child3

pub fn prev_siblings(&self, id: NodeId) -> PrevSiblingsIter<'_, S>

Returns an iterator over siblings preceding a node.

Does not include the node itself. Iterates in reverse order (from immediate predecessor toward first sibling).

Examples

use std::collections::HashMap;

use scrape_core::Document;

let mut doc = Document::new();
let parent = doc.create_element("ul", HashMap::new());
let child1 = doc.create_element("li", HashMap::new());
let child2 = doc.create_element("li", HashMap::new());
let child3 = doc.create_element("li", HashMap::new());

doc.append_child(parent, child1);
doc.append_child(parent, child2);
doc.append_child(parent, child3);

let prev: Vec<_> = doc.prev_siblings(child3).collect();
assert_eq!(prev.len(), 2); // child2, child1 (reverse order)

pub fn siblings(&self, id: NodeId) -> SiblingsIter<'_, S>

Returns an iterator over all siblings of a node (excluding the node itself).

Iterates in document order from first sibling to last.

Examples

use std::collections::HashMap;

use scrape_core::Document;

let mut doc = Document::new();
let parent = doc.create_element("ul", HashMap::new());
let child1 = doc.create_element("li", HashMap::new());
let child2 = doc.create_element("li", HashMap::new());
let child3 = doc.create_element("li", HashMap::new());

doc.append_child(parent, child1);
doc.append_child(parent, child2);
doc.append_child(parent, child3);

let siblings: Vec<_> = doc.siblings(child2).collect();
assert_eq!(siblings.len(), 2); // child1, child3

Trait Implementations

impl<S: Debug + DocumentState> Debug for DocumentImpl<S>

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

Formats the value using the given formatter.

impl Default for DocumentImpl<Building>

fn default() -> Self

Returns the “default value” for a type.