Struct EditorTab 

pub struct EditorTab { /* private fields */ }

Lightweight editor-tab state with a document, cursor, and async save tracking.

Prefer this over DocumentSession only when you want the same engine-facing session wrapper plus built-in cursor convenience.

Implementations

impl EditorTab

pub fn new(id: u64) -> Self

Creates a new empty tab with the provided identifier.

Frontends that already own cursor state can usually start with DocumentSession instead.

pub fn id(&self) -> u64

Returns the tab identifier.

pub fn generation(&self) -> u64

Returns the tab generation counter.

The counter is incremented after operations that fully replace the document.

pub fn is_saving(&self) -> bool

Returns true while a background save is in progress.

pub fn is_busy(&self) -> bool

Returns true while any background load/save worker is active.

pub fn is_indexing(&self) -> bool

Returns true while document-local indexing is still running.

pub fn is_loading(&self) -> bool

Returns true while a background load is in progress.

pub fn indexing_state(&self) -> Option<ByteProgress>

Returns typed indexing progress while background indexing is active.

pub fn loading_state(&self) -> Option<FileProgress>

Returns typed background-load progress.

This covers the asynchronous open path itself. Once the document is ready, follow indexing_state() for any continued background line indexing.

pub fn loading_phase(&self) -> Option<LoadPhase>

Returns the current loading phase when a background open is active.

pub fn poll_load_job(&mut self) -> Option<Result<(), DocumentError>>

Polls the background-load state.

pub fn poll_background_job(&mut self) -> Option<Result<(), DocumentError>>

Polls whichever background job is active.

Load jobs are checked first because open/save are mutually exclusive.

pub fn document(&self) -> &Document

Returns immutable access to the tab document.

pub fn document_mut(&mut self) -> &mut Document

Returns mutable access to the tab document.

This is an escape hatch for callers that fully coordinate their own background job lifecycle. The typed edit helpers on EditorTab reject edits while is_busy() is true; mutating the raw Document through this reference during a background open/save marks the in-flight worker result as stale, so the next poll surfaces an error instead of applying an outdated load/save result over the current document. If a close_file() was deferred while that job was active, this raw mutation also cancels the deferred close.

pub fn text(&self) -> String

Returns the full document text as a String.

This materializes the entire current document through Document::text_lossy. This is an advanced convenience helper rather than the recommended UI path. Prefer read_viewport(...) or read_text(...) when a frontend only needs a visible window or a bounded selection.

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

Returns the current document path, if one is set.

pub fn is_dirty(&self) -> bool

Returns true if the document has unsaved changes.

pub fn line_count(&self) -> LineCount

Returns the current document line count with exact/estimated semantics.

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

Returns the exact document line count when it is known.

pub fn display_line_count(&self) -> usize

Returns the current best-effort line count for viewport sizing and scrolling.

pub fn is_line_count_exact(&self) -> bool

Returns true when the current line count is exact.

pub fn file_len(&self) -> usize

Returns the current document length in bytes.

pub fn line_ending(&self) -> LineEnding

Returns the currently detected line ending style.

pub fn encoding(&self) -> DocumentEncoding

Returns the current document encoding contract.

pub fn preserve_save_error(&self) -> Option<DocumentEncodingErrorKind>

Returns the typed reason why preserve-save would currently fail, if any.

pub fn can_preserve_save(&self) -> bool

Returns true when preserve-save is currently allowed for this tab document.

pub fn save_error_for_options( &self, options: DocumentSaveOptions, ) -> Option<DocumentEncodingErrorKind>

Returns the typed reason why the requested save options would currently fail, if any.

pub fn can_save_with_options(&self, options: DocumentSaveOptions) -> bool

Returns true when the requested save options are currently valid.

pub fn save_error_for_encoding( &self, encoding: DocumentEncoding, ) -> Option<DocumentEncodingErrorKind>

Returns the typed reason why an explicit save conversion would currently fail, if any.

pub fn can_save_with_encoding(&self, encoding: DocumentEncoding) -> bool

