This is an automated email from the ASF dual-hosted git repository. xuanwo pushed a commit to branch fix-stat in repository https://gitbox.apache.org/repos/asf/incubator-opendal.git
commit fc125ff9129828c8310abbb0f9413355bc065227 Author: Xuanwo <[email protected]> AuthorDate: Tue Nov 21 15:57:57 2023 +0800 polish stat docs Signed-off-by: Xuanwo <[email protected]> --- core/src/types/operator/blocking_operator.rs | 30 ++++++++++++++++++---------- core/src/types/operator/operator.rs | 27 ++++++++++++++++--------- 2 files changed, 37 insertions(+), 20 deletions(-) diff --git a/core/src/types/operator/blocking_operator.rs b/core/src/types/operator/blocking_operator.rs index 5caed7534..de5bb8d7b 100644 --- a/core/src/types/operator/blocking_operator.rs +++ b/core/src/types/operator/blocking_operator.rs @@ -141,7 +141,7 @@ impl BlockingOperator { /// # Operator blocking API. impl BlockingOperator { - /// Get current path's metadata. + /// Get given path's metadata. /// /// # Notes /// @@ -151,6 +151,8 @@ impl BlockingOperator { /// /// # Examples /// + /// ## Check if file exists + /// /// ``` /// # use anyhow::Result; /// # use futures::io; @@ -170,29 +172,35 @@ impl BlockingOperator { self.stat_with(path).call() } - /// Get current path's metadata **without cache** directly with extra options. + /// Get given path's metadata with extra options. /// /// # Notes /// - /// Use `stat` if you: + /// For fetch metadata of entries returned by [`Lister`], it's better to use [`list_with`] and + /// [`lister_with`] with `metakey` query like `Metakey::ContentLength | Metakey::LastModified` + /// so that we can avoid extra requests. /// - /// - Want to detect the outside changes of path. - /// - Don't want to read from cached metadata. + /// # Examples /// - /// You may want to use `metadata` if you are working with entries - /// returned by [`Lister`]. It's highly possible that metadata - /// you want has already been cached. + /// ## Get metadata while `ETag` matches /// - /// # Examples + /// `stat_with` will + /// + /// - return `Ok(metadata)` if `ETag` matches + /// - return `Err(error)` and `error.kind() == ErrorKind::ConditionNotMatch` if file exists but + /// `ETag` mismatch + /// - return `Err(err)` if other errors occur, for example, `NotFound`. /// /// ``` /// # use anyhow::Result; /// # use opendal::BlockingOperator; /// use opendal::ErrorKind; /// # - /// # #[tokio::main] - /// # async fn test(op: BlockingOperator) -> Result<()> { + /// # fn test(op: BlockingOperator) -> Result<()> { /// if let Err(e) = op.stat_with("test").if_match("<etag>").call() { + /// if e.kind() == ErrorKind::ConditionNotMatch { + /// println!("file exists, but etag mismatch") + /// } /// if e.kind() == ErrorKind::NotFound { /// println!("file not exist") /// } diff --git a/core/src/types/operator/operator.rs b/core/src/types/operator/operator.rs index e1de7cc74..b861c5ca9 100644 --- a/core/src/types/operator/operator.rs +++ b/core/src/types/operator/operator.rs @@ -158,7 +158,7 @@ impl Operator { } } - /// Get current path's metadata. + /// Get given path's metadata. /// /// # Notes /// @@ -168,6 +168,8 @@ impl Operator { /// /// # Examples /// + /// ## Check if file exists + /// /// ``` /// # use anyhow::Result; /// # use futures::io; @@ -188,20 +190,24 @@ impl Operator { self.stat_with(path).await } - /// Get current path's metadata **without cache** directly with extra options. + /// Get given path's metadata with extra options. /// /// # Notes /// - /// Use `stat` if you: + /// For fetch metadata of entries returned by [`Lister`], it's better to use [`list_with`] and + /// [`lister_with`] with `metakey` query like `Metakey::ContentLength | Metakey::LastModified` + /// so that we can avoid extra requests. + /// + /// # Examples /// - /// - Want to detect the outside changes of path. - /// - Don't want to read from cached metadata. + /// ## Get metadata while `ETag` matches /// - /// You may want to use `metadata` if you are working with entries - /// returned by [`Lister`]. It's highly possible that metadata - /// you want has already been cached. + /// `stat_with` will /// - /// # Examples + /// - return `Ok(metadata)` if `ETag` matches + /// - return `Err(error)` and `error.kind() == ErrorKind::ConditionNotMatch` if file exists but + /// `ETag` mismatch + /// - return `Err(err)` if other errors occur, for example, `NotFound`. /// /// ``` /// # use anyhow::Result; @@ -212,6 +218,9 @@ impl Operator { /// # #[tokio::main] /// # async fn test(op: Operator) -> Result<()> { /// if let Err(e) = op.stat_with("test").if_match("<etag>").await { + /// if e.kind() == ErrorKind::ConditionNotMatch { + /// println!("file exists, but etag mismatch") + /// } /// if e.kind() == ErrorKind::NotFound { /// println!("file not exist") /// }
