Module format_runs

Expand description

Per-block character formatting as sorted, non-overlapping byte spans.

Each block carries a Vec<FormatRun> (formatting) and a Vec<ImageAnchor> (image positions). The block’s plain_text is the authoritative character source for byte offsets used by both. Replaces the pre-Phase-1 model where every formatted run and every inline image was a row in the now-deleted inline_elements entity table; the InlineSegment type in this module is a transient view synthesized from (plain_text, format_runs, block_images) for readers (export, fragments, cursor) that still consume a per-segment shape.

Invariants are documented on FormatRun and enforced by debug_assert_well_formed and by splice_range / shift_after which rebuild the run list while preserving them.

In a release build a debug_assert! is not enforcement. It is compiled out, so a contract violation there produced a malformed run list silently — and autosave wrote that corruption to the writer’s file seconds later. The bulk-edit path therefore uses the checked siblings, which report instead of assert: check_well_formed, try_splice_range and shift_runs_for_replace, all returning FormatRunError.

Structs§

CharacterFormat: Character-level formatting for a contiguous byte span. One per FormatRun; one per ImageAnchor. Fields mirror the fmt_* set on InlineSegment and on FragmentElement so values copy across types verbatim.
FootnoteRefAnchor: A footnote reference embedded at a specific byte position inside a block.
FormatRun: One run of identical character formatting inside a block. Byte offsets are relative to the block’s plain_text (Phase 1) or to the block’s rope range (Phase 2).
ImageAnchor: An image embedded at a specific byte position inside a block. In Phase 1 the byte position is an index into the block’s plain_text; in Phase 2 it points at the U+FFFC sentinel character in the rope.
InlineSegment: A lean view type representing one inline segment (text or image) with its associated formatting. Used by readers (export, fragments, cursor) to consume per-segment data synthesized from (plain_text, format_runs, block_images) via crate::format_runs_query::inline_segments_for_block. Never stored — synthesized on demand.

Enums§

BlockAnchor: One inline object anchored in a block: an image, or a footnote reference.
FormatRunError: A violation of the format-run invariants, reported instead of asserted.
InlineContent: Content type for an inline segment: text, image, footnote reference, or empty.
InlinePiece: One ordered piece of a block’s inline content: a run of text, or an image.
ReplaceFormatPolicy: What the replacement text wears when it overwrites formatted text.

Functions§

apply_character_format_to_segment: Apply a CharacterFormat onto an InlineSegment’s fmt_* fields.
block_anchors: Every anchor in a block, in byte order.
capture_image_formats_in_range: Capture the (byte_offset, format) pairs for every image anchor inside [start..end). Used together with capture_runs_in_range by hand-rolled-inverse undo for format-only edits.
capture_runs_in_range: Capture the slice of runs that intersects [start..end), clipped to those bounds. Used by hand-rolled-inverse undo for format-only edits: callers capture this BEFORE calling splice_range, and on undo splice the captured runs back into the same byte range to restore the prior state without paying the cost of a full RopeStoreSnapshot.
character_format_from_segment: Copy the fmt_* fields of an InlineSegment into a CharacterFormat.
check_well_formed: The same invariants as debug_assert_well_formed, but reported rather than asserted — so a caller that must not corrupt a block can refuse the edit.
coalesce_in_place: Merge adjacent runs that have identical formatting. O(n).
debug_assert_well_formed: Debug-only invariant check. Run from debug_assert! callsites in the use cases that mutate format runs. Cheap: O(n) where n is the run count (typically < 100 per block in real prose).
inline_segments_view: Synthesize a Vec<InlineSegment> view of a block from its plain_text, format_runs, and block_images. Returns segments in document order: a Text segment per format run (with a fallback default-format segment for any uncovered bytes), and an Image segment per anchor at its byte offset.
logical_offset_to_byte: Translate a logical character offset (counting text characters AND image positions interleaved by their byte_offset) into a UTF-8 byte offset within plain_text. Used by writer use cases to map a document-space char position to the byte position where text edits should land in block.plain_text.
merge_runs_and_anchors: Interleave a block’s format runs and image anchors into one ordered stream.
shift_after: Shift the byte offsets of every run whose byte_start >= threshold by delta. Used after a text insert/delete to keep downstream runs in sync with the new block text. Runs strictly before the threshold are unaffected; runs that straddle the threshold are left alone (the caller should have spliced them first).
shift_footnote_refs_for_insert: Apply an “insert” shift to a block’s image anchors. Anchors at or past the offset move forward by inserted_bytes. Apply an “insert” mutation to a block’s footnote references — the rule shift_images_for_insert applies, for the same reason.
shift_images_after: Same as shift_after for image anchors. Anchors AT the threshold are shifted (treated as part of the inserted region’s right side).
shift_images_for_delete: Apply a “delete” mutation to a block’s image anchors. Anchors whose byte_offset falls inside [byte_start..byte_end) are removed; anchors at or past byte_end shift back by the deleted length. Returns the number of anchors removed.
shift_images_for_insert
shift_runs_for_delete: Apply a “delete byte range [byte_start..byte_end)” mutation to a block’s runs. Splices the range with empty replacement (clipping straddling runs) and shifts everything past byte_end back by the deleted length. Adjacent runs that end up equal-format are coalesced.
shift_runs_for_insert: Apply an “insert inserted_bytes of text at byte_offset” mutation to a block’s runs in place. Runs strictly before the offset are unchanged; runs strictly after are shifted by +inserted_bytes; runs that straddle the offset are extended (the inserted text inherits the surrounding run’s format — Qt / ProseMirror convention).
shift_runs_for_replace: Apply a “replace byte range [byte_start..byte_end) with replacement_bytes bytes” mutation to a block’s runs, choosing explicitly what the replacement wears.
splice_range: Replace the runs covering range with replacement, preserving the invariants. Runs that straddle the range boundary are clipped on either side; runs fully contained are removed.
split_footnote_refs_at: Split block image anchors at byte_offset. Anchors at exactly byte_offset go to the right half (rebased to offset 0). Split footnote references at byte_offset, rebasing the right-hand side to zero — the exact rule split_images_at applies, because a reference occupies a block the same way an image does.
split_images_at
split_runs_at: Split a block’s format runs at byte_offset. The returned right-hand vector has its run offsets re-based so they start at byte 0 of the new (right) block. Straddling runs are split with their format cloned to both halves.
synth_element_id: Synthesize a stable per-fragment id from a block id and byte offset within that block. Populates the element_id field in FragmentContent::{Text, Image} (the public layout-engine type), giving callers a stable handle across renders even though the underlying InlineSegments are never stored. Two segments at the same (block_id, byte_start) always produce the same id; a segment that moves to a new byte_start (e.g. due to an insert upstream) gets a new id.
try_splice_range: splice_range, but the contract is checked and reported instead of asserted.