Trait buffered_reader::BufferedReader

source · 
pub trait BufferedReader<C>: Read + Debug + Display {

Show 19 methods    fn buffer(&self) -> &[u8]ⓘNotable traits for &mut [u8]impl Write for &mut [u8]impl Read for &[u8];
    fn data(&mut self, amount: usize) -> Result<&[u8], Error>;
    fn consume(&mut self, amount: usize) -> &[u8]ⓘNotable traits for &mut [u8]impl Write for &mut [u8]impl Read for &[u8];
    fn into_inner<'a>(
        self: Box<Self>
    ) -> Option<Box<dyn BufferedReader<C> + 'a>>
    where
        Self: 'a;
    fn get_mut(&mut self) -> Option<&mut dyn BufferedReader<C>>;
    fn get_ref(&self) -> Option<&dyn BufferedReader<C>>;
    fn cookie_set(&mut self, cookie: C) -> C;
    fn cookie_ref(&self) -> &C;
    fn cookie_mut(&mut self) -> &mut C;

    fn data_hard(&mut self, amount: usize) -> Result<&[u8], Error> { ... }
    fn data_eof(&mut self) -> Result<&[u8], Error> { ... }
    fn data_consume(&mut self, amount: usize) -> Result<&[u8], Error> { ... }
    fn data_consume_hard(&mut self, amount: usize) -> Result<&[u8], Error> { ... }
    fn read_be_u16(&mut self) -> Result<u16, Error> { ... }
    fn read_be_u32(&mut self) -> Result<u32, Error> { ... }
    fn read_to(&mut self, terminal: u8) -> Result<&[u8], Error> { ... }
    fn steal(&mut self, amount: usize) -> Result<Vec<u8>, Error> { ... }
    fn steal_eof(&mut self) -> Result<Vec<u8>, Error> { ... }
    fn drop_eof(&mut self) -> Result<bool, Error> { ... }

}
Expand description

The generic BufferReader interface.

Required Methods

Returns a reference to the internal buffer.

Note: this returns the same data as self.data(0), but it does so without mutably borrowing self:

use buffered_reader::*;
use buffered_reader::BufferedReaderMemory;

let mut br = BufferedReaderMemory::new(&b"0123456789"[..]);

let first = br.data(10)?.len();
let second = br.buffer().len();
// `buffer` must return exactly what `data` returned.
assert_eq!(first, second);

Ensures that the internal buffer has at least amount bytes of data, and returns it.

If the internal buffer contains less than amount bytes of data, the internal buffer is first filled.

The returned slice will have at least amount bytes unless EOF has been reached or an error occurs, in which case the returned slice will contain the rest of the file.

If an error occurs, it is not discarded, but saved. It is returned when data (or a related function) is called and the internal buffer is empty.

This function does not advance the cursor. To advance the cursor, use consume().

Note: If the internal buffer already contains at least amount bytes of data, then BufferedReader implementations are guaranteed to simply return the internal buffer. As such, multiple calls to data for the same amount will return the same slice.

Further, BufferedReader implementations are guaranteed to not shrink the internal buffer. Thus, once some data has been returned, it will always be returned until it is consumed. As such, the following must hold:

If BufferedReader receives EINTR when reading, it will automatically retry reading.

use buffered_reader::*;
use buffered_reader::BufferedReaderMemory;

let mut br = BufferedReaderMemory::new(&b"0123456789"[..]);

let first = br.data(10)?.len();
let second = br.data(5)?.len();
// Even though less data is requested, the second call must
// return the same slice as the first call.
assert_eq!(first, second);

Consumes some of the data.

This advances the internal cursor by amount. It is an error to call this function to consume data that hasn’t been returned by data() or a related function.

Note: It is safe to call this function to consume more data than requested in a previous call to data(), but only if data() also returned that data.

This function returns the internal buffer including the consumed data. Thus, the BufferedReader implementation must continue to buffer the consumed data until the reference goes out of scope.

Examples
use buffered_reader::*;
use buffered_reader::BufferedReaderGeneric;

const AMOUNT : usize = 100 * 1024 * 1024;
let buffer = vec![0u8; AMOUNT];
let mut br = BufferedReaderGeneric::new(&buffer[..], None);

let amount = {
    // We want at least 1024 bytes, but we'll be happy with
    // more or less.
    let buffer = br.data(1024)?;
    // Parse the data or something.
    let used = buffer.len();
    used
};
let buffer = br.consume(amount);

Returns the underlying reader, if any.

To allow this to work with BufferedReader traits, it is necessary for Self to be boxed.

This can lead to the following unusual code:

let inner = Box::new(br).into_inner();

Returns a mutable reference to the inner BufferedReader, if any.

It is a very bad idea to read any data from the inner BufferedReader, because this BufferedReader may have some data buffered. However, this function can be useful to get the cookie.

Returns a reference to the inner BufferedReader, if any.

Sets the BufferedReader’s cookie and returns the old value.

Returns a reference to the BufferedReader’s cookie.

Returns a mutable reference to the BufferedReader’s cookie.

Provided Methods

Like data(), but returns an error if there is not at least amount bytes available.

data_hard() is a variant of data() that returns at least amount bytes of data or an error. Thus, unlike data(), which will return less than amount bytes of data if EOF is encountered, data_hard() returns an error, specifically, io::ErrorKind::UnexpectedEof.

Examples
use buffered_reader::*;
use buffered_reader::BufferedReaderMemory;

let mut br = BufferedReaderMemory::new(&b"0123456789"[..]);

