Crate file_database 

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.

How ItemId works

• ItemId has a name and an index.
• name is the shared key (for example "test_file.txt").
• index picks which path you want when that name exists more than once.
• 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 you can still target one exact item by 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::new(".", "database")?;
    manager.write_new(ItemId::id("example.txt"), ItemId::database_id())?;
    manager.overwrite_existing(ItemId::id("example.txt"), b"hello")?;
    Ok(())
}

Example: Duplicate names with indexes

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

fn main() -> Result<(), DatabaseError> {
    let mut manager = DatabaseManager::new(".", "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::id("test.txt"), ItemId::id("folder_a"))?;
    manager.write_new(ItemId::id("test.txt"), ItemId::id("folder_b"))?;

    // First match for "test.txt"
    let first = ItemId::id("test.txt");
    // Second match for "test.txt"
    let second = ItemId::with_index("test.txt", 1);

    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::new(".", "database")?;
    manager.write_new(ItemId::id("a.txt"), ItemId::database_id())?;
    manager.write_new(ItemId::id("folder"), ItemId::database_id())?;
    manager.write_new(ItemId::id("a.txt"), ItemId::id("folder"))?;

    let ids = manager.get_ids_from_shared_id(ItemId::id("a.txt"))?;
    assert_eq!(ids.len(), 2);
    assert_eq!(ids[0].get_index(), 0);
    assert_eq!(ids[1].get_index(), 1);
    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.

Serialize

Controls whether APIs should serialize values.

ShouldSort

Controls whether list results are sorted.