Struct opendal::Object

pub struct Object { /* private fields */ }

Handler for all object related operations.

Implementations

impl Object

pub fn new(acc: Arc<dyn Accessor>, path: &str) -> Self

Creates a new Object with normalized path.

• All path will be converted into relative path (without any leading /)
• Path endswith / means it’s a dir path.
• Otherwise, it’s a file path.

pub async fn create(&self) -> Result<()>

Create an empty object, like using the following linux commands:

• touch path/to/file
• mkdir path/to/dir/

Behavior

• Create on existing dir will succeed.
• Create on existing file will overwrite and truncate it.

Examples

Create an empty file

let o = op.object("path/to/file");
let _ = o.create().await?;

Create a dir

let o = op.object("path/to/dir/");
let _ = o.create().await?;

pub async fn read(&self) -> Result<Vec<u8>>

Read the whole object into a bytes.

This function will allocate a new bytes internally. For more precise memory control or reading data lazily, please use Object::reader

Examples

let bs = o.read().await?;

pub async fn range_read(&self, range: impl RangeBounds<u64>) -> Result<Vec<u8>>

Read the specified range of object into a bytes.

This function will allocate a new bytes internally. For more precise memory control or reading data lazily, please use Object::range_reader

Examples

let bs = o.range_read(1024..2048).await?;

pub async fn reader(&self) -> Result<impl BytesRead>

Create a new reader which can read the whole object.

Examples

let r = o.reader().await?;

pub async fn range_reader(
    &self,
    range: impl RangeBounds<u64>
) -> Result<impl BytesRead>

Create a new reader which can read the specified range.

Examples

let r = o.range_reader(1024..2048).await?;

pub fn seekable_reader(&self, range: impl RangeBounds<u64>) -> SeekableReader

Create a reader which implements AsyncRead and AsyncSeek inside specified range.

Notes

It’s not a zero-cost operations. In order to support seeking, we have extra internal state which maintains the reader contents:

• Seeking is pure in memory operation.
• Every first read after seeking will start a new read operation on backend.

This operation is neither async nor returning result, because real IO happens while users call read or seek.

Examples

let r = o.seekable_reader(1024..2048);

pub async fn write(&self, bs: impl AsRef<[u8]>) -> Result<()>

Write bytes into object.

Notes

• Write will make sure all bytes has been written, or an error will be returned.

Examples

use bytes::Bytes;

let o = op.object("path/to/file");
let _ = o.write(vec![0; 4096]).await?;

pub async fn writer(&self, size: u64) -> Result<impl BytesWrite>

Create a new writer which can write data into the object.

Examples

use bytes::Bytes;

let op = Operator::new(memory::Backend::build().finish().await?);
let o = op.object("path/to/file");
let mut w = o.writer(4096).await?;
w.write(&[1; 4096]);
w.close();

pub async fn delete(&self) -> Result<()>

Delete object.

Notes

• Delete not existing error won’t return errors.

Examples

op.object("test").delete().await?;

pub async fn list(&self) -> Result<ObjectStreamer>

List current dir object.

This function will create a new ObjectStreamer handle to list objects.

An error will be returned if object path doesn’t end with /.

Examples

let o = op.object("path/to/dir/");
let mut obs = o.list().await?;
// ObjectStream implements `futures::Stream`
while let Some(o) = obs.next().await {
    let mut o = o?;
    // It's highly possible that OpenDAL already did metadata during list.
    // Use `Object::metadata_cached()` to get cached metadata at first.
    let meta = o.metadata_cached().await?;
    match meta.mode() {
        ObjectMode::FILE => {
            println!("Handling file")
        }
        ObjectMode::DIR => {
            println!("Handling dir like start a new list via meta.path()")
        }
        ObjectMode::Unknown => continue,
    }
}

pub async fn metadata(&self) -> Result<Metadata>

Get current object’s metadata.

Examples

use std::io::ErrorKind;
if let Err(e) = op.object("test").metadata().await {
    if e.kind() == ErrorKind::NotFound {
        println!("object not exist")
    }
}

pub async fn metadata_cached(&mut self) -> Result<&Metadata>

Use local cached metadata if possible.

Example

use opendal::services::memory;
use anyhow::Result;
use futures::io;
use opendal::Operator;


#[tokio::main]
async fn main() -> Result<()> {
    let op = Operator::new(memory::Backend::build().finish().await?);
    let mut o = op.object("test");

    o.metadata_cached().await;
    // The second call to metadata_cached will have no cost.
    o.metadata_cached().await;

    Ok(())
}

pub async fn is_exist(&self) -> Result<bool>

Check if this object exist or not.

Example

use opendal::services::memory;
use anyhow::Result;
use futures::io;
use opendal::Operator;


#[tokio::main]
async fn main() -> Result<()> {
    let op = Operator::new(memory::Backend::build().finish().await?);
    let _ = op.object("test").is_exist().await?;

    Ok(())
}

Trait Implementations

impl Clone for Object

fn clone(&self) -> Object

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Object

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.