pub struct ItemTree {
pub items: Vec<TreeItem>,
pub body: Vec<usize>,
pub blocks: Vec<SourceBlock>,
pub containers: Vec<SourceElement>,
pub inline_whitespace: bool,
pub doclang_nodes: bool,
}Expand description
docling’s item tree in creation order (see the module docs).
Fields§
§items: Vec<TreeItem>Every item, indexed by creation order — which is how docling numbers
#/texts/N, #/groups/N, … within each bucket.
body: Vec<usize>The body’s children, as item indices.
blocks: Vec<SourceBlock>The source’s blocks (#903), in document order, when the backend
enumerates them (HTML); each item’s TreeItem::block points into
this. Empty otherwise.
containers: Vec<SourceElement>The source’s containers that carry an id or a class (#910), in
document order; see SourceElement. Empty when blocks is.
inline_whitespace: boolThe runs of this tree’s inline groups carry their own boundary
whitespace — docling-core’s inline whitespace contract (schema 1.11.0,
crate::inline): a backend that keeps each run’s spaces, as
docling’s do since docling#3891, sets it. Unset, the runs are the
trimmed runs the old " " join expected, and the export re-injects
that join into them (Self::separate_legacy_inline_runs) so the
output reads as it did.
doclang_nodes: boolThe DocLang export serializes the flat nodes rather than this tree, which every other tree gets its DocLang from: the tree reproduces a loss of docling’s the nodes avoid (USPTO’s tables, emptied when docling’s table regex misses them), and the DocLang follows the Markdown there.
Implementations§
Source§impl ItemTree
impl ItemTree
Sourcepub fn place_note_calls(
&self,
first_new: usize,
full_text: &str,
offsets: &[usize],
) -> Vec<Option<(usize, usize)>>
pub fn place_note_calls( &self, first_new: usize, full_text: &str, offsets: &[usize], ) -> Vec<Option<(usize, usize)>>
Where each note call of one paragraph lands (#538): full_text is the
paragraph’s text, offsets the calls’ positions in it (chars), and
the paragraph’s items are those created from first_new on. Each text
item is a trimmed slice of the paragraph (a formatting run, a link, or
the whole heading / list item), matched in order; a call inside an
item lands there, one between items ends the earlier (or starts the
first). When no item matches, the call ends the paragraph’s last text
item; with no text item at all it is None.
Source§impl ItemTree
impl ItemTree
Sourcepub fn add(
&mut self,
parent: Option<usize>,
layer: Option<ContentLayer>,
kind: TreeKind,
) -> usize
pub fn add( &mut self, parent: Option<usize>, layer: Option<ContentLayer>, kind: TreeKind, ) -> usize
Append an item under parent (None = body) on layer, registering
it as its parent’s last child — docling’s add_* calls do exactly that.
Sourcepub fn add_with_prov(
&mut self,
parent: Option<usize>,
layer: Option<ContentLayer>,
kind: TreeKind,
prov: TreeProv,
) -> usize
pub fn add_with_prov( &mut self, parent: Option<usize>, layer: Option<ContentLayer>, kind: TreeKind, prov: TreeProv, ) -> usize
add with the item’s provenance — docling’s
add_text(…, prov=prov).
Sourcepub fn source_text(&self, blocks: impl IntoIterator<Item = usize>) -> String
pub fn source_text(&self, blocks: impl IntoIterator<Item = usize>) -> String
The text of the given source blocks (#904), one line each: each
block’s own normalized SourceBlock::text, joined with a single
\n — no serializer decoration, no trailing separator, nothing of
the blocks around them. Indices out of range are skipped.
Sourcepub fn source_text_excluding(
&self,
blocks: impl IntoIterator<Item = usize>,
exclude: impl Fn(&SourceInline) -> bool,
) -> String
pub fn source_text_excluding( &self, blocks: impl IntoIterator<Item = usize>, exclude: impl Fn(&SourceInline) -> bool, ) -> String
source_text without the inline elements
exclude selects in each block (SourceBlock::text_excluding).
Sourcepub fn blocks_under(&self, path: &str) -> Vec<usize>
pub fn blocks_under(&self, path: &str) -> Vec<usize>
The blocks under path (#910), in document order: those whose
SourceBlock::path is path or starts with path/ — the block
itself, or everything inside a container.
Sourcepub fn path_of_id(&self, id: &str) -> Option<&str>
pub fn path_of_id(&self, id: &str) -> Option<&str>
The path of the element with id (#910): a block’s or a container’s,
the first in document order when the source repeats an id.
Sourcepub fn append(&mut self, other: ItemTree)
pub fn append(&mut self, other: ItemTree)
Append every item of other after this tree’s, renumbering its
indices (parents, children, comments, table/picture caption and
rich-cell refs) and adding its body children to this body — so a
backend can build independent fragments in parallel (one per PPTX
slide) and still hand the export one tree in creation order, exactly
as if it had been built sequentially.
Sourcepub fn reparent(&mut self, id: usize, new_parent: Option<usize>)
pub fn reparent(&mut self, id: usize, new_parent: Option<usize>)
Move id under new_parent, dropping it from its current parent’s
children and appending it to the new one’s — docling’s
group_cell_elements re-parenting of a rich cell’s items.
Sourcepub fn renumber_in_traversal_order(&mut self) -> Vec<Option<usize>>
pub fn renumber_in_traversal_order(&mut self) -> Vec<Option<usize>>
Re-number the items in traversal order — a pre-order walk of the body
through every layer, which is how docling’s
DoclingDocument.concatenate (and _normalize_references) re-creates
a document’s items: a group created after the content it was later
wrapped around comes before that content afterwards. Items the walk
does not reach (deleted ones) are dropped. Returns each old id’s new
id.
Sourcepub fn delete(&mut self, id: usize)
pub fn delete(&mut self, id: usize)
Remove id from the tree — docling’s delete_items, which the DOCX
backend uses to drop the empty text item a blank spacer paragraph left
between two items of a resumed list. The item leaves its parent’s
children and is neither numbered nor written; its slot stays so the
indices held elsewhere stay valid.
Sourcepub fn separate_legacy_inline_runs(&mut self)
pub fn separate_legacy_inline_runs(&mut self)
docling-core’s _migrate_legacy_inline_separators (#997) over the
tree: every inline group’s runs get the " " the pre-1.11 join put
between them (crate::inline::separate_legacy_runs) — on a plain
neighbour, never inside a code or formula run, a standalone " " text
run when both neighbours are delimited. The JSON export applies it to
a tree whose backend has not set Self::inline_whitespace, so a
trimmed-run backend still reads left bold right under the faithful
join, as docling-core reads a document saved before the contract.
text changes, orig keeps the run’s own text.
Sourcepub fn wrap_misplaced_list_items(&mut self)
pub fn wrap_misplaced_list_items(&mut self)
docling-core’s DoclingDocument.validate_misplaced_list_items (a
model validator, so it runs whenever docling-core serializes or loads
a document): every list_item whose parent is not a list group is
re-homed into a new one. A pre-order walk of the body (groups
included) collects them; consecutive misplaced items directly on the
body share one group, any other misplaced item gets its own. Working
from the last run back, each run gets a ListGroup (name group)
inserted where its first item stood, the items are deleted and
re-added under the group as fresh items, so they move to the end of
the text numbering (#527: the DOCX backend leaves such items in rich
table cells). A no-op for a well-formed tree.
One deliberate divergence (#586): docling-core deletes each item with
its children and re-adds it from its text alone, so a mixed-format
item — an empty list_item over an inline group of text runs —
comes back empty and its text is gone from the JSON (and from the
Markdown/HTML docling serializes after that validator ran; the JSON
docling saves before exporting still has it). Here the children
follow the item into the group: the structure docling-core requires,
the content the document had.
Sourcepub fn last_text(&self) -> Option<usize>
pub fn last_text(&self) -> Option<usize>
The last live text-bucket item (docling’s doc.texts[-1]).
Sourcepub fn bucket_index(&self, id: usize) -> usize
pub fn bucket_index(&self, id: usize) -> usize
How many items of a bucket precede id — its #/{bucket}/N index.
Sourcepub fn table_count(&self) -> usize
pub fn table_count(&self) -> usize
The number of tables created so far (docling’s len(doc.tables)).