Struct Dir 

pub struct Dir { /* private fields */ }

A directory tree an app may use, and nothing outside it.

Cloning is cheap and the clone names the same tree.

Implementations

impl Dir

pub fn open(location: Location) -> Result<Dir, FsError>

The tree at location. Nothing is created until something is written.

Errors

FsError::Unsupported for a location this target has no backend for, and FsError::InvalidPath for an OPFS profile that is not one path component.

pub fn memory() -> Dir

An empty tree in memory that only this Dir and its clones see.

pub async fn read(&self, path: &VPath) -> Result<Vec<u8>, FsError>

The whole file.

Errors

FsError::NotFound, FsError::IsADirectory, or the backend’s failure.

pub async fn write_atomic( &self, path: &VPath, bytes: &[u8], ) -> Result<(), FsError>

Replaces the file’s contents with bytes so that a crash leaves either the old contents or the new ones, creating missing parents.

Errors

FsError::IsADirectory, FsError::NotADirectory for a file in the way of a parent, FsError::InvalidPath for the root, or the backend’s failure. Natively a failure of the final directory fsync happens after the new contents are visible.

pub async fn save_document( &self, path: &VPath, bytes: &[u8], ) -> Result<(), FsError>

Saves a user’s document as write_atomic does, but natively through an existing symbolic link and keeping the file’s permission bits, so saving an edited file changes only its contents. Dangling links and files with several names are refused rather than detached. Natively the folder must exist: a chosen folder that has gone (an unmounted drive) is an error, never recreated.

Errors

As write_atomic; natively FsError::NotFound for a missing folder and an unwritable or unsupported existing target.

pub async fn write_private( &self, path: &VPath, bytes: &[u8], ) -> Result<(), FsError>

write_atomic, readable only by this user: natively the file is 0600 and its parent directory 0700. Browser and memory storage are private to the page or process already.

Errors

As write_atomic.

pub async fn create_new( &self, path: &VPath, bytes: &[u8], ) -> Result<bool, FsError>

Publishes bytes at path only while nothing is there, creating missing parents. Returns false, and changes nothing, when the name is taken.

Errors

FsError::InvalidPath for the root, or the backend’s failure.

pub async fn rename_noreplace( &self, from: &VPath, to: &VPath, ) -> Result<(), FsError>

Moves the file or directory at from to to, failing rather than replacing anything at to. Missing parents of to are created.

Errors

FsError::NotFound for from, FsError::AlreadyExists for to, FsError::InvalidPath for the root or a move into itself, and FsError::Unsupported where a backend cannot move this kind of entry (directories in browsers without FileSystemHandle.move, and natively on file systems without no-replace renames).

pub async fn remove(&self, path: &VPath) -> Result<(), FsError>

Removes a file or an empty directory.

Errors

FsError::NotFound, FsError::DirectoryNotEmpty, FsError::InvalidPath for the root, or the backend’s failure.

pub async fn create_dir_all(&self, path: &VPath) -> Result<(), FsError>

Creates the directory and any missing parents; an existing directory is success.

Errors

A file in the way, or the backend’s failure.

pub async fn list(&self, path: &VPath) -> Result<Vec<Entry>, FsError>

The directory’s entries, sorted by name. Natively, names that are not UTF-8 cannot be [VPath] components and are left out.

Errors

FsError::NotFound (including a root nothing was written to yet), FsError::NotADirectory, or the backend’s failure.

pub async fn metadata(&self, path: &VPath) -> Result<Meta, FsError>

Size, modification time and kind of the entry.

Errors

FsError::NotFound, or the backend’s failure.

pub async fn lock(&self, path: &VPath, mode: LockMode) -> Result<Lock, FsError>

Waits for a lock on the lock file at path, created empty (with its parents) when missing. Other processes, and on the web other tabs of the origin, that lock the same path through tilo-files exclude one another as mode says.

Lock a dedicated file, not one you replace with write_atomic: natively a replacement is a new file, and the lock stays on the old one.

Natively the wait blocks the polling thread until tilo_rt::io carries file work; use [blocking::try_lock] to avoid waiting.

Errors

FsError::InvalidPath for the root, FsError::Unsupported in a browser without Web Locks, or the backend’s failure.

pub fn watch(&self, path: &VPath) -> Result<Watch, FsError>

Watches path (a file, or a directory and everything below it) for changes. The watch reports paths relative to this Dir.

Errors

FsError::Unsupported with [Feature::Watch] for native directories in a build without the watch feature; natively, FsError::NotFound when path does not exist yet.

pub async fn trash(&self, path: &VPath) -> Result<(), FsError>

Moves the entry to the user’s trash. Not in this version.

Errors

FsError::Unsupported with [Feature::Trash] on every target.

pub fn native_path(&self, path: &VPath) -> Result<PathBuf, Unsupported<Feature>>

The operating-system path of path, for code that must hand one to a native API. Portable code uses the operations above.

Errors

[Unsupported] for browser and in-memory storage.

Trait Implementations

impl Clone for Dir

fn clone(&self) -> Dir

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Dir

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

Formats the value using the given formatter.