Trait Filesystem 

pub trait Filesystem {
    type ReadDir: Stream<Item = Result<Self::DirEntry>>;
    type DirEntry: DirEntry;

    // Required methods
    fn canonicalize<'async_trait, P>(
        path: P,
    ) -> Pin<Box<dyn Future<Output = Result<PathBuf>> + Send + 'async_trait>>
       where P: 'async_trait + AsRef<Path> + Send;
    fn copy<'async_trait, S, D>(
        from: S,
        to: D,
    ) -> Pin<Box<dyn Future<Output = Result<u64>> + Send + 'async_trait>>
       where S: 'async_trait + AsRef<Path> + Send,
             D: 'async_trait + AsRef<Path> + Send;
    fn create_dir<'async_trait, P>(
        path: P,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where P: 'async_trait + AsRef<Path> + Send;
    fn create_dir_all<'async_trait, P>(
        path: P,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where P: 'async_trait + AsRef<Path> + Send;
    fn hard_link<'async_trait, S, D>(
        from: S,
        to: D,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where S: 'async_trait + AsRef<Path> + Send,
             D: 'async_trait + AsRef<Path> + Send;
    fn metadata<'async_trait, P>(
        path: P,
    ) -> Pin<Box<dyn Future<Output = Result<Metadata>> + Send + 'async_trait>>
       where P: 'async_trait + AsRef<Path> + Send;
    fn read<'async_trait, P>(
        path: P,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<u8>>> + Send + 'async_trait>>
       where P: 'async_trait + AsRef<Path> + Send;
    fn read_dir<'async_trait, P>(
        path: P,
    ) -> Pin<Box<dyn Future<Output = Result<Self::ReadDir>> + Send + 'async_trait>>
       where P: 'async_trait + AsRef<Path> + Send,
             Self: 'async_trait;
    fn read_link<'async_trait, P>(
        path: P,
    ) -> Pin<Box<dyn Future<Output = Result<PathBuf>> + Send + 'async_trait>>
       where P: 'async_trait + AsRef<Path> + Send;
    fn read_to_string<'async_trait, P>(
        path: P,
    ) -> Pin<Box<dyn Future<Output = Result<String>> + Send + 'async_trait>>
       where P: 'async_trait + AsRef<Path> + Send;
    fn remove_dir<'async_trait, P>(
        path: P,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where P: 'async_trait + AsRef<Path> + Send;
    fn remove_dir_all<'async_trait, P>(
        path: P,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where P: 'async_trait + AsRef<Path> + Send;
    fn remove_file<'async_trait, P>(
        path: P,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where P: 'async_trait + AsRef<Path> + Send;
    fn rename<'async_trait, O, N>(
        from: O,
        to: N,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where O: 'async_trait + AsRef<Path> + Send,
             N: 'async_trait + AsRef<Path> + Send;
    fn set_permissions<'async_trait, P>(
        path: P,
        perm: Permissions,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where P: 'async_trait + AsRef<Path> + Send;
    fn symlink_metadata<'async_trait, P>(
        path: P,
    ) -> Pin<Box<dyn Future<Output = Result<Metadata>> + Send + 'async_trait>>
       where P: 'async_trait + AsRef<Path> + Send;
    fn write<'async_trait, P, C>(
        path: P,
        contents: C,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where P: 'async_trait + AsRef<Path> + Send,
             C: 'async_trait + AsRef<[u8]> + Send;
}

An async abstraction over the functions in std::fs.

Required Associated Types

type ReadDir: Stream<Item = Result<Self::DirEntry>>

type DirEntry: DirEntry

Required Methods

fn canonicalize<'async_trait, P>( path: P, ) -> Pin<Box<dyn Future<Output = Result<PathBuf>> + Send + 'async_trait>>

where P: 'async_trait + AsRef<Path> + Send,

Returns the canonical form of a path.

The returned path is in absolute form with all intermediate components normalized and symbolic links resolved.

This function is an async version of std::fs::canonicalize.

Errors

An error will be returned in the following situations:

• path does not point to an existing file or directory.
• A non-final component in path is not a directory.
• Some other I/O error occurred.

Examples

Using the tokio runtime:

use fut_compat::fs::Filesystem;
use fut_compat::fs::TokioFs;

let path = TokioFs::canonicalize(".").await?;

Using the async_std runtime:

use fut_compat::fs::Filesystem;
use fut_compat::fs::AsyncStdFs;

let path = AsyncStdFs::canonicalize(".").await?;

fn copy<'async_trait, S, D>( from: S, to: D, ) -> Pin<Box<dyn Future<Output = Result<u64>> + Send + 'async_trait>>

where S: 'async_trait + AsRef<Path> + Send, D: 'async_trait + AsRef<Path> + Send,

Copies the contents and permissions of a file to a new location.

