Skip to content

Commit fda4092

Browse files
XuanwoXuanwo
authored
Add examples for object (#135)
Signed-off-by: Xuanwo <[email protected]>
1 parent b9c1fcb commit fda4092

File tree

1 file changed

+193
-0
lines changed

1 file changed

+193
-0
lines changed

‎src/object.rs

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,29 @@ impl Object {
5252
}
5353

5454
/// Create a new reader which can read the whole object.
55+
///
56+
/// # Example
57+
///
58+
/// ```
59+
/// use opendal::services::memory;
60+
/// use anyhow::Result;
61+
/// use futures::io;
62+
/// use opendal::Operator;
63+
///
64+
/// #[tokio::main]
65+
/// async fn main() -> Result<()> {
66+
/// let op = Operator::new(memory::Backend::build().finish().await?);
67+
///
68+
/// let bs = "Hello, World!".as_bytes().to_vec();
69+
/// op.object("test").writer().write_bytes(bs).await?;
70+
///
71+
/// // Read whole file.
72+
/// let mut r = op.object("test").reader();
73+
/// io::copy(&mut r, &mut io::sink()).await?;
74+
///
75+
/// Ok(())
76+
/// }
77+
/// ```
5578
pub fn reader(&self) -> Reader {
5679
Reader::new(self.acc.clone(), self.meta.path(), None, None)
5780
}
@@ -62,6 +85,29 @@ impl Object {
6285
///
6386
/// The input offset and size are not checked, callers could meet error
6487
/// while reading.
88+
///
89+
/// # Example
90+
///
91+
/// ```
92+
/// use opendal::services::memory;
93+
/// use anyhow::Result;
94+
/// use futures::io;
95+
/// use opendal::Operator;
96+
///
97+
/// #[tokio::main]
98+
/// async fn main() -> Result<()> {
99+
/// let op = Operator::new(memory::Backend::build().finish().await?);
100+
///
101+
/// let bs = "Hello, World!".as_bytes().to_vec();
102+
/// op.object("test").writer().write_bytes(bs).await?;
103+
///
104+
/// // Read within [1, 2) bytes.
105+
/// let mut r = op.object("test").range_reader(1, 1);
106+
/// io::copy(&mut r, &mut io::sink()).await?;
107+
///
108+
/// Ok(())
109+
/// }
110+
/// ```
65111
pub fn range_reader(&self, offset: u64, size: u64) -> Reader {
66112
Reader::new(self.acc.clone(), self.meta.path(), Some(offset), Some(size))
67113
}
@@ -71,6 +117,29 @@ impl Object {
71117
/// # Note
72118
///
73119
/// The input offset is not checked, callers could meet error while reading.
120+
///
121+
/// # Example
122+
///
123+
/// ```
124+
/// use opendal::services::memory;
125+
/// use anyhow::Result;
126+
/// use futures::io;
127+
/// use opendal::Operator;
128+
///
129+
/// #[tokio::main]
130+
/// async fn main() -> Result<()> {
131+
/// let op = Operator::new(memory::Backend::build().finish().await?);
132+
///
133+
/// let bs = "Hello, World!".as_bytes().to_vec();
134+
/// op.object("test").writer().write_bytes(bs).await?;
135+
///
136+
/// // Read start offset 4.
137+
/// let mut r = op.object("test").offset_reader(4);
138+
/// io::copy(&mut r, &mut io::sink()).await?;
139+
///
140+
/// Ok(())
141+
/// }
142+
/// ```
74143
pub fn offset_reader(&self, offset: u64) -> Reader {
75144
Reader::new(self.acc.clone(), self.meta.path(), Some(offset), None)
76145
}
@@ -80,30 +149,136 @@ impl Object {
80149
/// # Note
81150
///
82151
/// The input size is not checked, callers could meet error while reading.
152+
///
153+
/// # Example
154+
///
155+
/// ```
156+
/// use opendal::services::memory;
157+
/// use anyhow::Result;
158+
/// use futures::io;
159+
/// use opendal::Operator;
160+
///
161+
/// #[tokio::main]
162+
/// async fn main() -> Result<()> {
163+
/// let op = Operator::new(memory::Backend::build().finish().await?);
164+
///
165+
/// let bs = "Hello, World!".as_bytes().to_vec();
166+
/// op.object("test").writer().write_bytes(bs).await?;
167+
///
168+
/// // Read within 8 bytes.
169+
/// let mut r = op.object("test").limited_reader(8);
170+
/// io::copy(&mut r, &mut io::sink()).await?;
171+
///
172+
/// Ok(())
173+
/// }
174+
/// ```
83175
pub fn limited_reader(&self, size: u64) -> Reader {
84176
Reader::new(self.acc.clone(), self.meta.path(), None, Some(size))
85177
}
86178

87179
/// Create a new writer which can write data into the object.
180+
///
181+
/// # Example
182+
///
183+
/// ```
184+
/// use opendal::services::memory;
185+
/// use anyhow::Result;
186+
/// use futures::io;
187+
/// use opendal::Operator;
188+
///
189+
/// #[tokio::main]
190+
/// async fn main() -> Result<()> {
191+
/// let op = Operator::new(memory::Backend::build().finish().await?);
192+
///
193+
/// let bs = "Hello, World!".as_bytes().to_vec();
194+
/// op.object("test").writer().write_bytes(bs).await?;
195+
///
196+
/// Ok(())
197+
/// }
198+
/// ```
88199
pub fn writer(&self) -> Writer {
89200
Writer::new(self.acc.clone(), self.meta.path())
90201
}
91202

92203
/// Delete current object.
204+
///
205+
/// # Example
206+
///
207+
/// ```
208+
/// use opendal::services::memory;
209+
/// use anyhow::Result;
210+
/// use futures::io;
211+
/// use opendal::Operator;
212+
///
213+
/// #[tokio::main]
214+
/// async fn main() -> Result<()> {
215+
/// let op = Operator::new(memory::Backend::build().finish().await?);
216+
///
217+
/// let bs = "Hello, World!".as_bytes().to_vec();
218+
/// op.object("test").delete().await?;
219+
///
220+
/// Ok(())
221+
/// }
222+
/// ```
93223
pub async fn delete(&self) -> Result<()> {
94224
let op = &OpDelete::new(self.meta.path());
95225

96226
self.acc.delete(op).await
97227
}
98228

99229
/// Get current object's metadata.
230+
///
231+
/// # Example
232+
///
233+
/// ```
234+
/// use opendal::services::memory;
235+
/// use anyhow::Result;
236+
/// use futures::io;
237+
/// use opendal::Operator;
238+
/// use opendal::error::Kind;
239+
///
240+
/// #[tokio::main]
241+
/// async fn main() -> Result<()> {
242+
/// let op = Operator::new(memory::Backend::build().finish().await?);
243+
///
244+
/// if let Err(e) = op.object("test").metadata().await {
245+
/// if e.kind() == Kind::ObjectNotExist {
246+
/// println!("object not exist")
247+
/// }
248+
/// }
249+
///
250+
/// Ok(())
251+
/// }
252+
/// ```
100253
pub async fn metadata(&self) -> Result<Metadata> {
101254
let op = &OpStat::new(self.meta.path());
102255

103256
self.acc.stat(op).await
104257
}
105258

106259
/// Use local cached metadata if possible.
260+
///
261+
/// # Example
262+
///
263+
/// ```
264+
/// use opendal::services::memory;
265+
/// use anyhow::Result;
266+
/// use futures::io;
267+
/// use opendal::Operator;
268+
/// use opendal::error::Kind;
269+
///
270+
/// #[tokio::main]
271+
/// async fn main() -> Result<()> {
272+
/// let op = Operator::new(memory::Backend::build().finish().await?);
273+
/// let mut o = op.object("test");
274+
///
275+
/// o.metadata_cached().await;
276+
/// // The second call to metadata_cached will have no cost.
277+
/// o.metadata_cached().await;
278+
///
279+
/// Ok(())
280+
/// }
281+
/// ```
107282
pub async fn metadata_cached(&mut self) -> Result<&Metadata> {
108283
if self.meta.complete() {
109284
return Ok(&self.meta);
@@ -120,6 +295,24 @@ impl Object {
120295
}
121296

122297
/// Check if this object exist or not.
298+
///
299+
/// # Example
300+
///
301+
/// ```
302+
/// use opendal::services::memory;
303+
/// use anyhow::Result;
304+
/// use futures::io;
305+
/// use opendal::Operator;
306+
/// use opendal::error::Kind;
307+
///
308+
/// #[tokio::main]
309+
/// async fn main() -> Result<()> {
310+
/// let op = Operator::new(memory::Backend::build().finish().await?);
311+
/// let _ = op.object("test").is_exist().await?;
312+
///
313+
/// Ok(())
314+
/// }
315+
/// ```
123316
pub async fn is_exist(&self) -> Result<bool> {
124317
let r = self.metadata().await;
125318
match r {

0 commit comments

Comments
 (0)