Returns true when saving through the given explicit encoding is currently valid.

pub fn encoding_origin(&self) -> DocumentEncodingOrigin

Returns how the current encoding contract was chosen.

pub fn decoding_had_errors(&self) -> bool

Returns true when the last open required replacement-character decoding.

pub fn line_len_chars(&self, line0: usize) -> usize

Returns the visible line length in text columns, excluding line endings.

pub fn is_pinned(&self) -> bool

Returns true if the tab is pinned.

pub fn toggle_pinned(&mut self)

Toggles the pinned state.

pub fn cursor(&self) -> CursorPosition

Returns the current cursor position.

pub fn cursor_position(&self) -> TextPosition

Returns the current cursor as a zero-based text position.

pub fn set_cursor_line_col(&mut self, line: usize, column: usize)

Sets the cursor position using 1-based coordinates.

pub fn set_cursor_position(&mut self, position: TextPosition)

Sets the cursor using a zero-based text position.

pub fn update_cursor_char_index(&mut self, char_index: usize)

Recomputes the cursor position from a character index in the full document text.

pub fn clamp_position(&self, position: TextPosition) -> TextPosition

Clamps a typed position into the currently known document bounds.

pub fn position_for_char_index(&self, char_index: usize) -> TextPosition

Returns the typed document position for a full-text character index.

pub fn char_index_for_position(&self, position: TextPosition) -> usize

Returns the full-text character index for a typed document position.

pub fn ordered_positions( &self, first: TextPosition, second: TextPosition, ) -> (TextPosition, TextPosition)

Returns the ordered pair of two clamped positions.

pub fn clamp_selection(&self, selection: TextSelection) -> TextSelection

Clamps a selection into the currently known document bounds.

pub fn text_units_between( &self, start: TextPosition, end: TextPosition, ) -> usize

Returns the number of edit text units between two positions.

pub fn text_range_between( &self, start: TextPosition, end: TextPosition, ) -> TextRange

Builds a typed edit range between two positions.

pub fn text_range_for_selection(&self, selection: TextSelection) -> TextRange

Builds a typed edit range from an anchor/head selection.

pub fn edit_capability_at(&self, position: TextPosition) -> EditCapability

Returns whether the requested position is editable and whether it would require a backend promotion first.

pub fn edit_capability_for_range(&self, range: TextRange) -> EditCapability

Returns editability for a typed edit range.

pub fn edit_capability_for_selection( &self, selection: TextSelection, ) -> EditCapability

Returns editability for an anchor/head selection.

pub fn read_text(&self, range: TextRange) -> TextSlice

Reads a typed text range from the current document.

pub fn read_selection(&self, selection: TextSelection) -> TextSlice

Reads the current selection as a typed text slice.

pub fn fragmentation_stats(&self) -> Option<FragmentationStats>

Returns current piece-table fragmentation metrics.

pub fn fragmentation_stats_with_threshold( &self, small_piece_threshold_bytes: usize, ) -> Option<FragmentationStats>

Returns fragmentation metrics using a caller-provided small-piece threshold.

pub fn compaction_recommendation(&self) -> Option<CompactionRecommendation>

Returns a piece-table compaction recommendation using the default policy.

pub fn compaction_recommendation_with_policy( &self, policy: CompactionPolicy, ) -> Option<CompactionRecommendation>

Returns a piece-table compaction recommendation using a caller policy.

pub fn maintenance_status(&self) -> DocumentMaintenanceStatus

Returns a maintenance-focused snapshot using the default compaction policy.

pub fn maintenance_action(&self) -> MaintenanceAction

Returns the high-level maintenance action suggested by the default policy.

pub fn maintenance_status_with_policy( &self, policy: CompactionPolicy, ) -> DocumentMaintenanceStatus

Returns a maintenance-focused snapshot using a caller-provided compaction policy.

pub fn maintenance_action_with_policy( &self, policy: CompactionPolicy, ) -> MaintenanceAction

Returns the high-level maintenance action suggested by a caller-provided policy.

