Struct TextBuffer 

pub struct TextBuffer { /* private fields */ }

A text buffer that manages document content using a piece table with integrated line tracking

Implementations

impl TextBuffer

pub fn new(_large_file_threshold: usize) -> Self

Create a new text buffer (with large_file_threshold for backwards compatibility) Note: large_file_threshold is ignored in the new implementation

pub fn version(&self) -> u64

Current buffer version (monotonic, wraps on overflow)

pub fn from_bytes(content: Vec<u8>) -> Self

Create a text buffer from initial content

pub fn from_str(s: &str, _large_file_threshold: usize) -> Self

Create a text buffer from a string

pub fn empty() -> Self

Create an empty text buffer

pub fn load_from_file<P: AsRef<Path>>( path: P, large_file_threshold: usize, ) -> Result<Self>

Load a text buffer from a file

pub fn save(&mut self) -> Result<()>

Save the buffer to its associated file

pub fn save_to_file<P: AsRef<Path>>(&mut self, path: P) -> Result<()>

Save the buffer to a specific file

This uses incremental saving for large files: instead of loading the entire file into memory, it streams unmodified regions directly from the source file and only keeps edited regions in memory.

If the line ending format has been changed (via set_line_ending), all content will be converted to the new format during save.

pub fn finalize_external_save(&mut self, dest_path: PathBuf) -> Result<()>

Finalize buffer state after an external save operation (e.g., via sudo).

This updates the saved snapshot and file size to match the new state on disk.

pub fn total_bytes(&self) -> usize

Get the total number of bytes in the document

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

Get the total number of lines in the document Uses the piece tree’s integrated line tracking Returns None if line count is unknown (e.g., for large files without line indexing)

pub fn mark_saved_snapshot(&mut self)

Snapshot the current tree as the saved baseline

pub fn diff_since_saved(&self) -> PieceTreeDiff

Diff the current piece tree against the last saved snapshot.

This compares actual byte content, not just tree structure. This means that if you delete text and then paste it back, the diff will correctly show no changes (even though the tree structure differs).

Uses a two-phase algorithm for efficiency:

• Phase 1: Fast structure-based diff to find changed byte ranges (O(num_leaves))
• Phase 2: Only compare actual content within changed ranges (O(edit_size))

This is O(edit_size) instead of O(file_size) for small edits in large files.

pub fn offset_to_position(&self, offset: usize) -> Option<Position>

Convert a byte offset to a line/column position

pub fn position_to_offset(&self, position: Position) -> usize

Convert a line/column position to a byte offset

pub fn insert_bytes(&mut self, offset: usize, text: Vec<u8>) -> Cursor

Insert text at the given byte offset

pub fn insert(&mut self, offset: usize, text: &str)

Insert text (from &str) at the given byte offset

pub fn insert_at_position( &mut self, position: Position, text: Vec<u8>, ) -> Cursor

Insert text at a line/column position This now uses the optimized piece_tree.insert_at_position() for a single traversal

pub fn delete_bytes(&mut self, offset: usize, bytes: usize)

Delete text starting at the given byte offset

pub fn delete(&mut self, range: Range<usize>)

Delete text in a range

pub fn delete_range(&mut self, start: Position, end: Position)

Delete text in a line/column range This now uses the optimized piece_tree.delete_position_range() for a single traversal

pub fn replace_content(&mut self, new_content: &str)

Replace the entire buffer content with new content This is an O(n) operation that rebuilds the piece tree in a single pass, avoiding the O(n²) complexity of applying individual edits.

This is used for bulk operations like “replace all” where applying individual edits would be prohibitively slow.

pub fn restore_piece_tree(&mut self, tree: &Arc<PieceTree>)

Restore a previously saved piece tree (for undo of BulkEdit) This is O(1) because PieceTree uses Arc internally

pub fn snapshot_piece_tree(&self) -> Arc<PieceTree>

Get the current piece tree as an Arc (for saving before BulkEdit) This is O(1) - creates an Arc wrapper around a clone of the tree

