Struct SpareBuffer 

pub struct SpareBuffer<'a, T>
where
    T: Primitive,
{ /* private fields */ }

A wrapper around Vec<T> that provides access to the “spare” capacity of the vector as a &mut[T] slice.

See module level documentation for more information.

Implementations

impl<'a, T> SpareBuffer<'a, T>

where T: Primitive,

pub fn from(buffer: &'a mut Vec<T>, limit: Option<NonZeroUsize>) -> Self

Creates a new SpareBuffer from an existing vector.

An optional limit for the length of the vector can be specified. The commit() fails, if it would exceed this limit.

Examples found in repository

examples/fill_buffer.rs (line 11)

fn main() {
    let mut vec: Vec<u8> = Vec::with_capacity(128);
    let mut buffer = SpareBuffer::from(&mut vec, None);
    
    let spare = buffer.allocate_spare(NonZeroUsize::new(100).unwrap());
    for i in 0..50 {
        spare[i] = i as u8;
    }

    // Whoops: only &spare[0..50] was initialized, but 100 elements are committed!
    buffer.commit(100).expect("Failed to commit!");

    println!("Expect valid numbers:");
    println!("{:?}\n", &vec[..50]);

    println!("Expect \"unspecified\" garbage:");
    println!("{:?}\n", &vec[50..]);
}

examples/read_file.rs (line 13)

fn main() {
    let mut vec: Vec<u8> = Vec::with_capacity(1048576);
    let mut buffer = SpareBuffer::from(&mut vec, NonZeroUsize::new(10485760));
    
    let chunk_size = NonZeroUsize::new(4096).unwrap();
    let mut file = File::open("input.dat").expect("Failed to open input file!");

    loop {
        let spare = buffer.allocate_spare(chunk_size);
        let count = file.read(spare).expect("File read error encountered!");
        if count > 0 {
            buffer.commit(count).expect("Failed to commit!");
        } else {
            break; /* EOF*/
        }
    }

    println!("Length: {:?}", vec.len());
}

pub fn len(&self) -> usize

Returns the number of “committed” elements in the underlying vector. This is equivalent to Vec::len().

pub fn is_empty(&self) -> bool

Returns true if the underlying vector contains no “committed” elements. This is equivalent to Vec::is_empty().

pub fn limit(&self) -> Option<NonZeroUsize>

Returns the length limit, if a limit has been specified. Otherwise None is returned.

pub fn data(&self) -> &[T]

Returns a &[T] slice of all “committed” elements in the underlying vector. This is equivalent to Vec::as_slice().

pub fn allocate_spare(&mut self, length: NonZeroUsize) -> &mut [T]

Allocates a “spare” buffer of the specified length.

Reserves capacity for at least length additional elements in the underlying vector. May reserve more space to speculatively avoid frequent reallocations. Does nothing, if the unused “spare” capacity of the underlying vector is already sufficient.

Returns a &mut[T] slice which allows the caller to access the allocated “spare” buffer. No guarantees are provided about the initial contents of the buffer! It is recommended that the caller only writes data to the slice instead of reading its contents.

The returned &mut[T] slice can be passed to Read::read() or similar I/O routines.

The “spare” buffer is not considered to be a valid part of the underlying vector, until the commit() function is called eventually.

Examples found in repository

examples/fill_buffer.rs (line 13)

fn main() {
    let mut vec: Vec<u8> = Vec::with_capacity(128);
    let mut buffer = SpareBuffer::from(&mut vec, None);
    
    let spare = buffer.allocate_spare(NonZeroUsize::new(100).unwrap());
    for i in 0..50 {
        spare[i] = i as u8;
    }

    // Whoops: only &spare[0..50] was initialized, but 100 elements are committed!
    buffer.commit(100).expect("Failed to commit!");

    println!("Expect valid numbers:");
    println!("{:?}\n", &vec[..50]);

    println!("Expect \"unspecified\" garbage:");
    println!("{:?}\n", &vec[50..]);
}

examples/read_file.rs (line 19)

fn main() {
    let mut vec: Vec<u8> = Vec::with_capacity(1048576);
    let mut buffer = SpareBuffer::from(&mut vec, NonZeroUsize::new(10485760));
    
    let chunk_size = NonZeroUsize::new(4096).unwrap();
    let mut file = File::open("input.dat").expect("Failed to open input file!");

    loop {
        let spare = buffer.allocate_spare(chunk_size);
        let count = file.read(spare).expect("File read error encountered!");
        if count > 0 {
            buffer.commit(count).expect("Failed to commit!");
        } else {
            break; /* EOF*/
        }
    }

    println!("Length: {:?}", vec.len());
}

pub fn commit(&mut self, additional: usize) -> IoResult<()>

Commits the first additional elements of the “spare” buffer.

The underlying vector is extended into the previously allocated “spare” buffer, by increasing its length, so that the first additional elements in the “spare” buffer effectively are appended to the vector without copying the data.

All elements to be committed fom the “spare” buffer must have been initialized, i.e. the whole of &spare[0..additional] must have been filled with valid data. Otherwise, the contents of the underlying vector are unspecified after the commit 😨

This function always invalidates the current “spare” buffer. A new “spare” buffer must be allocated in order to append more data!

Errors

If a length limit has been specified, then this function will fail, if adding additional more elements to the underlying vector would cause its total length to exceed the specified limit. Otherwise, the function always returns Ok(()).

Panics

Panics if additional is greater than the available “spare” capacity, or if no “spare” buffer was allocated before!

A panic may also occur, if the new length would overflow usize::MAX.

Examples found in repository

examples/fill_buffer.rs (line 19)

fn main() {
    let mut vec: Vec<u8> = Vec::with_capacity(128);
    let mut buffer = SpareBuffer::from(&mut vec, None);
    
    let spare = buffer.allocate_spare(NonZeroUsize::new(100).unwrap());
    for i in 0..50 {
        spare[i] = i as u8;
    }

    // Whoops: only &spare[0..50] was initialized, but 100 elements are committed!
    buffer.commit(100).expect("Failed to commit!");

    println!("Expect valid numbers:");
    println!("{:?}\n", &vec[..50]);

    println!("Expect \"unspecified\" garbage:");
    println!("{:?}\n", &vec[50..]);
}

examples/read_file.rs (line 22)

fn main() {
    let mut vec: Vec<u8> = Vec::with_capacity(1048576);
    let mut buffer = SpareBuffer::from(&mut vec, NonZeroUsize::new(10485760));
    
    let chunk_size = NonZeroUsize::new(4096).unwrap();
    let mut file = File::open("input.dat").expect("Failed to open input file!");

    loop {
        let spare = buffer.allocate_spare(chunk_size);
        let count = file.read(spare).expect("File read error encountered!");
        if count > 0 {
            buffer.commit(count).expect("Failed to commit!");
        } else {
            break; /* EOF*/
        }
    }

    println!("Length: {:?}", vec.len());
}

pub unsafe fn commit_unchecked(&mut self, additional: usize)

The same as commit() but without any checks.

This function is unsafe, for obvious reasons, and therefore should be used with great care!