Trait netio::BufReadGrow

pub trait BufReadGrow: BufRead {
    fn grow_buf(&mut self) -> Result<&[u8]>;

    fn fill_buf_min(&mut self, size: usize) -> Result<&[u8]> { ... }
    fn read_until2(&mut self, delims: (u8, u8), buf: &mut Vec<u8>) -> Result<()> { ... }
    fn skip_until2(&mut self, delims: (u8, u8)) -> Result<()> { ... }
    fn decode_utf8(self) -> Utf8Reader<Self>
    where
        Self: Sized,
    { ... }
}

A BufReadGrow is a BufReader that has the ability to read additional data even if the buffer is not empty.

A BufRead guarantees an internal buffer of at only one byte with no possibility to read additional data without consuming the already read data first. With this limitation it is not possible to implement many functions in an interrupt-safe way.

Interrupt-safe function require that - when the function returns - all data is either left in the stream or appended to the buffer. But for example when read UTF-8 with a BufReader, this requirement can only be met by appending incomplete UTF-8 to the buffer which is also unacceptable by itself.

For that reason, the BufReadGrow trait is introduced which extends BufRead by a method to grow the internal buffer. This requires the buffer to be able to relocate the data in the internal buffer.

Required Methods

fn grow_buf(&mut self) -> Result<&[u8]>

Grows the internal buffer of this object by at least one byte, returning the buffer contents.

Like fill_buf, this function is a lower-level call. It needs to be paired with the consume method to function properly. When calling this method, none of the contents will be "read" in the sense that later calling read may return the same contents. As such, consume must be called with the number of bytes that are consumed from this buffer to ensure that the bytes are never returned twice.

Errors

• Any error returned by the underlying call to read will be returned immediately.
• If the stream has already reached EOF, an error of kind ErrorKind::UnexpectedEof is returned.
• If the internal buffer of is full, an appropriate error is returned. Since there is no specific ErrorKind for this, ErrorKind::Other should be used.

Provided Methods

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

Fills the internal buffer to at least the specified amount, returning the buffer contents.

Like BufRead::fill_buf and grow_buf, this function is a lower-level call. It needs to be paired with the consume method to function properly. When calling this method, none of the contents will be "read" in the sense that later calling read may return the same contents. As such, consume must be called with the number of bytes that are consumed from this buffer to ensure that the bytes are never returned twice.

Errors

• Any I/O error will be returned immediately.
• If the stream has already reached EOF, an error of kind ErrorKind::UnexpectedEof is returned.
• If the internal buffer of is full, an appropriate error is returned. See grow_buf for more details.

fn read_until2(&mut self, delims: (u8, u8), buf: &mut Vec<u8>) -> Result<()>

Read all bytes into a buffer until two consecutive delimiters are reached.

This function will read bytes from the underlying stream and push them to the specified buffer buf, until the two consecutive delimiters delims are found. If the delimiters are found, they also part of the result.

Errors

This function will return an error immediately if a call to fill_buf returns any kind of error. Instances of ErrorKind::Interrupted are not handled by this function.

If this reader has reached EOF then this function will return ErrorKind::UnexpectedEof.

In case of an error, all bytes read up to that point are appended to the buffer and consumed from this buffered reader. There's one notable exception to that rule: If the last byte in the buffer would be the first delimiter, it is left in the buffered reader. Otherwise retrying on error would not work reliably.

In any case, all bytes consumed from the buffered reader will be written to the specified buffer and vice versa. It is guaranteed that no data is lost in case of error.

fn skip_until2(&mut self, delims: (u8, u8)) -> Result<()>

Skip all bytes until two consecutive delimiters are reached.

This function will discard bytes from the underlying stream until the two consecutive delimiters delims are found.

Errors

This function will return an error immediately if a call to fill_buf returns any kind of error. Instances of ErrorKind::Interrupted are not handled by this function.

If this reader has reached EOF then this function will return ErrorKind::UnexpectedEof.

fn decode_utf8(self) -> Utf8Reader<Self> where
    Self: Sized, 

Implementations on Foreign Types

impl<'a, B: BufReadGrow + ?Sized> BufReadGrow for &'a mut B

fn grow_buf(&mut self) -> Result<&[u8]>

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

fn read_until2(&mut self, delims: (u8, u8), buf: &mut Vec<u8>) -> Result<()>

fn skip_until2(&mut self, delims: (u8, u8)) -> Result<()>

fn decode_utf8(self) -> Utf8Reader<Self> where
    Self: Sized, 

impl<B: BufReadGrow + ?Sized> BufReadGrow for Box<B>

fn grow_buf(&mut self) -> Result<&[u8]>

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

fn read_until2(&mut self, delims: (u8, u8), buf: &mut Vec<u8>) -> Result<()>

fn skip_until2(&mut self, delims: (u8, u8)) -> Result<()>

fn decode_utf8(self) -> Utf8Reader<Self> where
    Self: Sized, 

impl BufReadGrow for Empty

fn grow_buf(&mut self) -> Result<&[u8]>

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

fn read_until2(&mut self, delims: (u8, u8), buf: &mut Vec<u8>) -> Result<()>

fn skip_until2(&mut self, delims: (u8, u8)) -> Result<()>

fn decode_utf8(self) -> Utf8Reader<Self> where
    Self: Sized, 

impl<'a> BufReadGrow for &'a [u8]

fn grow_buf(&mut self) -> Result<&[u8]>

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

fn read_until2(&mut self, delims: (u8, u8), buf: &mut Vec<u8>) -> Result<()>

fn skip_until2(&mut self, delims: (u8, u8)) -> Result<()>

fn decode_utf8(self) -> Utf8Reader<Self> where
    Self: Sized, 

impl<T> BufReadGrow for Cursor<T> where
    T: AsRef<[u8]>, 

fn grow_buf(&mut self) -> Result<&[u8]>

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

fn read_until2(&mut self, delims: (u8, u8), buf: &mut Vec<u8>) -> Result<()>

fn skip_until2(&mut self, delims: (u8, u8)) -> Result<()>

fn decode_utf8(self) -> Utf8Reader<Self> where
    Self: Sized, 

impl<R, Rs, Ms> BufReadGrow for BufReader<R, Rs, Ms> where
    R: Read,
    Rs: ReadStrategy,
    Ms: MoveStrategy, 

fn grow_buf(&mut self) -> Result<&[u8]>

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

fn read_until2(&mut self, delims: (u8, u8), buf: &mut Vec<u8>) -> Result<()>

fn skip_until2(&mut self, delims: (u8, u8)) -> Result<()>

fn decode_utf8(self) -> Utf8Reader<Self> where
    Self: Sized, 

Implementors

• impl<R: BufReadGrow> BufReadGrow for Retry<R>
• impl<T: BufReadGrow> BufReadGrow for Take<T>