Struct FilePicker 

pub struct FilePicker {
    pub mode: FFFMode,
    pub base_path: PathBuf,
    pub is_scanning: Arc<AtomicBool>,
    /* private fields */
}

Fields

mode: FFFMode

base_path: PathBuf

is_scanning: Arc<AtomicBool>

Implementations

impl FilePicker

pub fn base_path(&self) -> &Path

pub fn need_enable_mmap_cache(&self) -> bool

pub fn need_enable_content_indexing(&self) -> bool

pub fn need_watch(&self) -> bool

pub fn mode(&self) -> FFFMode

pub fn cache_budget(&self) -> &ContentCacheBudget

pub fn bigram_index(&self) -> Option<&BigramFilter>

pub fn bigram_overlay(&self) -> Option<&RwLock<BigramOverlay>>

pub fn get_file_mut(&mut self, index: usize) -> Option<&mut FileItem>

pub fn set_bigram_index(&mut self, index: BigramFilter, overlay: BigramOverlay)

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

pub fn get_files(&self) -> &[FileItem]

Get all indexed files sorted by path. Note: Files are stored sorted by PATH for efficient insert/remove. For frecency-sorted results, use search() which sorts matched results.

pub fn get_overflow_files(&self) -> &[FileItem]

pub fn get_dirs(&self) -> &[DirItem]

Get the directory table (sorted by path).

pub fn arena_bytes(&self) -> (usize, usize, usize)

Actual heap bytes used: (chunked_path_store, 0, 0). The second element is 0 because leaked overflow stores aren’t tracked.

pub fn extract_watch_dirs(&self) -> Vec<PathBuf>

Extracts all unique ancestor directories from the indexed file list. Uses the pre-built directory table when available (O(d) where d = unique dirs), falling back to the old traversal for overflow files.

pub fn new(options: FilePickerOptions) -> Result<Self, Error>

Create a new FilePicker from options. Always prefer new_with_shared_state for the consumer application, use this only if you know what you are doing. This won’t spawn the backgraound watcher and won’t walk the file tree.

pub fn new_with_shared_state( shared_picker: SharedPicker, shared_frecency: SharedFrecency, options: FilePickerOptions, ) -> Result<(), Error>

Create a picker, place it into the shared handle, and spawn background indexing + file-system watcher. This is the default entry point.

pub fn collect_files(&mut self) -> Result<(), Error>

Synchronous filesystem scan — populates self with indexed files.

Use this when you need direct access to the picker without shared state:

let mut picker = FilePicker::new(options)?;
picker.collect_files()?;
// picker.get_files() is now populated

pub fn spawn_background_watcher( &mut self, shared_picker: &SharedPicker, shared_frecency: &SharedFrecency, ) -> Result<(), Error>

Start the background file-system watcher.

The picker must already be placed into shared_picker (the watcher needs the shared handle to apply live updates). Call after collect_files or after an initial scan.

pub fn fuzzy_search<'q>( &self, query: &'q FFFQuery<'q>, query_tracker: Option<&QueryTracker>, options: FuzzySearchOptions<'q>, ) -> SearchResult<'_>

Perform fuzzy search on files with a pre-parsed query.

The query should be parsed using FFFQuery::parse() before calling this function. If a QueryTracker is provided, the search will automatically look up the last selected file for this query and apply combo-boost scoring.

pub fn fuzzy_search_directories<'q>( &self, query: &'q FFFQuery<'q>, options: FuzzySearchOptions<'q>, ) -> DirSearchResult<'_>

Perform fuzzy search on indexed directories.

Returns directories ranked by fuzzy match quality + frecency.

pub fn fuzzy_search_mixed<'q>( &self, query: &'q FFFQuery<'q>, query_tracker: Option<&QueryTracker>, options: FuzzySearchOptions<'q>, ) -> MixedSearchResult<'_>

Perform a mixed fuzzy search across both files and directories.

Returns a single flat list where files and directories are interleaved by total score in descending order.

If the raw query ends with a path separator (/), only directories are searched — files are skipped entirely. The caller should parse the query with DirSearchConfig so that trailing / is kept as fuzzy text instead of becoming a PathSegment constraint.

pub fn grep( &self, query: &FFFQuery<'_>, options: &GrepSearchOptions, ) -> GrepResult<'_>

Perform a live grep search across indexed files.

If options.abort_signal is set it overrides the picker’s internal cancellation flag, giving the caller full control over when to stop.

pub fn multi_grep( &self, patterns: &[&str], constraints: &[Constraint<'_>], options: &GrepSearchOptions, ) -> GrepResult<'_>

Multi-pattern grep search across indexed files.

pub fn grep_without_overlay( &self, query: &FFFQuery<'_>, options: &GrepSearchOptions, ) -> GrepResult<'_>

Like grep but ignores the bigram overlay.

pub fn get_scan_progress(&self) -> ScanProgress

pub fn update_git_statuses( &mut self, status_cache: GitStatusCache, shared_frecency: &SharedFrecency, ) -> Result<(), Error>

Update git statuses for files, using the provided shared frecency tracker.

pub fn update_single_file_frecency( &mut self, file_path: impl AsRef<Path>, frecency_tracker: &FrecencyTracker, ) -> Result<(), Error>

pub fn get_file_by_path(&self, path: impl AsRef<Path>) -> Option<&FileItem>

pub fn get_mut_file_by_path( &mut self, path: impl AsRef<Path>, ) -> Option<&mut FileItem>

pub fn add_file_sorted(&mut self, file: FileItem) -> Option<&FileItem>

Add a file to the picker’s files in sorted order (used by background watcher)

pub fn on_create_or_modify( &mut self, path: impl AsRef<Path> + Debug, ) -> Option<&FileItem>

pub fn remove_file_by_path(&mut self, path: impl AsRef<Path>) -> bool

Tombstone a file instead of removing it, keeping base indices stable.

pub fn remove_all_files_in_dir(&mut self, dir: impl AsRef<Path>) -> usize

pub fn cancel(&self)

Use this to prevent any substantial background threads from acquiring the locks

pub fn stop_background_monitor(&mut self)

pub fn trigger_rescan( &mut self, shared_frecency: &SharedFrecency, ) -> Result<(), Error>

pub fn is_scan_active(&self) -> bool

Quick way to check if scan is going without acquiring a lock for Self::get_scan_progress

pub fn scan_signal(&self) -> Arc<AtomicBool>

Return a clone of the scanning flag so callers can poll it without holding a lock on the picker.

pub fn watcher_signal(&self) -> Arc<AtomicBool>

Return a clone of the watcher-ready flag so callers can poll it without holding a lock on the picker.

Trait Implementations

impl Debug for FilePicker

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

Formats the value using the given formatter.

impl FFFStringStorage for &FilePicker

fn arena_for(&self, file: &FileItem) -> ArenaPtr

Resolve the arena for a FileItem (handles base vs overflow split).

fn base_arena(&self) -> ArenaPtr

The base arena (scan-time paths).

fn overflow_arena(&self) -> ArenaPtr

The overflow arena (paths added after the last full scan).