Struct zbox::File

pub struct File { /* fields omitted */ }

A reference to an opened file in the repository.

An instance of a File can be read and/or written depending on what options it was opened with. Files also implement Seek to alter the logical cursor that the file contains internally.

Files are automatically closed when they go out of scope.

As ZboxFS internally cached file content, it is no need to use buffered reader, such as BufReader<R>.

Examples

Create a new file and write bytes to it:

use std::io::prelude::*;

let mut file = repo.create_file("/foo.txt")?;
file.write_all(b"Hello, world!")?;
file.finish()?;

Read the content of a file into a String:

use std::io::prelude::*;

let mut file = repo.open_file("/foo.txt")?;
let mut content = String::new();
file.read_to_string(&mut content)?;
assert_eq!(content, "Hello, world!");

Versioning

File contents support up to 255 revision versions. Version is immutable once it is created.

By default, the maximum number of versions of a File is 1, which is configurable by version_limit on both Repo and File level. File level option takes precedence.

After reaching this limit, the oldest Version will be automatically deleted after adding a new one.

Version number starts from 1 and continuously increases by 1.

Writing

The file content is cached internally for deduplication and will be handled automatically, thus calling flush is not recommended.

File is multi-versioned, each time updating its content will create a new permanent Version. There are two ways of writing data to a file:

• Multi-part Write

  This is done by updating File using Write trait multiple times. After all writing operations, finish must be called to create a new version.

  Examples

  use std::io::prelude::*;
  use std::io::SeekFrom;
  
  let mut file = OpenOptions::new()
      .create(true)
      .open(&mut repo, "/foo.txt")?;
  file.write_all(b"foo ")?;
  file.write_all(b"bar")?;
  file.finish()?;
  
  let mut content = String::new();
  file.seek(SeekFrom::Start(0))?;
  file.read_to_string(&mut content)?;
  assert_eq!(content, "foo bar");
  

• Single-part Write

  This can be done by calling write_once, which will call finish internally to create a new version.

  Examples

  use std::io::{Read, Seek, SeekFrom};
  
  let mut file = OpenOptions::new()
      .create(true)
      .open(&mut repo, "/foo.txt")?;
  file.write_once(b"foo bar")?;
  
  let mut content = String::new();
  file.seek(SeekFrom::Start(0))?;
  file.read_to_string(&mut content)?;
  assert_eq!(content, "foo bar");
  

Reading

As File can contain multiple versions, Read operation can be associated with different versions. By default, reading on File object is always bound to the latest version. To read a specific version, a VersionReader, which supports Read trait as well, can be used.

Examples

Read the file content while it is in writing, notice that reading is always bound to latest content version.

use std::io::prelude::*;
use std::io::SeekFrom;

// create a file and write data to it
let mut file = OpenOptions::new().create(true).open(&mut repo, "/foo.txt")?;
file.write_once(&[1, 2, 3, 4, 5, 6])?;

// read the first 2 bytes
let mut buf = [0; 2];
file.seek(SeekFrom::Start(0))?;
file.read_exact(&mut buf)?;
assert_eq!(&buf[..], &[1, 2]);

// create a new version, now the file content is [1, 2, 7, 8, 5, 6]
file.write_once(&[7, 8])?;

// notice that reading is on the latest version
file.seek(SeekFrom::Current(-2))?;
file.read_exact(&mut buf)?;
assert_eq!(&buf[..], &[7, 8]);

Read multiple versions using VersionReader.

use std::io::prelude::*;

// create a file and write 2 versions
let mut file = OpenOptions::new()
    .version_limit(4)
    .create(true)
    .open(&mut repo, "/foo.txt")?;
file.write_once(b"foo")?;
file.write_once(b"bar")?;

// get latest version number
let curr_ver = file.curr_version()?;

// create a version reader and read latest version of content
let mut rdr = file.version_reader(curr_ver)?;
let mut content = String::new();
rdr.read_to_string(&mut content)?;
assert_eq!(content, "foobar");

// create another version reader and read previous version of content
let mut rdr = file.version_reader(curr_ver - 1)?;
let mut content = String::new();
rdr.read_to_string(&mut content)?;
assert_eq!(content, "foo");

Methods

impl File

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

Queries metadata about the file.

pub fn history(&self) -> Result<Vec<Version>>

Returns a list of all the file content versions.

pub fn curr_version(&self) -> Result<usize>

Returns the current content version number.

pub fn version_reader(&self, ver_num: usize) -> Result<VersionReader>

Get a reader of the specified version.

The returned reader implements Read trait. To get the version number, first call history to get the list of all versions and then choose the version number from it.

pub fn finish(&mut self) -> Result<()>

Complete multi-part write to file and create a new version.

Errors

Calling this function without writing data before will return Error::NotWrite error.

pub fn write_once(&mut self, buf: &[u8]) -> Result<()>

Single-part write to file and create a new version.

This function provides a convenient way of combining Write and finish.

pub fn set_len(&mut self, len: usize) -> Result<()>

Truncates or extends the underlying file, create a new version of content which size to become size.

If the size is less than the current content size, then the new content will be shrunk. If it is greater than the current content size, then the content will be extended to size and have all of the intermediate data filled in with 0s.

Errors

This function will return an error if the file is not opened for writing or not finished writing.

Trait Implementations

impl Debug for File

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

Formats the value using the given formatter.

impl Read for File

fn read(&mut self, buf: &mut [u8]) -> Result<usize>

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

fn read_vectored(&mut self, bufs: &mut [IoSliceMut]) -> Result<usize, Error>

Like read, except that it reads into a slice of buffers.

unsafe fn initializer(&self) -> Initializer

🔬 This is a nightly-only experimental API. (read_initializer)

Determines if this Reader can work with buffers of uninitialized memory.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Read all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Read all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Read the exact number of bytes required to fill buf.

fn by_ref(&mut self) -> &mut Self

Creates a "by reference" adaptor for this instance of Read.

fn bytes(self) -> Bytes<Self>

Transforms this Read instance to an [Iterator] over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R> where
    R: Read, 

Creates an adaptor which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

Creates an adaptor which will read at most limit bytes from it.

impl Write for File

fn write(&mut self, buf: &[u8]) -> Result<usize>

Write a buffer into this writer, returning how many bytes were written.

fn flush(&mut self) -> Result<()>

Flush this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_vectored(&mut self, bufs: &[IoSlice]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this writer.

fn write_fmt(&mut self, fmt: Arguments) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

Creates a "by reference" adaptor for this instance of Write.

impl Seek for File

fn seek(&mut self, pos: SeekFrom) -> Result<u64>

Seek to an offset, in bytes, in a stream.

fn stream_len(&mut self) -> Result<u64, Error>

🔬 This is a nightly-only experimental API. (seek_convenience)

Returns the length of this stream (in bytes).

fn stream_position(&mut self) -> Result<u64, Error>

🔬 This is a nightly-only experimental API. (seek_convenience)

Returns the current seek position from the start of the stream.