On success, the total number of bytes copied is returned and equals the length of the to file after this operation.

The old contents of to will be overwritten. If from and to both point to the same file, then the file will likely get truncated as a result of this operation.

If you’re working with open Files and want to copy contents through those types, use the io::copy function.

This function is an async version of std::fs::copy.

Errors

An error will be returned in the following situations:

• from does not point to an existing file.
• The current process lacks permissions to read from or write to.
• Some other I/O error occurred.

Examples

Using the tokio runtime:

use fut_compat::fs::Filesystem;
use fut_compat::fs::TokioFs;

let num_bytes = TokioFs::copy("a.txt", "b.txt").await?;

Using the async_std runtime:

use fut_compat::fs::Filesystem;
use fut_compat::fs::AsyncStdFs;

let num_bytes = AsyncStdFs::copy("a.txt", "b.txt").await?;

fn create_dir<'async_trait, P>( path: P, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where P: 'async_trait + AsRef<Path> + Send,

Creates a new directory.

Note that this function will only create the final directory in path. If you want to create all of its missing parent directories too, use the create_dir_all function instead.

This function is an async version of std::fs::create_dir.

Errors

An error will be returned in the following situations:

• path already points to an existing file or directory.
• A parent directory in path does not exist.
• The current process lacks permissions to create the directory.
• Some other I/O error occurred.

Examples

Using the tokio runtime:

use fut_compat::fs::Filesystem;
use fut_compat::fs::TokioFs;

TokioFs::create_dir("./some/directory").await?;

Using the async_std runtime:

use fut_compat::fs::Filesystem;
use fut_compat::fs::AsyncStdFs;

AsyncStdFs::create_dir("./some/directory").await?;

fn create_dir_all<'async_trait, P>( path: P, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where P: 'async_trait + AsRef<Path> + Send,

Creates a new directory and all of its parents if they are missing.

This function is an async version of std::fs::create_dir_all.

Errors

An error will be returned in the following situations:

• path already points to an existing file or directory.
• The current process lacks permissions to create the directory or its missing parents.
• Some other I/O error occurred.

Examples

Using the tokio runtime:

use fut_compat::fs::Filesystem;
use fut_compat::fs::TokioFs;

TokioFs::create_dir_all("./some/directory").await?;

Using the async_std runtime:

use fut_compat::fs::Filesystem;
use fut_compat::fs::AsyncStdFs;

AsyncStdFs::create_dir_all("./some/directory").await?;

fn hard_link<'async_trait, S, D>( from: S, to: D, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where S: 'async_trait + AsRef<Path> + Send, D: 'async_trait + AsRef<Path> + Send,

Creates a hard link on the filesystem.

The dst path will be a link pointing to the src path. Note that operating systems often require these two paths to be located on the same filesystem.

This function is an async version of std::fs::hard_link.

Errors

An error will be returned in the following situations:

• src does not point to an existing file.
• Some other I/O error occurred.

Examples

Using the tokio runtime:

use fut_compat::fs::Filesystem;
use fut_compat::fs::TokioFs;

TokioFs::hard_link("a.txt", "b.txt").await?;

Using the async_std runtime:

use fut_compat::fs::Filesystem;
use fut_compat::fs::AsyncStdFs;

AsyncStdFs::hard_link("a.txt", "b.txt").await?;

fn metadata<'async_trait, P>( path: P, ) -> Pin<Box<dyn Future<Output = Result<Metadata>> + Send + 'async_trait>>

where P: 'async_trait + AsRef<Path> + Send,

Reads metadata for a path.

This function will traverse symbolic links to read metadata for the target file or directory. If you want to read metadata without following symbolic links, use symlink_metadata instead.

This function is an async version of std::fs::metadata.

Errors

An error will be returned in the following situations:

• path does not point to an existing file or directory.
• The current process lacks permissions to read metadata for the path.
• Some other I/O error occurred.

Examples

Using the tokio runtime:

use fut_compat::fs::Filesystem;
use fut_compat::fs::TokioFs;

let meta = TokioFs::metadata("a.txt").await?;

Using the async_std runtime:

use fut_compat::fs::Filesystem;
use fut_compat::fs::AsyncStdFs;

let meta = AsyncStdFs::metadata("a.txt").await?;

fn read<'async_trait, P>( path: P, ) -> Pin<Box<dyn Future<Output = Result<Vec<u8>>> + Send + 'async_trait>>

where P: 'async_trait + AsRef<Path> + Send,

Reads the entire contents of a file as raw bytes.

This is a convenience function for reading entire files. It pre-allocates a buffer based on the file size when available, so it is typically faster than manually opening a file and reading from it.

If you want to read the contents as a string, use read_to_string instead.

This function is an async version of std::fs::read.

Errors

An error will be returned in the following situations:

• path does not point to an existing file.
• The current process lacks permissions to read the file.
• Some other I/O error occurred.

