Struct zbox::File

pub struct File { /* fields omitted */ }

A reference to an open 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 Zbox 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 10, which is configurable by version_limit. 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 recommendated.

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

• Multi-part Write

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

  Examples

  use std::io::prelude::*;
  
  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.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;
  
  let mut file = OpenOptions::new().create(true).open(&mut repo, "/foo.txt")?;
  file.write_once(b"foo bar")?;
  
  let mut content = String::new();
  file.read_to_string(&mut content)?;
  assert_eq!(content, "foo bar");
  

Reading

As File contains multiple versions, Read operation must be associated with a version. By default, the latest version is binded for reading. To read a specific version, a VersionReader, which supports Read trait, can be used.

File internally maintain a reader, which will be opened for current version when it is used at first time. Once the reader is opened, subsequent write operations have no effect on it. So be carefull when doing both reading and writing at the same time.

Examples

Read multiple versions using VersionReader.

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

let mut file = OpenOptions::new().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();

let mut rdr = file.version_reader(curr_ver)?;
let mut content = String::new();
rdr.read_to_string(&mut content)?;
assert_eq!(content, "bar");

let mut rdr = file.version_reader(curr_ver - 1)?;
let mut content = String::new();
rdr.read_to_string(&mut content)?;
assert_eq!(content, "foo");

Read the file content while it is in writing, notice that the read is not affected by the following write.

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

let mut file = OpenOptions::new().create(true).open(&mut repo, "/foo.txt")?;
file.write_once(&[1, 2, 3, 4])?;

let mut buf = [0; 2];
file.read_exact(&mut buf)?;
assert_eq!(&buf[..], &[1, 2]);

// create a new version
file.write_once(&[5, 6, 7])?;

// notice this read still continues on previous version
file.read_exact(&mut buf)?;
assert_eq!(&buf[..], &[3, 4]);

Methods

impl File

fn metadata(&self) -> Metadata

Queries metadata about the underlying file.

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

Returns a list of all the file content versions.

fn curr_version(&self) -> usize

Returns the current content version number.

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

Return reader of specified version.

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

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

Complete multi-part write to create a new version.

Errors

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

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

Single-part write to create a new version.

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

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 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.

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, placing them into 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 chars(self) -> Chars<Self>

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

the semantics of a partial read/write of where errors happen is currently unclear and may change

Transforms this Read instance to an [Iterator] over [char]s.

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 object, 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_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this write.

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.

impl Debug for File

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

Formats the value using the given formatter.