pub fn find_next(&self, needle: &str, from: TextPosition) -> Option<SearchMatch>

Finds the next literal match starting at from.

pub fn find_next_query( &self, query: &LiteralSearchQuery, from: TextPosition, ) -> Option<SearchMatch>

Finds the next literal match using a reusable compiled query.

pub fn find_prev( &self, needle: &str, before: TextPosition, ) -> Option<SearchMatch>

Finds the previous literal match whose end is at or before before.

pub fn find_prev_query( &self, query: &LiteralSearchQuery, before: TextPosition, ) -> Option<SearchMatch>

Finds the previous literal match using a reusable compiled query.

pub fn find_all(&self, needle: impl Into<String>) -> LiteralSearchIter<'_>

Iterates non-overlapping literal matches in the whole document.

pub fn find_all_query( &self, query: &LiteralSearchQuery, ) -> LiteralSearchIter<'_>

Iterates non-overlapping literal matches in the whole document using a reusable compiled query.

pub fn find_all_from( &self, needle: impl Into<String>, from: TextPosition, ) -> LiteralSearchIter<'_>

Iterates non-overlapping literal matches from from onward.

pub fn find_all_query_from( &self, query: &LiteralSearchQuery, from: TextPosition, ) -> LiteralSearchIter<'_>

Iterates non-overlapping literal matches from from onward using a reusable compiled query.

pub fn find_all_in_range( &self, needle: impl Into<String>, range: TextRange, ) -> LiteralSearchIter<'_>

Iterates non-overlapping literal matches fully contained within range.

pub fn find_all_query_in_range( &self, query: &LiteralSearchQuery, range: TextRange, ) -> LiteralSearchIter<'_>

Iterates non-overlapping literal matches fully contained within range using a reusable compiled query.

pub fn find_all_between( &self, needle: impl Into<String>, start: TextPosition, end: TextPosition, ) -> LiteralSearchIter<'_>

Iterates non-overlapping literal matches between two typed positions.

pub fn find_all_query_between( &self, query: &LiteralSearchQuery, start: TextPosition, end: TextPosition, ) -> LiteralSearchIter<'_>

Iterates non-overlapping literal matches between two typed positions using a reusable compiled query.

pub fn find_next_in_range( &self, needle: &str, range: TextRange, ) -> Option<SearchMatch>

Finds the first literal match fully contained within range.

pub fn find_next_between( &self, needle: &str, start: TextPosition, end: TextPosition, ) -> Option<SearchMatch>

Finds the first literal match fully contained between two typed positions.

pub fn find_prev_in_range( &self, needle: &str, range: TextRange, ) -> Option<SearchMatch>

Finds the last literal match fully contained within range.

pub fn find_prev_between( &self, needle: &str, start: TextPosition, end: TextPosition, ) -> Option<SearchMatch>

Finds the last literal match fully contained between two typed positions.

pub fn find_next_query_in_range( &self, query: &LiteralSearchQuery, range: TextRange, ) -> Option<SearchMatch>

Finds the first query match fully contained within range.

pub fn find_next_query_between( &self, query: &LiteralSearchQuery, start: TextPosition, end: TextPosition, ) -> Option<SearchMatch>

Finds the first query match fully contained between two typed positions.

pub fn find_prev_query_in_range( &self, query: &LiteralSearchQuery, range: TextRange, ) -> Option<SearchMatch>

Finds the last query match fully contained within range.

pub fn find_prev_query_between( &self, query: &LiteralSearchQuery, start: TextPosition, end: TextPosition, ) -> Option<SearchMatch>

Finds the last query match fully contained between two typed positions.

pub fn compact_piece_table(&mut self) -> Result<bool, DocumentError>

Compacts the current piece-table document if one is active.

pub fn compact_piece_table_if_recommended( &mut self, policy: CompactionPolicy, ) -> Result<Option<CompactionRecommendation>, DocumentError>

Compacts the current piece-table document when the policy recommends it.

pub fn run_idle_compaction( &mut self, ) -> Result<IdleCompactionOutcome, DocumentError>

