[−][src]Struct zbox::File
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 10
, 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 recommendated.
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
usingWrite
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 callfinish
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; // 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().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
[src]
pub fn metadata(&self) -> Result<Metadata>
[src]
Queries metadata about the file.
pub fn history(&self) -> Result<Vec<Version>>
[src]
Returns a list of all the file content versions.
pub fn curr_version(&self) -> Result<usize>
[src]
Returns the current content version number.
pub fn version_reader(&self, ver_num: usize) -> Result<VersionReader>
[src]
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<()>
[src]
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<()>
[src]
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<()>
[src]
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
[src]
impl Write for File
[src]
fn write(&mut self, buf: &[u8]) -> Result<usize>
[src]
fn flush(&mut self) -> Result<()>
[src]
fn write_vectored(&mut self, bufs: &[IoSlice]) -> Result<usize, Error>
1.36.0[src]
Like write
, except that it writes from a slice of buffers. Read more
fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>
1.0.0[src]
Attempts to write an entire buffer into this writer. Read more
fn write_fmt(&mut self, fmt: Arguments) -> Result<(), Error>
1.0.0[src]
Writes a formatted string into this writer, returning any error encountered. Read more
fn by_ref(&mut self) -> &mut Self
1.0.0[src]
Creates a "by reference" adaptor for this instance of Write
. Read more
impl Seek for File
[src]
fn seek(&mut self, pos: SeekFrom) -> Result<u64>
[src]
fn stream_len(&mut self) -> Result<u64, Error>
[src]
seek_convenience
)Returns the length of this stream (in bytes). Read more
fn stream_position(&mut self) -> Result<u64, Error>
[src]
seek_convenience
)Returns the current seek position from the start of the stream. Read more
impl Read for File
[src]
fn read(&mut self, buf: &mut [u8]) -> Result<usize>
[src]
fn read_vectored(&mut self, bufs: &mut [IoSliceMut]) -> Result<usize, Error>
1.36.0[src]
Like read
, except that it reads into a slice of buffers. Read more
unsafe fn initializer(&self) -> Initializer
[src]
read_initializer
)Determines if this Read
er can work with buffers of uninitialized memory. Read more
fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>
1.0.0[src]
Read all bytes until EOF in this source, placing them into buf
. Read more
fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>
1.0.0[src]
Read all bytes until EOF in this source, appending them to buf
. Read more
fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>
1.6.0[src]
Read the exact number of bytes required to fill buf
. Read more
fn by_ref(&mut self) -> &mut Self
1.0.0[src]
Creates a "by reference" adaptor for this instance of Read
. Read more
fn bytes(self) -> Bytes<Self>
1.0.0[src]
Transforms this Read
instance to an [Iterator
] over its bytes. Read more
fn chain<R>(self, next: R) -> Chain<Self, R> where
R: Read,
1.0.0[src]
R: Read,
Creates an adaptor which will chain this stream with another. Read more
fn take(self, limit: u64) -> Take<Self>
1.0.0[src]
Creates an adaptor which will read at most limit
bytes from it. Read more
Auto Trait Implementations
Blanket Implementations
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,
type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
[src]
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<R> ReadBytesExt for R where
R: Read + ?Sized,
R: Read + ?Sized,
fn read_u8(&mut self) -> Result<u8, Error>
Reads an unsigned 8 bit integer from the underlying reader. Read more
fn read_i8(&mut self) -> Result<i8, Error>
Reads a signed 8 bit integer from the underlying reader. Read more
fn read_u16<T>(&mut self) -> Result<u16, Error> where
T: ByteOrder,
T: ByteOrder,
Reads an unsigned 16 bit integer from the underlying reader. Read more
fn read_i16<T>(&mut self) -> Result<i16, Error> where
T: ByteOrder,
T: ByteOrder,
Reads a signed 16 bit integer from the underlying reader. Read more
fn read_u24<T>(&mut self) -> Result<u32, Error> where
T: ByteOrder,
T: ByteOrder,
Reads an unsigned 24 bit integer from the underlying reader. Read more
fn read_i24<T>(&mut self) -> Result<i32, Error> where
T: ByteOrder,
T: ByteOrder,
Reads a signed 24 bit integer from the underlying reader. Read more
fn read_u32<T>(&mut self) -> Result<u32, Error> where
T: ByteOrder,
T: ByteOrder,
Reads an unsigned 32 bit integer from the underlying reader. Read more
fn read_i32<T>(&mut self) -> Result<i32, Error> where
T: ByteOrder,
T: ByteOrder,
Reads a signed 32 bit integer from the underlying reader. Read more
fn read_u48<T>(&mut self) -> Result<u64, Error> where
T: ByteOrder,
T: ByteOrder,
Reads an unsigned 48 bit integer from the underlying reader. Read more
fn read_i48<T>(&mut self) -> Result<i64, Error> where
T: ByteOrder,
T: ByteOrder,
Reads a signed 48 bit integer from the underlying reader. Read more
fn read_u64<T>(&mut self) -> Result<u64, Error> where
T: ByteOrder,
T: ByteOrder,
Reads an unsigned 64 bit integer from the underlying reader. Read more
fn read_i64<T>(&mut self) -> Result<i64, Error> where
T: ByteOrder,
T: ByteOrder,
Reads a signed 64 bit integer from the underlying reader. Read more
fn read_u128<T>(&mut self) -> Result<u128, Error> where
T: ByteOrder,
T: ByteOrder,
Reads an unsigned 128 bit integer from the underlying reader. Read more
fn read_i128<T>(&mut self) -> Result<i128, Error> where
T: ByteOrder,
T: ByteOrder,
Reads a signed 128 bit integer from the underlying reader. Read more
fn read_uint<T>(&mut self, nbytes: usize) -> Result<u64, Error> where
T: ByteOrder,
T: ByteOrder,
Reads an unsigned n-bytes integer from the underlying reader. Read more
fn read_int<T>(&mut self, nbytes: usize) -> Result<i64, Error> where
T: ByteOrder,
T: ByteOrder,
Reads a signed n-bytes integer from the underlying reader. Read more
fn read_uint128<T>(&mut self, nbytes: usize) -> Result<u128, Error> where
T: ByteOrder,
T: ByteOrder,
Reads an unsigned n-bytes integer from the underlying reader.
fn read_int128<T>(&mut self, nbytes: usize) -> Result<i128, Error> where
T: ByteOrder,
T: ByteOrder,
Reads a signed n-bytes integer from the underlying reader.
fn read_f32<T>(&mut self) -> Result<f32, Error> where
T: ByteOrder,
T: ByteOrder,
Reads a IEEE754 single-precision (4 bytes) floating point number from the underlying reader. Read more
fn read_f64<T>(&mut self) -> Result<f64, Error> where
T: ByteOrder,
T: ByteOrder,
Reads a IEEE754 double-precision (8 bytes) floating point number from the underlying reader. Read more
fn read_u16_into<T>(&mut self, dst: &mut [u16]) -> Result<(), Error> where
T: ByteOrder,
T: ByteOrder,
Reads a sequence of unsigned 16 bit integers from the underlying reader. Read more
fn read_u32_into<T>(&mut self, dst: &mut [u32]) -> Result<(), Error> where
T: ByteOrder,
T: ByteOrder,
Reads a sequence of unsigned 32 bit integers from the underlying reader. Read more
fn read_u64_into<T>(&mut self, dst: &mut [u64]) -> Result<(), Error> where
T: ByteOrder,
T: ByteOrder,
Reads a sequence of unsigned 64 bit integers from the underlying reader. Read more
fn read_u128_into<T>(&mut self, dst: &mut [u128]) -> Result<(), Error> where
T: ByteOrder,
T: ByteOrder,
Reads a sequence of unsigned 128 bit integers from the underlying reader. Read more
fn read_i16_into<T>(&mut self, dst: &mut [i16]) -> Result<(), Error> where
T: ByteOrder,
T: ByteOrder,
Reads a sequence of signed 16 bit integers from the underlying reader. Read more
fn read_i32_into<T>(&mut self, dst: &mut [i32]) -> Result<(), Error> where
T: ByteOrder,
T: ByteOrder,
Reads a sequence of signed 32 bit integers from the underlying reader. Read more
fn read_i64_into<T>(&mut self, dst: &mut [i64]) -> Result<(), Error> where
T: ByteOrder,
T: ByteOrder,
Reads a sequence of signed 64 bit integers from the underlying reader. Read more
fn read_i128_into<T>(&mut self, dst: &mut [i128]) -> Result<(), Error> where
T: ByteOrder,
T: ByteOrder,
Reads a sequence of signed 128 bit integers from the underlying reader. Read more
fn read_f32_into<T>(&mut self, dst: &mut [f32]) -> Result<(), Error> where
T: ByteOrder,
T: ByteOrder,
Reads a sequence of IEEE754 single-precision (4 bytes) floating point numbers from the underlying reader. Read more
fn read_f32_into_unchecked<T>(&mut self, dst: &mut [f32]) -> Result<(), Error> where
T: ByteOrder,
T: ByteOrder,
please use read_f32_into
instead
DEPRECATED. Read more
fn read_f64_into<T>(&mut self, dst: &mut [f64]) -> Result<(), Error> where
T: ByteOrder,
T: ByteOrder,
Reads a sequence of IEEE754 double-precision (8 bytes) floating point numbers from the underlying reader. Read more
fn read_f64_into_unchecked<T>(&mut self, dst: &mut [f64]) -> Result<(), Error> where
T: ByteOrder,
T: ByteOrder,
please use read_f64_into
instead
DEPRECATED. Read more
impl<W> WriteBytesExt for W where
W: Write + ?Sized,
W: Write + ?Sized,
fn write_u8(&mut self, n: u8) -> Result<(), Error>
Writes an unsigned 8 bit integer to the underlying writer. Read more
fn write_i8(&mut self, n: i8) -> Result<(), Error>
Writes a signed 8 bit integer to the underlying writer. Read more
fn write_u16<T>(&mut self, n: u16) -> Result<(), Error> where
T: ByteOrder,
T: ByteOrder,
Writes an unsigned 16 bit integer to the underlying writer. Read more
fn write_i16<T>(&mut self, n: i16) -> Result<(), Error> where
T: ByteOrder,
T: ByteOrder,
Writes a signed 16 bit integer to the underlying writer. Read more
fn write_u24<T>(&mut self, n: u32) -> Result<(), Error> where
T: ByteOrder,
T: ByteOrder,
Writes an unsigned 24 bit integer to the underlying writer. Read more
fn write_i24<T>(&mut self, n: i32) -> Result<(), Error> where
T: ByteOrder,
T: ByteOrder,
Writes a signed 24 bit integer to the underlying writer. Read more
fn write_u32<T>(&mut self, n: u32) -> Result<(), Error> where
T: ByteOrder,
T: ByteOrder,
Writes an unsigned 32 bit integer to the underlying writer. Read more
fn write_i32<T>(&mut self, n: i32) -> Result<(), Error> where
T: ByteOrder,
T: ByteOrder,
Writes a signed 32 bit integer to the underlying writer. Read more
fn write_u48<T>(&mut self, n: u64) -> Result<(), Error> where
T: ByteOrder,
T: ByteOrder,
Writes an unsigned 48 bit integer to the underlying writer. Read more
fn write_i48<T>(&mut self, n: i64) -> Result<(), Error> where
T: ByteOrder,
T: ByteOrder,
Writes a signed 48 bit integer to the underlying writer. Read more
fn write_u64<T>(&mut self, n: u64) -> Result<(), Error> where
T: ByteOrder,
T: ByteOrder,
Writes an unsigned 64 bit integer to the underlying writer. Read more
fn write_i64<T>(&mut self, n: i64) -> Result<(), Error> where
T: ByteOrder,
T: ByteOrder,
Writes a signed 64 bit integer to the underlying writer. Read more
fn write_u128<T>(&mut self, n: u128) -> Result<(), Error> where
T: ByteOrder,
T: ByteOrder,
Writes an unsigned 128 bit integer to the underlying writer.
fn write_i128<T>(&mut self, n: i128) -> Result<(), Error> where
T: ByteOrder,
T: ByteOrder,
Writes a signed 128 bit integer to the underlying writer.
fn write_uint<T>(&mut self, n: u64, nbytes: usize) -> Result<(), Error> where
T: ByteOrder,
T: ByteOrder,
Writes an unsigned n-bytes integer to the underlying writer. Read more
fn write_int<T>(&mut self, n: i64, nbytes: usize) -> Result<(), Error> where
T: ByteOrder,
T: ByteOrder,
Writes a signed n-bytes integer to the underlying writer. Read more
fn write_uint128<T>(&mut self, n: u128, nbytes: usize) -> Result<(), Error> where
T: ByteOrder,
T: ByteOrder,
Writes an unsigned n-bytes integer to the underlying writer. Read more
fn write_int128<T>(&mut self, n: i128, nbytes: usize) -> Result<(), Error> where
T: ByteOrder,
T: ByteOrder,
Writes a signed n-bytes integer to the underlying writer. Read more
fn write_f32<T>(&mut self, n: f32) -> Result<(), Error> where
T: ByteOrder,
T: ByteOrder,
Writes a IEEE754 single-precision (4 bytes) floating point number to the underlying writer. Read more
fn write_f64<T>(&mut self, n: f64) -> Result<(), Error> where
T: ByteOrder,
T: ByteOrder,
Writes a IEEE754 double-precision (8 bytes) floating point number to the underlying writer. Read more