fixed-buffer

This is a Rust library with fixed-size buffers, useful for network protocol parsers and file parsers.

Features

forbid(unsafe_code)
Depends only on std
Write bytes to the buffer and read them back
Lives on the stack
Does not allocate
Use it to read a stream, search for a delimiter, and save leftover bytes for the next read.
No macros
Good test coverage (99%)
Async support by enabling cargo features async-std-feature, futures-io, smol-feature, or tokio.

Limitations

Not a circular buffer. You can call shift() periodically to move unread bytes to the front of the buffer.

Examples

Read and handle requests from a remote client: ```rust use fixedbuffer::{deframeline, FixedBuf}; use std::io::Error; use std::net::TcpStream;

fn handleconn(mut tcpstream: TcpStream) -> Result<(), Error> { let mut buf: FixedBuf<4096> = FixedBuf::new(); loop { // Read a line // and leave leftover bytes in buf. let linebytes = match buf.readframe( &mut tcpstream, deframeline)? { Some(linebytes) => linebytes, None => return Ok(()), }; let request = Request::parse(linebytes)?; handlerequest(request)?; } } ``For a complete example, see [tests/server.rs`](https://gitlab.com/leonhard-llc/fixed-buffer-rs/-/blob/main/fixed-buffer/tests/server.rs).

Read and process records: ```rust use fixed_buffer::FixedBuf; use std::io::{Error, ErrorKind, Read}; use std::net::TcpStream;

fn tryprocessrecord(b: &[u8]) -> Result { if b.len() < 2 { return Ok(0); } if b.startswith("ab".asbytes()) { println!("found record"); Ok(2) } else { Err(Error::new(ErrorKind::InvalidData, "bad record")) } }

fn readandprocess(mut input: R) -> Result<(), Error> { let mut buf: FixedBuf<1024> = FixedBuf::new(); loop { // Read a chunk into the buffer. if buf.copyoncefrom(&mut input)? == 0 { return if buf.len() == 0 { // EOF at record boundary Ok(()) } else { // EOF in the middle of a record Err(Error::from( ErrorKind::UnexpectedEof)) }; } // Process records in the buffer. loop { let numtoconsume = tryprocessrecord(buf.readable())?; if numtoconsume == 0 { break; } buf.tryreadexact(numtoconsume).unwrap(); } // Shift data in the buffer to free up // space at the end for writing. buf.shift(); } } # ```

The From<[u8; SIZE]> implementation is useful in tests. Example: rust use core::convert::From; assert_eq!(3, FixedBuf::from(*b"abc").len());

Alternatives

bytes
buf_redux, circular buffer support
std::io::BufReader
std::io::BufWriter
static-buffer, updated in 2016
block-buffer, for processing fixed-length blocks of data
arrayvec, vector with fixed capacity.

Changelog

v0.5.0 - Move ReadWriteChain and ReadWriteTake to new read-write-ext crate.
v0.4.0
- From<&[u8]>
- write_bytes to take AsRef<[u8]>
- Rename try_read_exact to read_and_copy_exact.
- Rename try_read_bytes to try_read_exact.
- Remove empty, filled, read_byte, read_bytes, try_parse, and write_str.
- deframe to allow consuming bytes without returning a frame
- write_bytes to write as many bytes as it can, and return new NoWritableSpace error only when it cannot write any bytes. Remove NotEnoughSpaceError. The method now behaves like std::io::Write::write.
v0.3.1 - Implement From<NotEnoughSpaceError> and From<MalformedInputError> for String.

Older changelog entries

v0.3.0 - Breaking API changes:
- Change type parameter to const buffer size. Example: FixedBuf<1024>.
- Remove new arg.
- Remove capacity.
- Remove Copy impl.
- Change writable return type to &mut [u8].
v0.2.3
- Add read_byte, try_read_byte, try_read_bytes, try_read_exact, try_parse.
- Implement UnwindSafe
v0.2.2 - Add badges to readme
v0.2.1 - Add deframe and mem, needed by AsyncFixedBuf::read_frame.
v0.2.0
- Move tokio support to fixed_buffer_tokio.
- Add copy_once_from, read_block, ReadWriteChain, and ReadWriteTake.
v0.1.7 - Add FixedBuf::escape_ascii.
v0.1.6 - Add filled constructor.
v0.1.5 - Change read_delimited to return Option<&[u8]>, for clean EOF handling.
v0.1.4 - Add clear().
v0.1.3
- Thanks to freax13 for these changes:
- Support any buffer size. Now you can make FixedBuf<[u8; 42]>.
- Support any AsRef<[u8]> + AsMut<[u8]> value for internal memory:
  - [u8; N]
  - Box<[u8; N]>
  - &mut [u8]
  - Vec<u8>
- Renamed new_with_mem to new. Use FixedBuf::default() to construct any FixedBuf<T: Default>, which includes arrays of sizes up to 32.
v0.1.2 - Updated documentation.
v0.1.1 - First published version

TO DO

Change links in docs to standard style. Don't link to docs.rs.
Idea: buf.slice(buf.read_frame(&mut reader, deframe_crlf))
Add an frame_copy_iter function. Because of borrowing rules, this function must return non-borrowed (allocated and copied) data.
Set up CI on:
- DONE - Linux x86 64-bit
- macOS
- Windows
- https://crate-ci.github.io/pr/testing.html#travisci
- Linux ARM 64-bit (Raspberry Pi 3 and newer)
- Linux ARM 32-bit (Raspberry Pi 2)
- RISCV & ESP32 firmware?
DONE - Try to make this crate comply with the Rust API Guidelines.
DONE - Find out how to include Readme.md info in the crate's docs.
DONE - Make the repo public
DONE - Set up continuous integration tests and banner.
- https://github.com/actions-rs/example
- https://alican.codes/rust-github-actions/
DONE - Add some documentation tests
- https://doc.rust-lang.org/rustdoc/documentation-tests.html
- https://doc.rust-lang.org/stable/rust-by-example/testing/doc_testing.html
DONE - Set up public repository on Gitlab.com
DONE - Publish to crates.io
DONE - Read through https://crate-ci.github.io/index.html
DONE - Get a code review from an experienced rustacean
DONE - Add and update a changelog
- Update it manually
- https://crate-ci.github.io/release/changelog.html

Release Process

Edit Cargo.toml and bump version number.
Run ../release.sh

License: Apache-2.0