Enum LocalFiles 

pub enum LocalFiles {}

File-system utility namespace.

This type is an uninstantiable namespace. Use its associated methods for small recurring file operations, including parent creation, local directory operations, and atomic replacement writes.

Examples

use qubit_local_files::{
    LocalFiles,
    LocalTempDir,
};

let dir = LocalTempDir::with_prefix(Some("qubit-local-files-doc-"))?;
let path = dir.path().join("nested").join("data.txt");

LocalFiles::atomic_write(&path, b"payload")?;
assert_eq!(b"payload", std::fs::read(&path)?.as_slice());

Implementations

impl LocalFiles

pub const DEFAULT_TEMP_FILE_PREFIX: &str = "qubit-local-files-"

Default prefix used when callers do not provide a temporary file prefix.

pub const DEFAULT_TEMP_FILE_RETRIES: usize = 256

Default number of attempts used when creating a random temporary entry.

pub fn exists<P>(path: P) -> Result<bool>

where P: AsRef<Path>,

Tests whether a path exists.

Parameters

• path: Path to inspect.

Returns

true when path exists and false when it is missing.

Errors

Returns an I/O error when the filesystem cannot determine whether the path exists. Unlike Path::exists, this method does not silently map inspection errors to false.

pub fn metadata<P>(path: P) -> Result<Metadata>

where P: AsRef<Path>,

Reads metadata for a local filesystem path.

Parameters

• path: Path whose metadata should be read.

Returns

Metadata reported by fs::metadata.

Errors

Returns the I/O error reported by the filesystem. Symbolic links are followed, matching fs::metadata.

pub fn list<P>(path: P) -> Result<ReadDir>

where P: AsRef<Path>,

Lists the direct entries of a directory.

Parameters

• path: Directory path to list.

Returns

A directory iterator over direct children of path.

Errors

Returns the I/O error reported by fs::read_dir.

pub fn open_reader<P>( path: P, options: FileReadOptions, ) -> Result<LocalFileReader>

where P: AsRef<Path>,

Opens a local file for reading.

The target must be a file. Directories and other non-file paths are rejected before returning the reader.

Parameters

• path: File path to open.
• options: Read options controlling buffering.

Returns

A file reader matching options.

Errors

Returns an I/O error when path cannot be inspected or opened, when the target is not a file, or when the requested buffer capacity is invalid.

pub fn open_writer<P>( path: P, options: FileWriteOptions, ) -> Result<LocalFileWriter>

where P: AsRef<Path>,

Opens a local file for writing.

This method centralizes normal write-handle creation. Whole-file durable replacement remains the responsibility of LocalFiles::atomic_write and LocalFiles::atomic_write_with.

Parameters

• path: File path to open.
• options: Write options controlling parent creation, write mode, and buffering.

Returns

A file writer matching options.

Errors

Returns an I/O error when parent directories cannot be created, the file cannot be opened with the requested mode, or the requested buffer capacity is invalid.

pub fn ensure_dir<P>(path: P) -> Result<()>

where P: AsRef<Path>,

Ensures that a directory exists.

Parameters

• path: Directory path to create if missing.

Errors

Returns an I/O error when the directory or one of its ancestors cannot be created.

pub fn ensure_parent<P>(path: P) -> Result<()>

where P: AsRef<Path>,

Ensures that a path’s parent directory exists.

Parentless paths and paths whose parent is empty are accepted without creating any directory.

Parameters

• path: File path whose parent directory should be created.

Errors

Returns an I/O error when the parent directory or one of its ancestors cannot be created.

pub fn dir_size<P>(path: P) -> Result<u64>

where P: AsRef<Path>,

Computes the total size of regular files under a directory.

The root path must be a directory. This method walks the directory tree recursively, sums the byte length of regular files, and does not follow symbolic links. Symbolic links are ignored.

Parameters

• path: Directory whose regular-file contents should be measured.

Returns

Total byte length of regular files contained in the directory tree.

Errors

Returns an I/O error when path cannot be inspected, is not a directory, or one of the directory entries cannot be read.

pub fn clean_dir<P>(path: P) -> Result<()>

where P: AsRef<Path>,

Removes all entries from a directory while keeping the directory itself.