Examples

Using the tokio runtime:

use fut_compat::fs::Filesystem;
use fut_compat::fs::TokioFs;

let contents = TokioFs::read("a.txt").await?;

Using the async_std runtime:

use fut_compat::fs::Filesystem;
use fut_compat::fs::AsyncStdFs;

let contents = AsyncStdFs::read("a.txt").await?;

fn read_dir<'async_trait, P>( path: P, ) -> Pin<Box<dyn Future<Output = Result<Self::ReadDir>> + Send + 'async_trait>>

where P: 'async_trait + AsRef<Path> + Send, Self: 'async_trait,

Returns a stream of entries in a directory.

The stream yields items of type io::Result<DirEntry>. Note that I/O errors can occur while reading from the stream.

This function is an async version of std::fs::read_dir.

Errors

An error will be returned in the following situations:

• path does not point to an existing directory.
• The current process lacks permissions to read the contents of the directory.
• Some other I/O error occurred.

Examples

Using the tokio runtime:

use futures::stream::StreamExt;
use fut_compat::fs::Filesystem;
use fut_compat::fs::TokioFs;

let mut entries = TokioFs::read_dir(".").await?;

while let Some(res) = entries.next().await {
    let entry = res?;
    println!("{}", entry.file_name().to_string_lossy());
}

Using the async_std runtime:

use futures::stream::StreamExt;
use fut_compat::fs::Filesystem;
use fut_compat::fs::AsyncStdFs;

let mut entries = AsyncStdFs::read_dir(".").await?;

while let Some(res) = entries.next().await {
    let entry = res?;
    println!("{}", entry.file_name().to_string_lossy());
}

fn read_link<'async_trait, P>( path: P, ) -> Pin<Box<dyn Future<Output = Result<PathBuf>> + Send + 'async_trait>>

where P: 'async_trait + AsRef<Path> + Send,

Reads a symbolic link and returns the path it points to.

This function is an async version of std::fs::read_link.

Errors

An error will be returned in the following situations:

• path does not point to an existing link.
• Some other I/O error occurred.

Examples

Using the tokio runtime:

use fut_compat::fs::Filesystem;
use fut_compat::fs::TokioFs;

let path = TokioFs::read_link("a.txt").await?;

Using the async_std runtime:

use fut_compat::fs::Filesystem;
use fut_compat::fs::AsyncStdFs;

let path = AsyncStdFs::read_link("a.txt").await?;

fn read_to_string<'async_trait, P>( path: P, ) -> Pin<Box<dyn Future<Output = Result<String>> + Send + 'async_trait>>

where P: 'async_trait + AsRef<Path> + Send,

Reads the entire contents of a file as a string.

This is a convenience function for reading entire files. It pre-allocates a string based on the file size when available, so it is typically faster than manually opening a file and reading from it.

If you want to read the contents as raw bytes, use read instead.

This function is an async version of std::fs::read_to_string.

Errors

An error will be returned in the following situations:

• path does not point to an existing file.
• The current process lacks permissions to read the file.
• The contents of the file cannot be read as a UTF-8 string.
• Some other I/O error occurred.

Examples

Using the tokio runtime:

use fut_compat::fs::Filesystem;
use fut_compat::fs::TokioFs;

let contents = TokioFs::read_to_string("a.txt").await?;

Using the async_std runtime:

use fut_compat::fs::Filesystem;
use fut_compat::fs::AsyncStdFs;

let contents = AsyncStdFs::read_to_string("a.txt").await?;

fn remove_dir<'async_trait, P>( path: P, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where P: 'async_trait + AsRef<Path> + Send,

Removes an empty directory.

This function is an async version of std::fs::remove_dir.

Errors

An error will be returned in the following situations:

• path is not an existing and empty directory.
• The current process lacks permissions to remove the directory.
• Some other I/O error occurred.

Examples

Using the tokio runtime:

use fut_compat::fs::Filesystem;
use fut_compat::fs::TokioFs;

TokioFs::remove_dir("./some/directory").await?;

Using the async_std runtime:

use fut_compat::fs::Filesystem;
use fut_compat::fs::AsyncStdFs;

AsyncStdFs::remove_dir("./some/directory").await?;

fn remove_dir_all<'async_trait, P>( path: P, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where P: 'async_trait + AsRef<Path> + Send,

Removes a directory and all of its contents.

This function is an async version of std::fs::remove_dir_all.

Errors

An error will be returned in the following situations:

• path is not an existing and empty directory.
• The current process lacks permissions to remove the directory.
• Some other I/O error occurred.

Examples

Using the tokio runtime:

use fut_compat::fs::Filesystem;
use fut_compat::fs::TokioFs;

TokioFs::remove_dir_all("./some/directory").await?;

Using the async_std runtime:

use fut_compat::fs::Filesystem;
use fut_compat::fs::AsyncStdFs;

AsyncStdFs::remove_dir_all("./some/directory").await?;

fn remove_file<'async_trait, P>( path: P, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where P: 'async_trait + AsRef<Path> + Send,

Removes a file.

This function is an async version of std::fs::remove_file.

Errors

An error will be returned in the following situations:

• path does not point to an existing file.
• The current process lacks permissions to remove the file.
• Some other I/O error occurred.

Examples

Using the tokio runtime:

use fut_compat::fs::Filesystem;
use fut_compat::fs::TokioFs;

TokioFs::remove_file("a.txt").await?;

Using the async_std runtime:

use fut_compat::fs::Filesystem;
use fut_compat::fs::AsyncStdFs;

AsyncStdFs::remove_file("a.txt").await?;

fn rename<'async_trait, O, N>( from: O, to: N, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where O: 'async_trait + AsRef<Path> + Send, N: 'async_trait + AsRef<Path> + Send,

Renames a file or directory to a new location.

If a file or directory already exists at the target location, it will be overwritten by this operation.

This function is an async version of std::fs::rename.

Errors

An error will be returned in the following situations:

• from does not point to an existing file or directory.
• from and to are on different filesystems.
• The current process lacks permissions to do the rename operation.
• Some other I/O error occurred.

Examples

Using the tokio runtime:

use fut_compat::fs::Filesystem;
use fut_compat::fs::TokioFs;

TokioFs::rename("a.txt", "b.txt").await?;

Using the async_std runtime:

use fut_compat::fs::Filesystem;
use fut_compat::fs::AsyncStdFs;

AsyncStdFs::rename("a.txt", "b.txt").await?;

fn set_permissions<'async_trait, P>( path: P, perm: Permissions, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where P: 'async_trait + AsRef<Path> + Send,

Changes the permissions of a file or directory.

This function is an async version of std::fs::set_permissions.

Errors

An error will be returned in the following situations:

• path does not point to an existing file or directory.
• The current process lacks permissions to change attributes on the file or directory.
• Some other I/O error occurred.

Examples

Using the tokio runtime:

use fut_compat::fs::Filesystem;
use fut_compat::fs::TokioFs;

let mut perm = TokioFs::metadata("a.txt").await?.permissions();
perm.set_readonly(true);
TokioFs::set_permissions("a.txt", perm).await?;

Using the async_std runtime:

use fut_compat::fs::Filesystem;
use fut_compat::fs::AsyncStdFs;

let mut perm = AsyncStdFs::metadata("a.txt").await?.permissions();
perm.set_readonly(true);
AsyncStdFs::set_permissions("a.txt", perm).await?;

fn symlink_metadata<'async_trait, P>( path: P, ) -> Pin<Box<dyn Future<Output = Result<Metadata>> + Send + 'async_trait>>

where P: 'async_trait + AsRef<Path> + Send,

Reads metadata for a path without following symbolic links.

If you want to follow symbolic links before reading metadata of the target file or directory, use metadata instead.

This function is an async version of std::fs::symlink_metadata.

Errors

An error will be returned in the following situations:

• path does not point to an existing file or directory.
• The current process lacks permissions to read metadata for the path.
• Some other I/O error occurred.

Examples

Using the tokio runtime:

use fut_compat::fs::Filesystem;
use fut_compat::fs::TokioFs;

let meta = TokioFs::symlink_metadata("a.txt").await?;

Using the async_std runtime:

use fut_compat::fs::Filesystem;
use fut_compat::fs::AsyncStdFs;

let meta = AsyncStdFs::symlink_metadata("a.txt").await?;

fn write<'async_trait, P, C>( path: P, contents: C, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where P: 'async_trait + AsRef<Path> + Send, C: 'async_trait + AsRef<[u8]> + Send,

Writes a slice of bytes as the new contents of a file.

This function will create a file if it does not exist, and will entirely replace its contents if it does.

This function is an async version of std::fs::write.

Errors

An error will be returned in the following situations:

• The file’s parent directory does not exist.
• The current process lacks permissions to write to the file.
• Some other I/O error occurred.

Examples

Using the tokio runtime:

use fut_compat::fs::Filesystem;
use fut_compat::fs::TokioFs;

TokioFs::write("a.txt", b"Hello world!").await?;

Using the async_std runtime:

use fut_compat::fs::Filesystem;
use fut_compat::fs::AsyncStdFs;

AsyncStdFs::write("a.txt", b"Hello world!").await?;

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl Filesystem for AsyncStdFs

Available on crate feature async-std-rt only.

type ReadDir = ReadDir

type DirEntry = DirEntry

impl Filesystem for TokioFs

Available on crate feature tokio-rt only.

type ReadDir = ReadDirStream

type DirEntry = DirEntry