pub fn apply_bulk_edits(&mut self, edits: &[(usize, usize, &str)]) -> isize

Apply bulk edits efficiently in a single pass Returns the net change in bytes

pub fn get_text_range_mut( &mut self, offset: usize, bytes: usize, ) -> Result<Vec<u8>>

Get text from a byte offset range with lazy loading This will load unloaded chunks on-demand and always returns complete data

Returns an error if loading fails or if data cannot be read for any reason.

NOTE: Currently loads entire buffers on-demand. Future optimization would split large pieces and load only LOAD_CHUNK_SIZE chunks at a time.

pub fn prepare_viewport( &mut self, start_offset: usize, line_count: usize, ) -> Result<()>

Prepare a viewport for rendering

This is called before rendering with &mut access to pre-load all data that will be needed for the viewport. It estimates the number of bytes needed based on the line count and pre-loads them.

Arguments

• start_offset - The byte offset where the viewport starts
• line_count - The number of lines to prepare (estimate)

Returns

Ok(()) if preparation succeeded, Err if loading failed

pub fn to_string(&self) -> Option<String>

Get all text as a String Returns None if any buffers are unloaded (lazy loading)

pub fn len(&self) -> usize

Get the total number of bytes

pub fn is_empty(&self) -> bool

Check if the buffer is empty

pub fn file_path(&self) -> Option<&Path>

Get the file path associated with this buffer

pub fn set_file_path(&mut self, path: PathBuf)

Set the file path for this buffer

pub fn clear_file_path(&mut self)

Clear the file path (make buffer unnamed) Note: This does NOT affect Unloaded chunk file_paths used for lazy loading. Those still point to the original source file for chunk loading.

pub fn extend_streaming(&mut self, source_path: &Path, new_size: usize)

Extend buffer to include more bytes from a streaming source file. Used for stdin streaming where the temp file grows over time. Appends a new Unloaded chunk for the new bytes.

pub fn is_modified(&self) -> bool

Check if the buffer has been modified since last save

pub fn clear_modified(&mut self)

Clear the modified flag (after save)

pub fn set_modified(&mut self, modified: bool)

Set the modified flag explicitly Used by undo/redo to restore the correct modified state

pub fn is_recovery_pending(&self) -> bool

Check if buffer has pending changes for recovery auto-save

pub fn set_recovery_pending(&mut self, pending: bool)

Mark buffer as needing recovery auto-save (call after edits)

pub fn is_large_file(&self) -> bool

Check if this is a large file with lazy loading enabled

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

Get the saved file size (size of the file on disk after last load/save) For large files, this is used during recovery to know the expected original file size. Returns None for new unsaved buffers.

pub fn get_recovery_chunks(&self) -> Vec<(usize, Vec<u8>)>

Get recovery chunks for this buffer (only modified portions)

For large files, this returns only the pieces that come from Added buffers (i.e., the modifications), not the original file content. This allows efficient incremental recovery without reading/writing the entire file.

Returns: Vec of (original_file_offset, data) for each modified chunk The offset is the position in the ORIGINAL file where this chunk should be inserted.

pub fn is_binary(&self) -> bool

Check if this buffer contains binary content

pub fn line_ending(&self) -> LineEnding

Get the line ending format for this buffer

pub fn set_line_ending(&mut self, line_ending: LineEnding)

Set the line ending format for this buffer

This marks the buffer as modified since the line ending format has changed. On save, the buffer content will be converted to the new format.

pub fn set_default_line_ending(&mut self, line_ending: LineEnding)

Set the default line ending format for a new/empty buffer

Unlike set_line_ending, this does NOT mark the buffer as modified. This should be used when initializing a new buffer with a configured default.

pub fn detect_binary(bytes: &[u8]) -> bool

Detect if the given bytes contain binary content.

Binary content is detected by looking for:

• Null bytes (0x00)
• Non-printable control characters (except common ones like tab, newline, CR)

