Struct TextBlock 

pub struct TextBlock { /* private fields */ }

A lightweight, read-only handle to a single block (paragraph).

Holds a stable entity ID — the handle remains valid across edits that insert or remove other blocks. Each method acquires the document lock independently. For consistent reads across multiple fields, use snapshot().

Implementations

impl TextBlock

pub fn text(&self) -> String

Block’s plain text. O(1).

pub fn length(&self) -> usize

Character count. O(1).

pub fn is_empty(&self) -> bool

length() == 0. O(1).

pub fn is_valid(&self) -> bool

Block entity still exists in the database. O(1).

pub fn id(&self) -> usize

Stable entity ID (stored in the handle). O(1).

pub fn position(&self) -> usize

Character offset of this block’s start in the document. O(log n) via the rope index for rope-clean documents; O(1) read of the stored field for tabled documents.

pub fn block_number(&self) -> usize

Global 0-indexed block number. O(n): requires scanning all blocks sorted by document_position. Prefer id() for identity and position() for ordering.

pub fn next(&self) -> Option<TextBlock>

The next block in document order. O(n). Returns None if this is the last block.

pub fn previous(&self) -> Option<TextBlock>

The previous block in document order. O(n). Returns None if this is the first block.

pub fn frame(&self) -> TextFrame

Parent frame. O(1).

pub fn table_cell(&self) -> Option<TableCellRef>

If inside a table cell, returns table and cell coordinates.

Finds the block’s parent frame, then checks if any table cell references that frame as its cell_frame. If so, identifies the owning table.

pub fn block_format(&self) -> BlockFormat

Block format (alignment, margins, indent, heading level, marker, tabs). O(1).

pub fn char_format_at(&self, offset: usize) -> Option<TextFormat>

Character format at a block-relative character offset. O(k) where k = format runs + image anchors in this block.

Returns the TextFormat of the fragment containing the given offset. Returns None if the offset is out of range or the block has no fragments.

pub fn fragments(&self) -> Vec<FragmentContent>

Shaping-input fragments: base formatting plus any metric-affecting syntax highlights (bold / italic / size / family / spacing). This is what the layout engine shapes. Paint-only highlights (colors, underline decorations) are NOT merged here — they are kept separate in BlockSnapshot::paint_highlights as a post-shape recolor overlay, so the shaping input stays stable across paint-only highlight changes. For the fully-merged visual fragments, use display_fragments.

O(k) where k = format runs + image anchors in this block.

pub fn display_fragments(&self) -> Vec<FragmentContent>

Fragments as they should be displayed: base formatting with all active syntax highlights merged in, including paint-only ones. This is the “what it looks like” view — useful for a non-optimized renderer, for accessibility, or for tests. The optimized layout path instead uses fragments (shaping input) plus the separate BlockSnapshot::paint_highlights overlay. Equivalent to the pre-overlay behaviour of fragments().

pub fn list(&self) -> Option<TextList>

List this block belongs to. O(1).

pub fn list_item_index(&self) -> Option<usize>

0-based position within its list. O(n) where n = total blocks.

pub fn snapshot(&self) -> BlockSnapshot

All layout-relevant data in one lock acquisition. O(k+n).

Trait Implementations

impl Clone for TextBlock

fn clone(&self) -> TextBlock

Returns a duplicate of the value.

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

Performs copy-assignment from source.