Skip to main content

Crate file_database

Crate file_database 

Source
Expand description

§Database

Local file database utilities.

This crate gives you a simple way to manage files and folders inside one database directory. The main type is DatabaseManager, and items are addressed with ItemId. DatabaseManager::create_database creates the directory if missing, or opens an existing directory and indexes its current contents.

§How ItemId works

  • ItemId has a name and an index.
  • name is the display/key name (for example "test_file.txt").
  • index is the stable slot for that name bucket in the internal StableVec.
  • ItemId::id("name") always means index 0.
  • ItemId::database_id() is the root ID for the database itself.

This means duplicate names are allowed, and each item is still uniquely addressable by the pair (name, index).

§Example: Build ItemId values

use file_database::ItemId;

let first = ItemId::id("test_file.txt");
let second = ItemId::with_index("test_file.txt", 1);
let root = ItemId::database_id();

assert_eq!(first.get_name(), "test_file.txt");
assert_eq!(first.get_index(), 0);
assert_eq!(second.get_index(), 1);
assert_eq!(root.get_name(), "");
assert_eq!(root.get_index(), 0);

§How to use GenPath

GenPath is used to generate paths from a ruleset. This is primarily used as the root directory for DatabaseManager. Pick the method based on where your app starts:

  • GenPath::from_working_dir(steps) when your process starts in a useful working directory.
  • GenPath::from_exe(steps) when paths should be anchored to the executable location.
  • GenPath::from_closest_match("name") when you want to find the nearest matching folder while walking upward from the executable.

§Example: Build base paths with GenPath

use file_database::{DatabaseError, GenPath};

fn main() -> Result<(), DatabaseError> {
    let from_cwd = GenPath::from_working_dir(0)?;
    let from_exe = GenPath::from_exe(0)?;
    assert!(from_cwd.is_absolute() || from_cwd.is_relative());
    assert!(from_exe.is_absolute() || from_exe.is_relative());
    Ok(())
}

§Example: Find a folder by name with GenPath

use file_database::{DatabaseError, GenPath};

fn main() -> Result<(), DatabaseError> {
    let project_root = GenPath::from_closest_match("src")?;
    assert!(project_root.ends_with("src"));
    Ok(())
}

§Example: Create and overwrite a file

use file_database::{DatabaseError, DatabaseManager, ItemId};

fn main() -> Result<(), DatabaseError> {
    let mut manager = DatabaseManager::create_database(".", "database")?;
    manager.write_new(ItemId::id("example.txt"), ItemId::database_id())?;
    manager.overwrite_existing(ItemId::id("example.txt"), b"hello")?;
    Ok(())
}

§Example: Open an existing database directory

use std::fs::{create_dir_all, File};
use file_database::{DatabaseError, DatabaseManager};

fn main() -> Result<(), DatabaseError> {
    create_dir_all("./db_parent/database/folder")?;
    File::create("./db_parent/database/config.json")?;

    let manager = DatabaseManager::create_database("./db_parent", "database")?;
    let ids = manager.get_ids_by_name("config.json");
    assert_eq!(ids.len(), 1);
    Ok(())
}

§Example: Duplicate names with stable indexes

use file_database::{DatabaseError, DatabaseManager, ItemId};

fn main() -> Result<(), DatabaseError> {
    let mut manager = DatabaseManager::create_database(".", "database")?;

    manager.write_new(ItemId::id("folder_a"), ItemId::database_id())?;
    manager.write_new(ItemId::id("folder_b"), ItemId::database_id())?;
    manager.write_new(ItemId::with_index("test.txt", 1), ItemId::id("folder_a"))?;
    manager.write_new(ItemId::with_index("test.txt", 2), ItemId::id("folder_b"))?;

    let first = ItemId::with_index("test.txt", 1);
    let second = ItemId::with_index("test.txt", 2);

    let _first_path = manager.locate_absolute(first)?;
    let _second_path = manager.locate_absolute(second)?;
    Ok(())
}

§Example: Get all IDs for one shared name

use file_database::{DatabaseError, DatabaseManager, ItemId};

fn main() -> Result<(), DatabaseError> {
    let mut manager = DatabaseManager::create_database(".", "database")?;
    manager.write_new(ItemId::with_index("a.txt", 1), ItemId::database_id())?;
    manager.write_new(ItemId::id("folder"), ItemId::database_id())?;
    manager.write_new(ItemId::with_index("a.txt", 2), ItemId::id("folder"))?;

    let ids = manager.get_ids_by_name("a.txt");
    assert_eq!(ids.len(), 2);
    assert!(ids.iter().any(|id| id.get_index() == 1));
    assert!(ids.iter().any(|id| id.get_index() == 2));
    Ok(())
}

Structs§

DatabaseManager
Main type that manages a database directory and its index.
FileInformation
Metadata returned by get_file_information.
FileSize
File size value paired with a unit.
GenPath
Helper for building paths from the current process location.
ItemId
Identifier used to select a tracked item by name and index.
ScanReport
Summary returned by scan_for_changes.

Enums§

DatabaseError
Errors returned by this library.
ExportMode
Controls whether export copies or moves the source.
ExternalChange
A file or folder change found by scan_for_changes.
FileSizeUnit
Units used by FileSize.
ForceDeletion
Controls whether directory deletion is forced.
ScanPolicy
Controls how scan_for_changes handles newly found files.
ShouldSort
Controls whether list results are sorted.