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 to a file:

• 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::*;
  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 binded 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 binded to latest content version.

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

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::*;

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()?;

// create a version reader and read its 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 its 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 underlying 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>

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.

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

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

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 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, appending them to buf.

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

Read the exact number of bytes required to fill buf.

Important traits for &'a mut R

impl<'a, R> Read for &'a mut R where
    R: Read + ?Sized, impl<'a, W> Write for &'a mut W where
    W: Write + ?Sized, impl<'a, I> Iterator for &'a mut I where
    I: Iterator + ?Sized,  type Item = <I as Iterator>::Item;

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

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

Important traits for Bytes<R>

impl<R> Iterator for Bytes<R> where
    R: Read,  type Item = Result<u8, Error>;

fn bytes(self) -> Bytes<Self>

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

Important traits for Chars<R>

impl<R> Iterator for Chars<R> where
    R: Read,  type Item = Result<char, CharsError>;

fn chars(self) -> Chars<Self>

Deprecated since 1.27.0

: Use str::from_utf8 instead: https://doc.rust-lang.org/nightly/std/str/struct.Utf8Error.html#examples

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

Important traits for Chain<T, U>

impl<T, U> Read for Chain<T, U> where
    T: Read,
    U: Read, 

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

Creates an adaptor which will chain this stream with another.

Important traits for Take<T>

impl<T> Read for Take<T> where
    T: Read, 

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.

Important traits for &'a mut R

impl<'a, R> Read for &'a mut R where
    R: Read + ?Sized, impl<'a, W> Write for &'a mut W where
    W: Write + ?Sized, impl<'a, I> Iterator for &'a mut I where
    I: Iterator + ?Sized,  type Item = <I as Iterator>::Item;

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.