// Trying to read more than there is available results in an error.
assert!(br.data_hard(20).is_err());
// Whereas with data(), everything through EOF is returned.
assert_eq!(br.data(20)?.len(), 10);

Returns all of the data until EOF. Like data(), this does not actually consume the data that is read.

In general, you shouldn’t use this function as it can cause an enormous amount of buffering. But, if you know that the amount of data is limited, this is acceptable.

Examples
use buffered_reader::*;
use buffered_reader::BufferedReaderGeneric;

const AMOUNT : usize = 100 * 1024 * 1024;
let buffer = vec![0u8; AMOUNT];
let mut br = BufferedReaderGeneric::new(&buffer[..], None);

// Normally, only a small amount will be buffered.
assert!(br.data(10)?.len() <= AMOUNT);

// `data_eof` buffers everything.
assert_eq!(br.data_eof()?.len(), AMOUNT);

// Now that everything is buffered, buffer(), data(), and
// data_hard() will also return everything.
assert_eq!(br.buffer().len(), AMOUNT);
assert_eq!(br.data(10)?.len(), AMOUNT);
assert_eq!(br.data_hard(10)?.len(), AMOUNT);

A convenience function that combines data() and consume().

If less than amount bytes are available, this function consumes what is available.

Note: Due to lifetime issues, it is not possible to call data(), work with the returned buffer, and then call consume() in the same scope, because both data() and consume() take a mutable reference to the BufferedReader. This function makes this common pattern easier.

Examples
use buffered_reader::*;
use buffered_reader::BufferedReaderMemory;

let orig = b"0123456789";
let mut br = BufferedReaderMemory::new(&orig[..]);

// We need a new scope for each call to `data_consume()`, because
// the `buffer` reference locks `br`.
{
    let buffer = br.data_consume(3)?;
    assert_eq!(buffer, &orig[..buffer.len()]);
}

// Note that the cursor has advanced.
{
    let buffer = br.data_consume(3)?;
    assert_eq!(buffer, &orig[3..3 + buffer.len()]);
}

// Like `data()`, `data_consume()` may return and consume less
// than request if there is no more data available.
{
    let buffer = br.data_consume(10)?;
    assert_eq!(buffer, &orig[6..6 + buffer.len()]);
}

{
    let buffer = br.data_consume(10)?;
    assert_eq!(buffer.len(), 0);
}

A convenience function that effectively combines data_hard() and consume().

This function is identical to data_consume(), but internally uses data_hard() instead of data().

A convenience function for reading a 16-bit unsigned integer in big endian format.

A convenience function for reading a 32-bit unsigned integer in big endian format.

Reads until either terminal is encountered or EOF.

Returns either a &[u8] terminating in terminal or the rest of the data, if EOF was encountered.

Note: this function does not consume the data.

Examples
use buffered_reader::*;
use buffered_reader::BufferedReaderMemory;

let orig = b"0123456789";
let mut br = BufferedReaderMemory::new(&orig[..]);

{
    let s = br.read_to(b'3')?;
    assert_eq!(s, b"0123");
}

// `read_to()` doesn't consume the data.
{
    let s = br.read_to(b'5')?;
    assert_eq!(s, b"012345");
}

// Even if there is more data in the internal buffer, only
// the data through the match is returned.
{
    let s = br.read_to(b'1')?;
    assert_eq!(s, b"01");
}

// If the terminal is not found, everything is returned...
{
    let s = br.read_to(b'A')?;
    assert_eq!(s, orig);
}

// If we consume some data, the search starts at the cursor,
// not the beginning of the file.
br.consume(3);

{
    let s = br.read_to(b'5')?;
    assert_eq!(s, b"345");
}

Like data_consume_hard(), but returns the data in a caller-owned buffer.

BufferedReader implementations may optimize this to avoid a copy by directly returning the internal buffer.

Like steal(), but instead of stealing a fixed number of bytes, steals all of the data until the end of file.

Like steal_eof(), but instead of returning the data, the data is discarded.

On success, returns whether any data (i.e., at least one byte) was discarded.

Note: whereas steal_eof() needs to buffer all of the data, this function reads the data a chunk at a time, and then discards it. A consequence of this is that an error may occur after we have consumed some of the data.

Trait Implementations

Make a Box<BufferedReader> look like a BufferedReader.

Returns a reference to the internal buffer. Read more
Ensures that the internal buffer has at least amount bytes of data, and returns it. Read more
Like data(), but returns an error if there is not at least amount bytes available. Read more
Returns all of the data until EOF. Like data(), this does not actually consume the data that is read. Read more
Consumes some of the data. Read more
A convenience function that combines data() and consume(). Read more
A convenience function that effectively combines data_hard() and consume(). Read more
A convenience function for reading a 16-bit unsigned integer in big endian format. Read more
A convenience function for reading a 32-bit unsigned integer in big endian format. Read more
Reads until either terminal is encountered or EOF. Read more
Like data_consume_hard(), but returns the data in a caller-owned buffer. Read more
Like steal(), but instead of stealing a fixed number of bytes, steals all of the data until the end of file. Read more
Like steal_eof(), but instead of returning the data, the data is discarded. Read more
Returns a mutable reference to the inner BufferedReader, if any. Read more
Returns a reference to the inner BufferedReader, if any.
Returns the underlying reader, if any. Read more
Sets the BufferedReader’s cookie and returns the old value.
Returns a reference to the BufferedReader’s cookie.
Returns a mutable reference to the BufferedReader’s cookie.

Implementations on Foreign Types

Make a Box<BufferedReader> look like a BufferedReader.

Implementors