Trait buffered_reader::BufferedReader[−][src]

pub trait BufferedReader<C>: Read + Debug + Display + Send + Sync where
    C: Debug + Send + Sync, {

Show 25 methods    fn buffer(&self) -> &[u8];

    fn data(&mut self, amount: usize) -> Result<&[u8], Error>;

    fn consume(&mut self, amount: usize) -> &[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 eof(&mut self) -> bool { ... }

    fn consummated(&mut self) -> bool { ... }

    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 drop_until(&mut self, terminals: &[u8]) -> Result<usize, Error> { ... }

    fn drop_through(
        &mut self, 
        terminals: &[u8], 
        match_eof: bool
    ) -> Result<(Option<u8>, usize), 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> { ... }

    fn dump(&self, sink: &mut dyn Write) -> Result<()>
    where
        Self: Sized,
    { ... }

    fn as_boxed<'a>(self) -> Box<dyn BufferedReader<C> + 'a>
    where
        Self: 'a + Sized,
    { ... }

}
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::BufferedReader;

let mut br = buffered_reader::Memory::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.

Errors are returned only when 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::BufferedReader;

let mut br = buffered_reader::Memory::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::BufferedReader;

const AMOUNT : usize = 100 * 1024 * 1024;
let buffer = vec![0u8; AMOUNT];
let mut br = buffered_reader::Generic::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::BufferedReader;

let mut br = buffered_reader::Memory::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::BufferedReader;

const AMOUNT : usize = 100 * 1024 * 1024;
let buffer = vec![0u8; AMOUNT];
let mut br = buffered_reader::Generic::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::BufferedReader;

let orig = b"0123456789";
let mut br = buffered_reader::Memory::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 requested 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().

Checks whether the end of the stream is reached.

Checks whether this reader is consummated.

For most readers, this function will return true once the end of the stream is reached. However, some readers are concerned with packet framing (e.g. the Limitor). Those readers consider themselves consummated if the amount of data indicated by the packet frame is consumed.

This allows us to detect truncation. A packet is truncated, iff the end of the stream is reached, but the reader is not consummated.

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

let orig = b"0123456789";
let mut br = buffered_reader::Memory::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");
}

Discards the input until one of the bytes in terminals is encountered.

The matching byte is not discarded.

Returns the number of bytes discarded.

The end of file is considered a match.

terminals must be sorted.

Discards the input until one of the bytes in terminals is encountered.

The matching byte is also discarded.

Returns the terminal byte and the number of bytes discarded.

If match_eof is true, then the end of file is considered a match. Otherwise, if the end of file is encountered, an error is returned.

terminals must be sorted.

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.

A helpful debugging aid to pretty print a Buffered Reader stack.

Uses the Buffered Readers’ fmt::Display implementations.

Boxes the reader.

Implementations on Foreign Types

Make a Box<BufferedReader> look like a BufferedReader.

Implementors