diff --git a/CHANGELOG.md b/CHANGELOG.md index e20bd71..2efbb6b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,7 @@ +# Version 2.1.3 + +- Add `async_fs::try_exists` function, which is an async wrapper for `std::path::Path::try_exists`. + # Version 2.1.2 - Ensure that the docs for `create_dir_all` are close to the equivalent function diff --git a/Cargo.toml b/Cargo.toml index 22aef2e..0faaaa3 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -3,7 +3,7 @@ name = "async-fs" # When publishing a new version: # - Update CHANGELOG.md # - Create "v2.x.y" git tag -version = "2.1.2" +version = "2.1.3" authors = ["Stjepan Glavina "] edition = "2021" rust-version = "1.63" @@ -26,6 +26,4 @@ libc = "0.2.78" [target.'cfg(windows)'.dev-dependencies.windows-sys] version = "0.59" -features = [ - "Win32_Storage_FileSystem", -] +features = ["Win32_Storage_FileSystem"] diff --git a/src/lib.rs b/src/lib.rs index 8e5a330..fcbfd9c 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -82,6 +82,33 @@ pub async fn canonicalize>(path: P) -> io::Result { unblock(move || std::fs::canonicalize(path)).await } +/// Returns `Ok(true)` if the path points at an existing entity. +/// +/// This function will traverse symbolic links to query information about the +/// destination file. In case of broken symbolic links this will return `Ok(false)`. +/// +/// [`try_exists`] only checks whether or not a path was both found and readable. +/// +/// Note that while this avoids some pitfalls of the `exists()` method, it still can not +/// prevent time-of-check to time-of-use (TOCTOU) bugs. You should only use it in scenarios +/// where those bugs are not an issue. +/// +/// This is the async equivalent of [std::path::Path::try_exists]. +/// +/// # Examples +/// +/// ```no_run +/// use std::path::Path; +/// # futures_lite::future::block_on(async { +/// assert!(!async_fs::try_exists(Path::new("does_not_exist.txt")).await.unwrap()); +/// assert!(!async_fs::try_exists(Path::new("exists.txt")).await.unwrap()); +/// # std::io::Result::Ok(()) }); +/// ``` +pub async fn try_exists>(path: P) -> io::Result { + let path = path.as_ref().to_owned(); + unblock(move || path.try_exists()).await +} + /// Copies a file to a new location. /// /// On success, the total number of bytes copied is returned and equals the length of the `dst`