Trait cap_std_ext::dirext::CapStdExtDirExt

pub trait CapStdExtDirExt {
    // Required methods
    fn open_optional(&self, path: impl AsRef<Path>) -> Result<Option<File>>;
    fn open_dir_optional(&self, path: impl AsRef<Path>) -> Result<Option<Dir>>;
    fn ensure_dir_with(
        &self,
        p: impl AsRef<Path>,
        builder: &DirBuilder,
    ) -> Result<bool>;
    fn metadata_optional(
        &self,
        path: impl AsRef<Path>,
    ) -> Result<Option<Metadata>>;
    fn symlink_metadata_optional(
        &self,
        path: impl AsRef<Path>,
    ) -> Result<Option<Metadata>>;
    fn remove_file_optional(&self, path: impl AsRef<Path>) -> Result<bool>;
    fn remove_all_optional(&self, path: impl AsRef<Path>) -> Result<bool>;
    fn update_timestamps(&self, path: impl AsRef<Path>) -> Result<()>;
    fn atomic_replace_with<F, T, E>(
        &self,
        destname: impl AsRef<Path>,
        f: F,
    ) -> Result<T, E>
       where F: FnOnce(&mut BufWriter<TempFile<'_>>) -> Result<T, E>,
             E: From<Error>;
    fn atomic_write(
        &self,
        destname: impl AsRef<Path>,
        contents: impl AsRef<[u8]>,
    ) -> Result<()>;
    fn atomic_write_with_perms(
        &self,
        destname: impl AsRef<Path>,
        contents: impl AsRef<[u8]>,
        perms: Permissions,
    ) -> Result<()>;
}

Extension trait for cap_std::fs::Dir.

Required Methods

fn open_optional(&self, path: impl AsRef<Path>) -> Result<Option<File>>

Open a file read-only, but return Ok(None) if it does not exist.

fn open_dir_optional(&self, path: impl AsRef<Path>) -> Result<Option<Dir>>

Open a directory, but return Ok(None) if it does not exist.

fn ensure_dir_with( &self, p: impl AsRef<Path>, builder: &DirBuilder, ) -> Result<bool>

Create the target directory, but do nothing if a directory already exists at that path. The return value will be true if the directory was created. An error will be returned if the path is a non-directory. Symbolic links will be followed.

fn metadata_optional(&self, path: impl AsRef<Path>) -> Result<Option<Metadata>>

Gather metadata, but return Ok(None) if it does not exist.

fn symlink_metadata_optional( &self, path: impl AsRef<Path>, ) -> Result<Option<Metadata>>

Gather metadata (but do not follow symlinks), but return Ok(None) if it does not exist.

fn remove_file_optional(&self, path: impl AsRef<Path>) -> Result<bool>

Remove (delete) a file, but return Ok(false) if the file does not exist.

fn remove_all_optional(&self, path: impl AsRef<Path>) -> Result<bool>

Remove a file or directory but return Ok(false) if the file does not exist. Symbolic links are not followed.

fn update_timestamps(&self, path: impl AsRef<Path>) -> Result<()>

Set the access and modification times to the current time. Symbolic links are not followed.

fn atomic_replace_with<F, T, E>( &self, destname: impl AsRef<Path>, f: F, ) -> Result<T, E>

where F: FnOnce(&mut BufWriter<TempFile<'_>>) -> Result<T, E>, E: From<Error>,

Atomically write a file by calling the provided closure.

This uses cap_tempfile::TempFile, which is wrapped in a std::io::BufWriter and passed to the closure.

Existing files and metadata

If the target path already exists and is a regular file (not a symbolic link or directory), then its access permissions (Unix mode) will be preserved. However, other metadata such as extended attributes will not be preserved automatically. To do this will require a higher level wrapper which queries the existing file and gathers such metadata before replacement.

Example, including setting permissions

The closure may also perform other file operations beyond writing, such as changing file permissions:

use cap_std_ext::prelude::*;
let contents = b"hello world\n";
somedir.atomic_replace_with("somefilename", |f| -> io::Result<_> {
    f.write_all(contents)?;
    f.flush()?;
    use cap_std::fs::PermissionsExt;
    let perms = cap_std::fs::Permissions::from_mode(0o600);
    f.get_mut().as_file_mut().set_permissions(perms)?;
    Ok(())
})

Any existing file will be replaced.

fn atomic_write( &self, destname: impl AsRef<Path>, contents: impl AsRef<[u8]>, ) -> Result<()>

Atomically write the provided contents to a file.

fn atomic_write_with_perms( &self, destname: impl AsRef<Path>, contents: impl AsRef<[u8]>, perms: Permissions, ) -> Result<()>

Atomically write the provided contents to a file, using specified permissions.

Object Safety

This trait is not object safe.

Implementations on Foreign Types

impl CapStdExtDirExt for Dir

fn open_optional(&self, path: impl AsRef<Path>) -> Result<Option<File>>

fn open_dir_optional(&self, path: impl AsRef<Path>) -> Result<Option<Dir>>

fn ensure_dir_with( &self, p: impl AsRef<Path>, builder: &DirBuilder, ) -> Result<bool>

fn metadata_optional(&self, path: impl AsRef<Path>) -> Result<Option<Metadata>>

fn symlink_metadata_optional( &self, path: impl AsRef<Path>, ) -> Result<Option<Metadata>>

fn remove_file_optional(&self, path: impl AsRef<Path>) -> Result<bool>

fn remove_all_optional(&self, path: impl AsRef<Path>) -> Result<bool>

fn update_timestamps(&self, path: impl AsRef<Path>) -> Result<()>

fn atomic_replace_with<F, T, E>( &self, destname: impl AsRef<Path>, f: F, ) -> Result<T, E>

where F: FnOnce(&mut BufWriter<TempFile<'_>>) -> Result<T, E>, E: From<Error>,

fn atomic_write( &self, destname: impl AsRef<Path>, contents: impl AsRef<[u8]>, ) -> Result<()>

fn atomic_write_with_perms( &self, destname: impl AsRef<Path>, contents: impl AsRef<[u8]>, perms: Permissions, ) -> Result<()>

Implementors