Trait read_collection::ReadBack

pub trait ReadBack {
    // Required method
    fn read_back(&mut self, buf: &mut [u8]) -> Result<usize>;

    // Provided methods
    fn read_back_vectored(
        &mut self,
        bufs: &mut [IoSliceMut<'_>],
    ) -> Result<usize> { ... }
    fn read_back_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize> { ... }
    fn read_back_to_string(&mut self, buf: &mut String) -> Result<usize> { ... }
    fn read_back_exact(&mut self, buf: &mut [u8]) -> Result<()> { ... }
    fn read_back_bytes(self) -> ReadBackBytes<Self> 
       where Self: Sized { ... }
    fn read_back_chain<R: ReadBack>(self, next: R) -> ReadBackChain<Self, R>
       where Self: Sized { ... }
    fn read_back_take(self, limit: u64) -> ReadBackTake<Self>
       where Self: Sized { ... }
}

A trait to read back the content which has been read with the methods of std::io::Read.

Example

use read_collection::ReadBack;
use std::io::Read;
use std::fs::File;

fn main() {
    let mut file = File::open("some/path").unwrap();
    let mut read_buffer: [u8; 10] = [0; 10];
    let mut read_back_buffer: [u8; 10] = [0; 10];

    // well, let's read some stuff!
    file.read(&mut read_buffer).unwrap();

    // do some work and somehow clear the `read_buffer`
    // ....

    // why not read it again?
    file.read_back(&mut read_back_buffer).unwrap();

    assert_eq!(read_buffer, read_back_buffer);
}

Required Methods

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

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

The same conditions have to be met as in Read::read. The difference to Read::read is that read_back is reading “backwards”.

Example

use read_collection::ReadBack;

fn main() {
    let data = [1u8, 2u8];
    let mut buffer: [u8; 3] = [0; 3];
    let mut small_buffer: [u8; 1] = [0];

    assert_eq!(data.as_slice().read_back(&mut buffer).ok(), Some(2));
    assert_eq!(data.as_slice().read_back(&mut small_buffer).ok(), Some(1));

    // notice here, that the values are added at the beginning of the array!
    assert_eq!(&buffer, &[1, 2, 0]);

    // notice here that the last value of data gets inserted "first"
    assert_eq!(&small_buffer, &[2]);
}

Provided Methods

fn read_back_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize>

Like Read::read_vectored but it uses rev_read instead of read.

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

Read all bytes until the start of the source, placing them into buf.

Can be also seen as “read back until you reach the start of the source”.

Example

use std::fs::File;
use std::io::Read;
use read_collection::ReadBack;

fn main() {
    let mut file = File::open("some/path").unwrap();
    let mut buffer: Vec<u8> = vec![0; 100];

    // do some arbitrary read...
    file.read(&mut buffer).unwrap();

    // do some even *more* random read...
    // ...

    // well, why not collecting *everything* from the start to
    // the cursor position?
    file.read_back_to_end(&mut buffer).unwrap();
}

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

Read all bytes until the start of the source, prepending them to buf (since we’re reading back).

Example

use read_collection::ReadBack;

fn main() {
    let mut message = "Arch btw.".to_string();
    let prefix = b"I use ";

    assert_eq!(prefix.as_slice().read_back_to_string(&mut message).ok(), Some(prefix.len()));
    assert_eq!(message, "I use Arch btw.".to_string());
}

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

Read back the exact number of bytes required to fill buf.

The conditions for Read::read_exact apply here as well.

Example

use read_collection::ReadBack;

fn main() {
    let values = [1, 2, 3];
    let mut buffer = [0, 0];

    assert!(values.as_slice().read_back_exact(&mut buffer).is_ok());
    assert_eq!(buffer, [2, 3]);
}

fn read_back_bytes(self) -> ReadBackBytes<Self>

where Self: Sized,

Transforms this ReadBack instance to an Iterator over its bytes. This can be also seen as “read the bytes of the instance in reverse”.

The same conditions of Read::bytes apply here as well.

Example

use read_collection::ReadBack;

fn main() {
    let data = [1, 2, 3];

    let mut iterator = data.as_slice().read_back_bytes();
    let read_back_bytes = iterator
        .map(|b| b.unwrap())
        .collect::<Vec<u8>>();

    assert_eq!(read_back_bytes, [3, 2, 1].to_vec());
}

fn read_back_chain<R: ReadBack>(self, next: R) -> ReadBackChain<Self, R>

where Self: Sized,

Creates an adapter which will chain this stream with another.

Example

use read_collection::ReadBack;

fn main() {
    let first_data = b"First in the chain.";
    let second_data = b" Second in the chain.";
    let total_length = first_data.len() + second_data.len();
    let mut buffer: Vec<u8> = vec![0; total_length];

    let mut chain = first_data.read_back_chain(second_data.as_slice());

    assert_eq!(chain.read_back(&mut buffer).ok(), Some(first_data.len()));
    assert_eq!(chain.read_back(&mut buffer[first_data.len()..]).ok(), Some(second_data.len()));

    assert_eq!(String::from_utf8(buffer).unwrap(), "First in the chain. Second in the chain.".to_string());
}

fn read_back_take(self, limit: u64) -> ReadBackTake<Self>

where Self: Sized,

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

Example

use read_collection::ReadBack;

fn main() {
    let data: [u8; 3] = [1, 2, 3];
    let mut buffer: [u8; 3] = [0; 3];

    let mut take = data.as_slice().read_back_take(2);

    assert_eq!(take.read_back(&mut buffer).ok(), Some(2));
    // we've already read 2, so we reached the limit
    assert_eq!(take.read_back(&mut buffer).ok(), Some(0));

    assert_eq!(buffer, [2, 3, 0]);
}

Implementations on Foreign Types

impl ReadBack for &File

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

impl ReadBack for &[u8]

As for the Read implementation of &[u8], bytes get copied from the slice.

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

fn read_back_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize>

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

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

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

impl ReadBack for File

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

impl ReadBack for Empty

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

impl<R: ReadBack> ReadBack for &mut R

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

fn read_back_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize>

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

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

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

impl<R: ReadBack> ReadBack for Box<R>

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

fn read_back_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize>

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

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

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

Implementors

impl<R: ReadBack> ReadBack for BufReadBacker<R>

impl<T: ReadBack, U: ReadBack> ReadBack for ReadBackChain<T, U>