Struct 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.

§Example

let mut buf: FixedBuf<16> = FixedBuf::new();
assert_eq!(0, buf.len());
buf.write_bytes("abc");
assert_eq!(3, buf.len());
buf.try_read_exact(2).unwrap();
assert_eq!(1, buf.len());
buf.shift();
assert_eq!(1, buf.len());
buf.read_all();
assert_eq!(0, buf.len());

Source

pub fn is_empty(&self) -> bool

Returns true if there are unread bytes in the buffer.

§Example

let mut buf: FixedBuf<16> = FixedBuf::new();
assert!(buf.is_empty());
buf.write_bytes("abc").unwrap();
assert!(!buf.is_empty());
buf.read_all();
assert!(buf.is_empty());

Source

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] ⓘ

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

Source

pub fn readable(&self) -> &[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.

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] ⓘ

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.

§Example

let mut buf: FixedBuf<3> = FixedBuf::new();
assert_eq!(2, buf.write_bytes("ab").unwrap());
assert_eq!(1, buf.write_bytes("cd").unwrap()); // Fills buffer, "d" not written.
assert_eq!("abc", buf.escape_ascii());
buf.write_bytes("d").unwrap_err();  // Error, buffer is full.

Source

pub fn writable(&mut self) -> &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.

§Example

let mut buf: FixedBuf<8> = FixedBuf::new();
buf.writable()[0] = 'a' as u8;
buf.writable()[1] = 'b' as u8;
buf.writable()[2] = 'c' as u8;
buf.wrote(3);
assert_eq!("abc", buf.escape_ascii());

Source

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"));