Struct Reader

pub struct Reader<S> { /* private fields */ }

Available on crate feature nonblocking only.

Receives items from the queue.

Values sent by the writer will be added to the end of the reader’s buffer, and capacity can be sent back to the writer from the start of the reader’s buffer to allow it to write more data.

Implementations

impl<S> Reader<S>

pub fn is_writer_open(&self) -> bool

Returns if the corresponding writer is still open.

If this is false, unread data will still be available to read but a well-behaved writer will not provide any new data.

pub fn has_data(&self) -> bool

Returns if data is available in the reader’s buffer.

If this is true it is guaranteed that the next call to buf will return a non-empty slice, unless consume is called first.

Keep in mind that when using a reader and writer on separate threads, a reader that has no data can receive data at any time - even between calls to has_data and other functions.

pub fn is_full(&self) -> bool

Returns if the buffer is full, i.e all space is allocated to the reader and any write operations will fail.

If this is true a reader can only resume the writer by calling consume to pass capacity to the writer.

Keep in mind that when using a reader and writer on separate threads, a reader that is not full can become full at any time - even between calls to is_full and other functions.

pub fn buf<T>(&self) -> Region<'_, T>

where S: Storage<T>,

Gets the readable buffer.

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 buf 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 items are never returned twice.

An empty buffer returned indicates that no data is available to read.

Panics

This function may panic if the underlying storage panics when trying to get a slice to the data. This may happen if queue was created with a ring that has a larger capacity than the storage.

pub fn consume(&mut self, amt: usize)

Marks items at the start of the reader buffer as consumed, removing them from the slice returned by buf and adding their capacity to the end of the writer’s buffer. Since queues have a fixed underlying length, calling this is required to allow the transfer of more data.

Panics

This function will panic if amt is larger than the reader’s available data buffer.

pub fn read<T>(&mut self, buf: &mut [T]) -> usize

where S: Storage<T>, T: Clone,

Pulls some items from this queue into the specified buffer, returning how many items were read.

Return

It is guaranteed that the return value is <= buf.len().

A return value of 0 indicates one of these three scenarios:

1. No data was available to read.
2. The writer has closed and all items have been read.
3. The buffer specified had a length of 0.

pub fn close(&mut self)

Close the reader, indicating to the writer that no more data will be read.

Any future write operations will fail. Closing the reader multiple times has no effect.

Dropping the reader object will also close it.

Trait Implementations

impl<S> BufRead for Reader<S>

where S: Storage<u8>,

Available on crate feature std-io only.

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

Returns the contents of the internal buffer, filling it with more data, via Read methods, if empty.

fn consume(&mut self, amt: usize)

Marks the given amount of additional bytes from the internal buffer as having been read. Subsequent calls to read only return bytes that have not been marked as read.

fn has_data_left(&mut self) -> Result<bool, Error>

🔬This is a nightly-only experimental API. (buf_read_has_data_left)

Checks if there is any data left to be read.

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

Reads all bytes into buf until the delimiter byte or EOF is reached.

fn skip_until(&mut self, byte: u8) -> Result<usize, Error>

Skips all bytes until the delimiter byte or EOF is reached.

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

Reads all bytes until a newline (the 0xA byte) is reached, and append them to the provided String buffer.

fn split(self, byte: u8) -> Split<Self>

where Self: Sized,

Returns an iterator over the contents of this reader split on the byte byte.

fn lines(self) -> Lines<Self>

where Self: Sized,

Returns an iterator over the lines of this reader.

impl<S: Debug> Debug for Reader<S>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<S> Drop for Reader<S>

fn drop(&mut self)

Executes the destructor for this type.

impl<S> Read for Reader<S>

where S: Storage<u8>,

Available on crate feature std-io only.

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

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

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

Like read, except that it reads into a slice of buffers.

fn is_read_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Reader has an efficient read_vectored implementation.

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

Reads all bytes until EOF in this source, placing them into buf.

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

Reads all bytes until EOF in this source, appending them to buf.

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

Reads the exact number of bytes required to fill buf.

fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Pull some bytes from this source into the specified buffer.

fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Reads the exact number of bytes required to fill cursor.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adaptor for this instance of Read.

fn bytes(self) -> Bytes<Self>

where Self: Sized,

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R>

where R: Read, Self: Sized,

Creates an adapter which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

where Self: Sized,

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