teh-bobo/stringbuffer

A fixed sized string for Rust.

StRing Buffer

StRing Buffer is a fixed sized UTF-8 String. It uses a ring buffer that overwrites the front when the buffer is full.

---

Usage

You can create a buffer on the stack using a constant size StRingBuffer::<SIZE>::new() or on the heap using a variable size HeapStRingBuffer::new(SIZE).

Both types of buffer implement the StringBuffer trait. The trait has a .push_str() and .push_char() method to add data to the buffer.

To read data is a bit more complicated. The .as_slices() method returns two &str. If the buffer reaches the end of its allotted size and loops back then the first &str will contain the string data from the start to the end of the buffer and the second string will contain the rest of the data.

If you want all the data in one &str then call .align() on the buffer first. This will ensure that all the data is returned to the first &str from .as_slices().

Examples

use st_ring_buffer::{HeapStRingBuffer, StRingBuffer, StringBuffer};

fn main() {
  // On the heap
  let mut heap = HeapStRingBuffer::new(5);
  heap.push_str("ABCDE");
  //as_slices() returns (&str, &str). If the buffer does not loop around the capacity then the second &str is empty.  
  assert_eq!(heap.as_slices().0, "ABCDE");
  //"FG" loops around to the front of the buffer, overwriting "AB"
  heap.push_str("FG");
  let (first, second) = heap.as_slices();
  assert_eq!(first, "CDE");
  assert_eq!(second, "FG");

  // On the stack
  let mut stack = StRingBuffer::<5>::new();
  stack.push_str("ABCDE");
  //'F' overwrites 'A', making the buffer loop around the capacity
  stack.push_char('F');
  //align the buffer so everything fits in one &str
  stack.align();
  assert_eq!(stack.as_slices().0, "BCDEF");
}

Time Complexity

Pushing data into the buffer is always constant time. Aligning the buffer is also done in constant time using, at most, two memcopys; however, it does allocate a temporary buffer that is the same size as the shortest &str returned by as_slices(). The StringBuffer trait also provides align_no_alloc if you would like to perform the alignment without allocating a temporary buffer, but using O(n) time, where 'n' is the length of the shortest leg of the buffer.

Features

Optional support for Serde is included.

No Std

This library is nostd compatible by default. A std feature exists to add std::error::Error to the StringBufferError type.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

stringbuffer's Issues

pop_front()

Remove Characters from Buffer

There needs to be a way to remove data from the buffer besides emptying it. Taking function on Vec as an example:

• #10
• #11
• #12
• #9

drain()

remove(index)

Allocations

Both buffer types should support creating a buffer with a custom allocater:

• Heap Buffer
• Stack Buffer

Additionally, align uses an alloc and should provide an alloc_in as well:

• align_in

Resizing

Although a bit counter to the point of the crate, providing at least shrinking methods may be useful. Ideas from Vec:

• resize(new_len, value)
• resize_with(new_len, F)

I don't intend on this being a 1.0 release requirement.

DoubleEnded

Implement Egui TextBuffer

Implement the egui TextBuffer trait so that this crate can be supplied to egui as a buffer in the text_edit widget.

Iterator Traits

Add iterator traits

• #7
• #8
• Iter?

IntoIter

pop()