Struct fixed_buffer::FixedBuf

source · [−]

pub struct FixedBuf<const SIZE: usize> { /* private fields */ }

Expand description

A fixed-length byte buffer. You can write bytes to it and then read them back.

It is not a circular buffer. Call shift periodically to move unread bytes to the front of the buffer.

Implementations

source

impl<const SIZE: usize> FixedBuf<SIZE>

source

pub const fn new() -> Self

Makes a new empty buffer with space for SIZE bytes.

Be careful of stack overflows!

source

pub fn into_inner(self) -> [u8 ; SIZE]

Drops the struct and returns its internal array.

source

pub fn len(&self) -> usize

Returns the number of unread bytes in the buffer.

pub fn is_empty(&self) -> bool

Returns true if there are unread bytes in the buffer.

pub fn clear(&mut self)

Discards all data in the buffer.

source

pub fn escape_ascii(&self) -> String

Copies all readable bytes to a string. Includes printable ASCII characters as-is. Converts non-printable characters to strings like “\n” and “\x19”.

Uses core::ascii::escape_default internally to escape each byte.

This function is useful for printing byte slices to logs and comparing byte slices in tests.

Example test:

use fixed_buffer::FixedBuf;
let mut buf: FixedBuf<8> = FixedBuf::new();
buf.write_bytes("abc");
buf.write_bytes("€");
assert_eq!("abc\\xe2\\x82\\xac", buf.escape_ascii());

source

pub fn mem(&self) -> &[u8 ]ⓘNotable traits for &'_ [u8 ]`impl<'_> Read for &'_ [u8]impl<'_> Write for &'_ mut [u8]`

Borrows the entire internal memory buffer. This is a low-level function.

source

pub fn readable(&self) -> &[u8 ]ⓘNotable traits for &'_ [u8 ]`impl<'_> Read for &'_ [u8]impl<'_> Write for &'_ mut [u8]`

Returns the slice of readable bytes in the buffer. After processing some bytes from the front of the slice, call read to consume the bytes.

This is a low-level method. You probably want to use std::io::Read::read or tokio::io::AsyncReadExt::read , implemented for FixedBuf in fixed_buffer_tokio::AsyncReadExt.

source

pub fn try_read_byte(&mut self) -> Option<u8>

Reads a single byte from the buffer.

Returns None if the buffer is empty.

source

pub fn try_read_exact(&mut self, num_bytes: usize) -> Option<&[u8 ]>

Reads bytes from the buffer.

Returns None if the buffer does not contain num_bytes bytes.

source

pub fn read_all(&mut self) -> &[u8 ]ⓘNotable traits for &'_ [u8 ]`impl<'_> Read for &'_ [u8]impl<'_> Write for &'_ mut [u8]`

Reads all the bytes from the buffer.

The buffer becomes empty and subsequent writes can fill the whole buffer.

source

pub fn read_and_copy_bytes(&mut self, dest: &mut [u8 ]) -> usize

Reads bytes from the buffer and copies them into dest.

Returns the number of bytes copied.

Returns 0 when the buffer is empty or dest is zero-length.

source

pub fn read_and_copy_exact(&mut self, dest: &mut [u8 ]) -> Option<()>

Reads byte from the buffer and copies them into dest, filling it, and returns Some(()).

Returns None if the buffer does not contain enough bytes tp fill dest.

Returns Some(()) if dest is zero-length.

source

pub fn copy_once_from(&mut self, reader: &mut impl Read) -> Result<usize, Error>

Reads from reader once and writes the data into the buffer.

Use shift to make empty space usable for writing.

Errors

Returns InvalidData if there is no empty space in the buffer.

source

pub fn write_bytes(
&mut self,
data: impl AsRef<[u8 ]>
) -> Result<usize, NoWritableSpace>

Tries to write data into the buffer, after any unread bytes.

Returns Ok(num_written), which may be less than the length of data.

Returns Ok(0) only when data is empty.

Use shift to make empty space usable for writing.

Errors

Returns NoWritableSpace when the buffer has no free space at the end.

pub fn writable(&mut self) -> &mut [u8 ]ⓘNotable traits for &'_ [u8 ]`impl<'_> Read for &'_ [u8]impl<'_> Write for &'_ mut [u8]`

