Struct DocumentTree 

pub struct DocumentTree { /* private fields */ }

A hierarchical document tree structure.

Uses an arena-based tree representation for efficient traversal and node manipulation.

Implementations

impl DocumentTree

pub fn new(title: &str, content: &str) -> Self

Create a new document tree with a root node.

pub fn from_raw(arena: Arena<TreeNode>, root_id: NodeId) -> Self

Create a document tree from an existing arena and root ID.

This is useful for deserialization and testing.

pub fn root(&self) -> NodeId

Get the root node ID.

pub fn arena(&self) -> &Arena<TreeNode>

Get a reference to the underlying arena.

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

Get a node by its ID.

Returns None if the node doesn’t exist.

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

Get a mutable reference to a node by its ID.

Returns None if the node doesn’t exist.

pub fn add_child( &mut self, parent: NodeId, title: &str, content: &str, ) -> NodeId

Add a child node to the specified parent.

Returns the ID of the newly created child node. The structure is automatically calculated based on siblings.

pub fn add_child_with_pages( &mut self, parent: NodeId, title: &str, content: &str, start_page: usize, end_page: usize, ) -> NodeId

Add a child node with page boundaries.

Returns the ID of the newly created child node.

pub fn is_leaf(&self, id: NodeId) -> bool

Check if a node is a leaf (has no children).

pub fn child_count(&self, id: NodeId) -> usize

Get the number of children of a node.

This is more efficient than children().len() as it doesn’t allocate.

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

Get the children of a node as an iterator.

Use this instead of children() when you only need to iterate, as it avoids allocating a Vec.

pub fn children(&self, id: NodeId) -> Vec<NodeId>

Get the children of a node.

Returns a Vec for cases where you need owned access to the children. Consider using children_iter() if you only need to iterate.

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

Get the parent of a node.

Returns None if the node is the root or doesn’t have a parent.

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

Get the siblings of a node (excluding the node itself).

Returns an empty iterator for the root node.

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

Get the ancestors of a node from parent to root.

Returns an empty iterator for the root node.

pub fn path_from_root(&self, id: NodeId) -> Vec<NodeId>

Get the path from root to a node (inclusive).

Returns the path as a Vec starting from the root.

pub fn depth(&self, id: NodeId) -> usize

Get the depth of a node (root = 0).

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

Get the first child of a node.

Returns None if the node has no children.

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

Get the last child of a node.

Returns None if the node has no children.

pub fn leaves(&self) -> Vec<NodeId>

Get all leaf nodes in the tree.

Uses cached leaves if available, otherwise rebuilds the cache.

pub fn rebuild_leaves_cache(&mut self)

Rebuild the leaves cache.

Call this after deserialization or batch modifications.

pub fn invalidate_leaves_cache(&mut self)

Invalidate the leaves cache.

Called automatically by mutation methods.

pub fn traverse(&self) -> Vec<NodeId>

Get all nodes in the tree (depth-first order).

pub fn node_count(&self) -> usize

Get the number of nodes in the tree.

pub fn set_summary(&mut self, id: NodeId, summary: &str)

Update a node’s summary.

pub fn set_content(&mut self, id: NodeId, content: &str)

Update a node’s content.

pub fn set_structure(&mut self, id: NodeId, structure: &str)

Update a node’s structure index.

pub fn set_page_boundaries(&mut self, id: NodeId, start: usize, end: usize)

Set page boundaries for a node.

pub fn set_line_indices(&mut self, id: NodeId, start: usize, end: usize)

Set line indices for a node.

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

Get page range for a node.

pub fn contains_page(&self, id: NodeId, page: usize) -> bool

Check if a node contains a specific page.

pub fn find_by_structure(&self, structure: &str) -> Option<NodeId>

Find a node by its structure index.

This is a convenience method that builds an index if needed. For repeated queries, build a RetrievalIndex once.

pub fn find_by_page(&self, page: usize) -> Option<NodeId>

Find the most specific node containing a page.

This is a convenience method that builds an index if needed. For repeated queries, build a RetrievalIndex once.

pub fn find_nodes_by_page_range(&self, start: usize, end: usize) -> Vec<NodeId>

Get all nodes whose page range overlaps with the given range.

pub fn set_node_id(&mut self, id: NodeId, node_id: &str)

Set the node ID (identifier string).

pub fn set_physical_index(&mut self, id: NodeId, index: &str)

Set the physical index marker.

pub fn set_token_count(&mut self, id: NodeId, count: usize)

Update token count for a node.

pub fn to_structure_json(&self, doc_name: &str) -> DocumentStructure

Export the tree structure to JSON format (PageIndex compatible).

pub fn build_retrieval_index(&self) -> RetrievalIndex

Build a retrieval index for efficient operations.

This should be called once after the tree is fully constructed. The index provides O(1) access to commonly needed traversal data.

Example

let tree = /* build tree */;
let index = tree.build_retrieval_index();

// Fast access to leaves
for leaf in index.leaves() {
    // process leaf
}

// Fast path lookup
if let Some(path) = index.path_to(node_id) {
    // path[0] = root, path[-1] = node_id
}

// Fast structure lookup
if let Some(node) = index.find_by_structure("2.1.3") {
    // Found section 2.1.3
}

// Fast page lookup
if let Some(node) = index.find_by_page(42) {
    // Found node containing page 42
}

Trait Implementations

impl Clone for DocumentTree

fn clone(&self) -> DocumentTree

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DocumentTree

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

Formats the value using the given formatter.

impl Default for DocumentTree

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for DocumentTree

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for DocumentTree

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.