Runs a deferred idle compaction pass with the default policy.

pub fn run_idle_compaction_with_policy( &mut self, policy: CompactionPolicy, ) -> Result<IdleCompactionOutcome, DocumentError>

Runs a deferred idle compaction pass using a caller-provided policy.

Forced recommendations are surfaced as ForcedPending without rewriting the piece table, which lets the caller reserve that heavier maintenance step for an explicit save or operator action.

pub fn try_insert( &mut self, position: TextPosition, text: &str, ) -> Result<TextPosition, DocumentError>

Applies a typed insert and updates the tab cursor to the resulting position.

pub fn try_replace( &mut self, range: TextRange, text: &str, ) -> Result<TextPosition, DocumentError>

Applies a typed replacement and updates the tab cursor to the resulting position.

pub fn try_replace_selection( &mut self, selection: TextSelection, text: &str, ) -> Result<TextPosition, DocumentError>

Replaces the current selection and updates the tab cursor.

pub fn try_backspace( &mut self, position: TextPosition, ) -> Result<EditResult, DocumentError>

Applies a typed backspace and updates the tab cursor to the resulting position.

pub fn try_backspace_selection( &mut self, selection: TextSelection, ) -> Result<EditResult, DocumentError>

Applies a backspace command to an anchor/head selection and updates the tab cursor.

pub fn try_delete_forward( &mut self, position: TextPosition, ) -> Result<EditResult, DocumentError>

Deletes the text unit at the cursor and updates the tab cursor.

pub fn try_delete_forward_selection( &mut self, selection: TextSelection, ) -> Result<EditResult, DocumentError>

Applies a forward-delete command to an anchor/head selection and updates the tab cursor.

pub fn try_delete_selection( &mut self, selection: TextSelection, ) -> Result<EditResult, DocumentError>

Deletes the current selection and updates the tab cursor.

pub fn try_cut_selection( &mut self, selection: TextSelection, ) -> Result<CutResult, DocumentError>

Cuts the current selection and updates the tab cursor.

pub fn open_file(&mut self, path: PathBuf) -> Result<(), DocumentError>

Opens a file in the tab and resets the cursor to the start of the document.

Errors

Returns DocumentError if the file cannot be opened or if a save is already in progress for the current document.

pub fn open_file_with_options( &mut self, path: PathBuf, options: DocumentOpenOptions, ) -> Result<(), DocumentError>

Opens a file in the tab using explicit open options and resets the cursor.

pub fn open_file_with_auto_encoding_detection( &mut self, path: PathBuf, ) -> Result<(), DocumentError>

Opens a file in the tab using the lightweight auto-detect path and resets the cursor.

pub fn open_file_with_auto_encoding_detection_and_fallback( &mut self, path: PathBuf, encoding: DocumentEncoding, ) -> Result<(), DocumentError>

Opens a file in the tab using auto-detect first and an explicit fallback encoding.

pub fn open_file_with_encoding( &mut self, path: PathBuf, encoding: DocumentEncoding, ) -> Result<(), DocumentError>

Opens a file in the tab using an explicit encoding and resets the cursor.

pub fn open_file_async(&mut self, path: PathBuf) -> Result<(), DocumentError>

Starts opening a file on a background worker.

Errors

Returns DocumentError if another background load or save is already in progress for the tab.

pub fn open_file_async_with_options( &mut self, path: PathBuf, options: DocumentOpenOptions, ) -> Result<(), DocumentError>

Starts opening a file on a background worker using explicit open options.

pub fn open_file_async_with_auto_encoding_detection( &mut self, path: PathBuf, ) -> Result<(), DocumentError>

Starts opening a file on a background worker using the lightweight auto-detect path.

pub fn open_file_async_with_auto_encoding_detection_and_fallback( &mut self, path: PathBuf, encoding: DocumentEncoding, ) -> Result<(), DocumentError>

Starts opening a file on a background worker using auto-detect first and an explicit fallback encoding.