This method deletes files, directories, and symbolic links directly contained in path. Nested directories are removed recursively. Symbolic links are removed as links and are not followed.

Parameters

• path: Directory to clean.

Errors

Returns an I/O error when path cannot be read, is not a directory, or one of its entries cannot be removed.

pub fn remove_any<P>(path: P) -> Result<()>

where P: AsRef<Path>,

Removes a file, directory, or symbolic link.

Directories are removed recursively. Symbolic links are removed as links and are not followed, including links that point to directories.

Parameters

• path: Path to remove.

Errors

Returns an I/O error when path cannot be inspected or removed.

pub fn copy_dir_all_with<S, D>( src: S, dst: D, options: LocalCopyDirOptions, ) -> Result<LocalCopyDirStats>

where S: AsRef<Path>, D: AsRef<Path>,

Recursively copies a directory tree.

The source path must be a directory. The destination directory is created when missing. Existing files are rejected unless LocalCopyDirOptions::overwrite is enabled. By default, symbolic links are rejected instead of followed so a copy cannot accidentally leave the requested source tree.

This method also rejects destinations located inside the source tree or inside any followed source directory, because copying a directory into itself can recurse indefinitely. Directory cycles introduced by followed symbolic links are rejected before recursive copy enters the repeated directory.

Parameters

• src: Source directory.
• dst: Destination directory.
• options: Copy behavior options.

Returns

Statistics describing copied files, created directories, and copied bytes.

Errors

Returns an I/O error when the source is not a directory, the destination is inside the source tree, a destination entry exists without overwrite permission, a symbolic link is encountered while follow_symlinks is false, or an underlying filesystem operation fails.

pub fn atomic_write<P, B>(path: P, bytes: B) -> Result<()>

where P: AsRef<Path>, B: AsRef<[u8]>,

Atomically writes bytes to a path using a temporary file in the same directory.

This method is intended for replacing a whole file with newly generated contents without exposing a partially written destination. Typical use cases include configuration files, cache manifests, checkpoint files, generated indexes, and other small to medium state files where callers want readers to observe either the old complete file or the new complete file.

Parent directories are created before writing. The data is written to a randomly named same-directory temporary file, flushed and synced, and then renamed over the destination path with platform-specific replace semantics. Using the same directory keeps the temporary file on the same filesystem as the destination, which is required for atomic replacement on common platforms. After the replacement, the parent directory is synced so directory metadata reaches durable storage on platforms that support directory syncing.

If path is a symbolic link on platforms where renaming over a symbolic link replaces the link itself, this method replaces the symbolic link with the new regular file and leaves the former link target unchanged.

If writing or syncing the temporary file fails, the temporary file is removed and the existing destination is left untouched. If replacement succeeds but syncing the parent directory fails, the destination may already contain the new contents even though this method returns an error.

This method is not a multi-file transaction and does not coordinate concurrent writers. Use an external lock if multiple processes or threads may replace the same path at the same time. It is also not an append helper; append-only logs should use normal append-mode writes.

Examples

use qubit_local_files::{
    LocalFiles,
    LocalTempDir,
};

let dir = LocalTempDir::with_prefix(Some("qubit-local-files-atomic-"))?;
let path = dir.path().join("state").join("manifest.json");

LocalFiles::atomic_write(&path, br#"{"version":1,"complete":true}"#)?;

assert_eq!(
    br#"{"version":1,"complete":true}"#,
    std::fs::read(&path)?.as_slice(),
);

Parameters

• path: Destination path.
• bytes: Bytes to write.

Errors

Returns the first I/O error reported while creating, writing, syncing, removing, replacing, or syncing the temporary file or parent directory.

pub fn atomic_write_with<P, F>(path: P, write: F) -> Result<()>

where P: AsRef<Path>, F: FnMut(&mut File) -> Result<()>,

Atomically writes a file using caller-provided write logic.

The closure receives the temporary file. After the closure succeeds, the file is flushed, synced, closed, replaced over the destination path, and the parent directory is synced. If replacement succeeds but syncing the parent directory fails, the destination may already contain the new contents even though this method returns an error.

Parameters

• path: Destination path.
• write: Function that writes the desired contents into the temporary file.

Errors

Returns the first I/O error reported while creating, writing, syncing, removing, replacing, or syncing the temporary file or parent directory.