Returns the writable part of the buffer.

To use this, first modify bytes at the beginning of the slice. Then call wrote(usize) to commit those bytes into the buffer and make them available for reading.

Returns an empty slice when the end of the buffer is full.

Use shift to make empty space usable for writing.

This is a low-level method. You probably want to use std::io::Write::write or tokio::io::AsyncWriteExt::write, implemented for FixedBuf in fixed_buffer_tokio::AsyncWriteExt.

pub fn wrote(&mut self, num_bytes: usize)

Commits bytes into the buffer. Call this after writing to the front of the writable slice.

This is a low-level method.

See writable().

Panics

Panics when there is not num_bytes free at the end of the buffer.

source

pub fn shift(&mut self)

Recovers buffer space.

The buffer is not circular. After you read bytes, the space at the beginning of the buffer is unused. Call this method to move unread data to the beginning of the buffer and recover the space. This makes the free space available for writes, which go at the end of the buffer.

source

pub fn deframe<F>(
 &mut self,
 deframer_fn: F
) -> Result<Option<Range<usize>>, Error> where
 F: Fn(&[u8 ]) -> Result<(usize, Option<Range<usize>>), MalformedInputError>,

This is a low-level function. Use read_frame instead.

Calls deframer_fn to check if the buffer contains a complete frame. Consumes the frame bytes from the buffer and returns the range of the frame’s contents in the internal memory.

Use mem to immutably borrow the internal memory and construct the slice with &buf.mem()[range]. This is necessary because deframe borrows self mutably but read_frame needs to borrow it immutably and return a slice.

Returns None if the buffer is empty or contains an incomplete frame.

Errors

Returns InvalidData when deframer_fn returns an error.

source

pub fn read_frame<R, F>(
 &mut self,
 reader: &mut R,
 deframer_fn: F
) -> Result<Option<&[u8 ]>, Error> where
 R: Read,
 F: Fn(&[u8 ]) -> Result<(usize, Option<Range<usize>>), MalformedInputError>,

Reads from reader into the buffer.

After each read, calls deframer_fn to check if the buffer now contains a complete frame. Consumes the frame bytes from the buffer and returns a slice with the frame contents.

Returns None when reader reaches EOF and the buffer is empty.

Calls shift before reading.

Provided deframer functions:

Errors

Returns UnexpectedEof when reader reaches EOF and the buffer contains an incomplete frame.

Returns InvalidData when deframer_fn returns an error or the buffer fills up.

Example

let mut buf: FixedBuf<32> = FixedBuf::new();
let mut input = std::io::Cursor::new(b"aaa\r\nbbb\n\nccc\n");
loop {
  if let Some(line) = buf.read_frame(&mut input, deframe_line).unwrap() {
    println!("{}", escape_ascii(line));
  } else {
    // EOF.
    break;
  }
}
// Prints:
// aaa
// bbb
//
// ccc

Deframer Function `deframe_fn`

Checks if data contains an entire frame.

Never panics.

Returns Ok((frame_len, Some(payload_range)) when data contains a complete frame at &data[payload_range]. The caller should consume frame_len from the beginning of the buffer before calling deframe again.

Returns Ok((frame_len, None)) if data contains an incomplete frame. The caller should consume frame_len from the beginning of the buffer. The caller can read more bytes and call deframe again.

Returns Err(MalformedInputError) if data contains a malformed frame.

Popular frame formats:

Newline-delimited: CSV, JSONL, HTTP, Server-Sent Events text/event-stream, and SMTP
Hexadecimal length prefix: HTTP chunked transfer encoding
Binary length prefix: TLS

Example

use fixed_buffer::deframe_crlf;
assert_eq!(Ok((0, None)), deframe_crlf(b""));
assert_eq!(Ok((0, None)), deframe_crlf(b"abc"));
assert_eq!(Ok((0, None)), deframe_crlf(b"abc\r"));
assert_eq!(Ok((0, None)), deframe_crlf(b"abc\n"));
assert_eq!(Ok((5, Some((0..3)))), deframe_crlf(b"abc\r\n"));
assert_eq!(Ok((5, Some((0..3)))), deframe_crlf(b"abc\r\nX"));