pub fn open_file_async_with_encoding( &mut self, path: PathBuf, encoding: DocumentEncoding, ) -> Result<(), DocumentError>

Starts opening a file on a background worker using an explicit encoding.

pub fn close_file(&mut self)

Closes the current document and replaces it with an empty one.

If a background open/save is still running, the close is deferred until that job finishes so the tab does not silently detach from the active worker result. Deferred closes after background saves are only applied when the save succeeds; failed saves leave the dirty document open.

pub fn after_text_edit_frame(&mut self)

Clears a deferred dirty flag scheduled after a clean document open.

pub fn cancel_clear_dirty_after_open(&mut self)

Cancels the deferred dirty-flag clear scheduled after a clean open.

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

Saves the document synchronously to its current path.

Errors

Returns SaveError::NoPath if no path is set and SaveError::Io if the write operation fails.

pub fn save_as(&mut self, path: PathBuf) -> Result<(), DocumentError>

Saves the document synchronously to a new path.

Errors

Returns DocumentError if the write operation fails.

pub fn save_as_with_options( &mut self, path: PathBuf, options: DocumentSaveOptions, ) -> Result<(), DocumentError>

Saves the document synchronously to a new path using explicit save options.

pub fn save_as_with_encoding( &mut self, path: PathBuf, encoding: DocumentEncoding, ) -> Result<(), DocumentError>

Saves the document synchronously to a new path using an explicit target encoding.

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

Sets the document path without saving.

When used while a background open/save is active, the path change is applied immediately to the current document and the in-flight worker result is marked stale so the next poll returns an error instead of applying outdated state. If a close_file() was deferred while that job was active, changing the path also cancels that deferred close.

pub fn save_state(&self) -> Option<FileProgress>

Returns typed background-save progress.

pub fn poll_save_job(&mut self) -> Option<Result<(), DocumentError>>

Polls the background-save state and applies the completed result.

Returns None if no save has been started or if the job is still running.

pub fn save_async(&mut self) -> Result<bool, SaveError>

Starts a background save to the current path.

Returns Ok(false) when the document is unchanged and no save is needed. The write itself runs on a worker thread, but save preparation still snapshots the current document before that worker starts. For large edited buffers, the call itself can therefore take noticeable time.

Errors

Returns SaveError::NoPath if no path is set, SaveError::InProgress if a save is already running, and SaveError::Io if save preparation fails.

pub fn save_as_async(&mut self, path: PathBuf) -> Result<bool, DocumentError>

Starts a background save to a new path.

Returns Ok(false) when the document is unchanged and is already bound to the same path. The write itself runs on a worker thread, but save preparation still snapshots the current document before that worker starts. For large edited buffers, the call itself can therefore take noticeable time.

Errors

Returns DocumentError if save preparation fails.

pub fn save_as_async_with_options( &mut self, path: PathBuf, options: DocumentSaveOptions, ) -> Result<bool, DocumentError>

Starts a background save to a new path using explicit save options.

pub fn save_as_async_with_encoding( &mut self, path: PathBuf, encoding: DocumentEncoding, ) -> Result<bool, DocumentError>

Starts a background save to a new path using an explicit target encoding.

pub fn background_activity(&self) -> BackgroundActivity

Returns the current background activity for the tab.

pub fn background_issue(&self) -> Option<&BackgroundIssue>

Returns the most recent background open/save problem, if one is being retained.

pub fn take_background_issue(&mut self) -> Option<BackgroundIssue>

Takes and clears the most recent retained background open/save problem.

This is useful for frontends that want to acknowledge a background error once it has been surfaced to the user instead of keeping it visible until a later successful operation clears it implicitly.

pub fn close_pending(&self) -> bool

Returns true when close_file() has been requested and is waiting for the active background open/save to finish.

pub fn status(&self) -> EditorTabStatus

Returns a frontend-friendly snapshot of the current tab state.

pub fn read_viewport(&self, request: ViewportRequest) -> Viewport

Reads a visible viewport directly from the current document.

Trait Implementations

impl Debug for EditorTab

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

Formats the value using the given formatter.