This is an automated email from the ASF dual-hosted git repository.
xuanwo pushed a commit to branch implement-list-metakey
in repository https://gitbox.apache.org/repos/asf/incubator-opendal.git
The following commit(s) were added to refs/heads/implement-list-metakey by this
push:
new 9ec63e4e2 Add docs
9ec63e4e2 is described below
commit 9ec63e4e2edd9a0597c3b78702c3f22c7f939bdf
Author: Xuanwo <[email protected]>
AuthorDate: Mon Aug 7 16:16:13 2023 +0800
Add docs
Signed-off-by: Xuanwo <[email protected]>
---
core/src/types/entry.rs | 88 +++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 88 insertions(+)
diff --git a/core/src/types/entry.rs b/core/src/types/entry.rs
index e735833a7..d6a062828 100644
--- a/core/src/types/entry.rs
+++ b/core/src/types/entry.rs
@@ -97,11 +97,99 @@ impl Entry {
}
/// Fetch metadata of this entry.
+ ///
+ /// # Notes
+ ///
+ /// Metadata only guaranteed to have results of `metakey` (which default
to `Metakey::Mode`).
+ ///
+ /// - `Some(T)` means the metadata is valid.
+ /// - `None` means the metadata is not provided by services.
+ ///
+ /// Visiting a metadata that not covered by `metakey` could result in
panic.
+ ///
+ /// # Examples
+ ///
+ /// Please use `metakey` to specify the metadata you want, for example:
+ ///
+ /// ```no_run
+ /// # use anyhow::Result;
+ /// use opendal::EntryMode;
+ /// use opendal::Metakey;
+ /// use opendal::Operator;
+ /// # #[tokio::main]
+ /// # async fn test(op: Operator) -> Result<()> {
+ /// let mut entries = op
+ /// .list_with("dir/")
+ /// .metakey(Metakey::ContentLength | Metakey::LastModified)
+ /// .await?;
+ /// for entry in entries {
+ /// let meta = entry.metadata();
+ /// match meta.mode() {
+ /// EntryMode::FILE => {
+ /// println!(
+ /// "Handling file {} with size {}",
+ /// entry.path(),
+ /// meta.content_length()
+ /// )
+ /// }
+ /// EntryMode::DIR => {
+ /// println!("Handling dir {}", entry.path())
+ /// }
+ /// EntryMode::Unknown => continue,
+ /// }
+ /// }
+ /// # Ok(())
+ /// # }
+ /// ```
pub fn metadata(&self) -> &Metadata {
&self.metadata
}
/// Consume this entry to get it's path and metadata.
+ ///
+ /// # Notes
+ ///
+ /// Metadata only guaranteed to have results of `metakey` (which default
to `Metakey::Mode`).
+ ///
+ /// - `Some(T)` means the metadata is valid.
+ /// - `None` means the metadata is not provided by services.
+ ///
+ /// Visiting a metadata that not covered by `metakey` could result in
panic.
+ ///
+ /// # Examples
+ ///
+ /// Please use `metakey` to specify the metadata you want, for example:
+ ///
+ /// ```no_run
+ /// # use anyhow::Result;
+ /// use opendal::EntryMode;
+ /// use opendal::Metakey;
+ /// use opendal::Operator;
+ /// # #[tokio::main]
+ /// # async fn test(op: Operator) -> Result<()> {
+ /// let mut entries = op
+ /// .list_with("dir/")
+ /// .metakey(Metakey::ContentLength | Metakey::LastModified)
+ /// .await?;
+ /// for entry in entries {
+ /// let (path, meta) = entry.into_parts();
+ /// match meta.mode() {
+ /// EntryMode::FILE => {
+ /// println!(
+ /// "Handling file {} with size {}",
+ /// path,
+ /// meta.content_length()
+ /// )
+ /// }
+ /// EntryMode::DIR => {
+ /// println!("Handling dir {}", path)
+ /// }
+ /// EntryMode::Unknown => continue,
+ /// }
+ /// }
+ /// # Ok(())
+ /// # }
+ /// ```
pub fn into_parts(self) -> (String, Metadata) {
(self.path, self.metadata)
}