ANSI escape sequences (ESC [ …) are treated as text, not binary.

pub fn detect_line_ending(bytes: &[u8]) -> LineEnding

Detect the line ending format from a sample of bytes

Uses majority voting: counts CRLF, LF-only, and CR-only occurrences and returns the most common format.

pub fn normalize_line_endings(bytes: Vec<u8>) -> Vec<u8>

Normalize line endings in the given bytes to LF only

Converts CRLF (\r\n) and CR (\r) to LF (\n) for internal representation. This makes editing and cursor movement simpler while preserving the original format for saving.

pub fn get_line(&self, line: usize) -> Option<Vec<u8>>

Get text for a specific line

pub fn line_start_offset(&self, line: usize) -> Option<usize>

Get the byte offset where a line starts

pub fn piece_info_at_offset(&self, offset: usize) -> Option<PieceInfo>

Get piece information at a byte offset

pub fn stats(&self) -> TreeStats

Get tree statistics for debugging

pub fn find_next(&self, pattern: &str, start_pos: usize) -> Option<usize>

Find the next occurrence of a pattern, with wrap-around

pub fn find_next_in_range( &self, pattern: &str, start_pos: usize, range: Option<Range<usize>>, ) -> Option<usize>

Find the next occurrence of a pattern within an optional range If range is None, searches the entire buffer with wrap-around (same as find_next) If range is Some, searches only within that range without wrap-around

pub fn find_next_regex(&self, regex: &Regex, start_pos: usize) -> Option<usize>

Find the next occurrence of a regex pattern, with wrap-around

pub fn find_next_regex_in_range( &self, regex: &Regex, start_pos: usize, range: Option<Range<usize>>, ) -> Option<usize>

Find the next occurrence of a regex pattern within an optional range

pub fn replace_range(&mut self, range: Range<usize>, replacement: &str) -> bool

Replace a range with replacement text

pub fn replace_next( &mut self, pattern: &str, replacement: &str, start_pos: usize, range: Option<Range<usize>>, ) -> Option<usize>

Find and replace the next occurrence of a pattern

pub fn replace_all(&mut self, pattern: &str, replacement: &str) -> usize

Replace all occurrences of a pattern with replacement text

pub fn replace_all_regex( &mut self, regex: &Regex, replacement: &str, ) -> Result<usize>

Replace all occurrences of a regex pattern with replacement text

pub fn position_to_line_col(&self, byte_pos: usize) -> (usize, usize)

Convert byte position to (line, column) in bytes

pub fn line_col_to_position(&self, line: usize, character: usize) -> usize

Convert (line, character) to byte position - 0-indexed character is in BYTES, not UTF-16 code units Optimized to use single line_range() call instead of two

pub fn position_to_lsp_position(&self, byte_pos: usize) -> (usize, usize)

Convert byte position to LSP position (line, UTF-16 code units) LSP protocol uses UTF-16 code units for character offsets

pub fn lsp_position_to_byte(&self, line: usize, utf16_offset: usize) -> usize

Convert LSP position (line, UTF-16 code units) to byte position LSP uses UTF-16 code units for character offsets, not bytes Optimized to use single line_range() call instead of two

pub fn prev_char_boundary(&self, pos: usize) -> usize

Find the previous character boundary (UTF-8 aware)

pub fn next_char_boundary(&self, pos: usize) -> usize

Find the next character boundary (UTF-8 aware)

pub fn snap_to_char_boundary(&self, pos: usize) -> usize

Snap position to a valid UTF-8 character boundary If already at a boundary, returns the same position. Otherwise, moves to the previous valid boundary.

pub fn prev_grapheme_boundary(&self, pos: usize) -> usize

Find the previous grapheme cluster boundary (for proper cursor movement with combining characters)

This handles complex scripts like Thai where multiple Unicode code points form a single visual character (grapheme cluster). For example, Thai “ที่” is 3 code points but 1 grapheme cluster.

pub fn next_grapheme_boundary(&self, pos: usize) -> usize

Find the next grapheme cluster boundary (for proper cursor movement with combining characters)

This handles complex scripts like Thai where multiple Unicode code points form a single visual character (grapheme cluster). For example, Thai “ที่” is 3 code points but 1 grapheme cluster.

pub fn prev_word_boundary(&self, pos: usize) -> usize

Find the previous word boundary

pub fn next_word_boundary(&self, pos: usize) -> usize

Find the next word boundary

pub fn line_iterator( &mut self, byte_pos: usize, estimated_line_length: usize, ) -> LineIterator<'_>

Create a line iterator starting at the given byte position

This iterator lazily loads chunks as needed, never scanning the entire file. For large files with unloaded buffers, chunks are loaded on-demand (1MB at a time).

pub fn iter_lines_from( &mut self, byte_pos: usize, max_lines: usize, ) -> Result<TextBufferLineIterator>

Iterate over lines starting from a given byte offset, with line numbers

This is a more efficient alternative to using line_iterator() + offset_to_position() because it calculates line numbers incrementally during iteration by accumulating line_feed_cnt from pieces (which is already tracked in the piece tree).

Returns: Iterator yielding (byte_offset, content, line_number: Option)

• line_number is Some(n) for small files with line metadata
• line_number is None for large files without line metadata

Performance

• O(1) per line for line number calculation (vs O(log n) per line with offset_to_position)
• Uses single source of truth: piece tree’s existing line_feed_cnt metadata

pub fn get_line_number(&self, byte_offset: usize) -> usize

Get the line number for a given byte offset

Returns exact line number if metadata available, otherwise estimates based on bytes.

Behavior by File Size:

• Small files (< 1MB): Returns exact line number from piece tree’s line_starts metadata
• Large files (≥ 1MB): Returns estimated line number using byte_offset / 80

Large files don’t maintain line metadata for performance reasons. The estimation assumes ~80 bytes per line on average, which works reasonably well for most text files.

pub fn populate_line_cache( &mut self, start_byte: usize, _line_count: usize, ) -> usize

Get the starting line number at a byte offset (used for viewport rendering)

Line Cache Architecture (Post-Refactoring):

The concept of a separate “line cache” is now obsolete. After the refactoring, line tracking is integrated directly into the piece tree via:

BufferData::Loaded {
    data: Vec<u8>,
    line_starts: Option<Vec<usize>>  // None = large file mode (no line metadata)
}

Why This Method Still Exists:

The rendering code needs to know what line number to display in the margin at the top of the viewport. This method returns that line number, handling both small and large file modes transparently.

Small vs Large File Modes:

• Small files: line_starts = Some(vec) → returns exact line number from metadata
• Large files: line_starts = None → returns estimated line number (byte_offset / 80)

Legacy Line Cache Methods:

These methods are now no-ops and can be removed in a future cleanup:

• invalidate_line_cache_from() - No-op (piece tree updates automatically)
• handle_line_cache_insertion() - No-op (piece tree updates automatically)
• handle_line_cache_deletion() - No-op (piece tree updates automatically)
• clear_line_cache() - No-op (can’t clear piece tree metadata)

Bug Fix (2025-11):

Previously this method always returned 0, causing line numbers in the margin to always show 1, 2, 3… regardless of scroll position. Now it correctly returns the actual line number at start_byte.

pub fn get_cached_byte_offset_for_line( &self, line_number: usize, ) -> Option<usize>

Get cached byte offset for line (compatibility method)

pub fn invalidate_line_cache_from(&mut self, _byte_offset: usize)

Invalidate line cache from offset (no-op in new implementation)

pub fn handle_line_cache_insertion( &mut self, _byte_offset: usize, _bytes_inserted: usize, )

Handle line cache insertion (no-op in new implementation)

pub fn handle_line_cache_deletion( &mut self, _byte_offset: usize, _bytes_deleted: usize, )

Handle line cache deletion (no-op in new implementation)

pub fn clear_line_cache(&mut self)

Clear line cache (no-op in new implementation)