Trait StringBuffer 

pub trait StringBuffer {
    // Required methods
    fn push_char(&mut self, c: char);
    fn pop(&mut self) -> Option<char>;
    fn pop_front(&mut self) -> Option<char>;
    fn try_push_char(&mut self, c: char) -> Result<usize, StringBufferError>;
    fn try_push_some(&mut self, s: &str) -> Result<usize, StringBufferError>;
    fn as_slices(&self) -> (&str, &str);
    fn align(&mut self);
    fn align_no_alloc(&mut self);
    fn len(&self) -> usize;
    fn is_empty(&self) -> bool;
    fn capacity(&self) -> usize;
    fn remaining_size(&self) -> usize;
    fn clear(&mut self);

    // Provided methods
    fn push_str(&mut self, s: &str) { ... }
    fn try_push_all(&mut self, s: &str) -> Result<(), StringBufferError> { ... }
    fn chars(&self) -> Chain<Chars<'_>, Chars<'_>> { ... }
}

A buffer specializing in holding data for a string. Pushing data to the buffer will not fail nor panic. When full, the end of the data overwrites the start, while keeping the integrity of the underlying utf-8 data.

Required Methods

fn push_char(&mut self, c: char)

Adds a char to the buffer. Overwrites the start if the buffer is full.

This will never panic nor fail. However, if the length of the char in utf-8 exceeds the length of the buffer then the buffer will be emptied.

Example

use st_ring_buffer::{StRingBuffer, StringBuffer};
let mut buffer = StRingBuffer::<5>::new();
buffer.push_char('F');
assert_eq!(buffer.as_slices().0, "F");
assert_eq!(buffer.as_slices().1, "");

fn pop(&mut self) -> Option<char>

Remove a char from the buffer if one exists. Returns None if the buffer is empty.

fn pop_front(&mut self) -> Option<char>

Remove a char from the front of the buffer if one exists. Returns None if the buffer is empty.

fn try_push_char(&mut self, c: char) -> Result<usize, StringBufferError>

Tries to push the given character into the buffer. Will return Ok(c.bytes_len) if the write succeeded. If there is not enough room for the char or the buffer is full then Err(NotEnoughSpaceForChar) or Err(BufferFull) is returned respectively.

Example

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

let mut buffer = StRingBuffer::<5>::new();
let res = buffer.try_push_char('🦀'); //Crab Emoji (Fat Ferris) (UTF-8: 0xF0 0x9F 0xA6 0x80)
assert_eq!(res, Ok(4));

let res = buffer.try_push_char('🦀');
//already 4 bytes in the buffer, can't fit 4 more
assert_eq!(res, Err(StringBufferError::NotEnoughSpaceForChar));

//but 1 more does fit
assert_eq!(buffer.try_push_char('A'), Ok(1));

//now the buffer is full and can't fit anything
assert_eq!(buffer.try_push_char('A'), Err(StringBufferError::BufferFull));

fn try_push_some(&mut self, s: &str) -> Result<usize, StringBufferError>

Will push as many chars as will fit into the existing space of the buffer. Will not overwrite any existing data.

Example

use st_ring_buffer::{StRingBuffer, StringBuffer};

let mut buffer = StRingBuffer::<5>::new();
let res = buffer.try_push_some("ABCDEFGHIJKLMNO"); // too long
assert_eq!(res, Ok(5)); //only 5 bytes pushed
// the first bytes are pushed so long as there's room
assert_eq!(buffer.as_slices().0,"ABCDE");

fn as_slices(&self) -> (&str, &str)

Get a reference to the two buffer segments in order.

If the current data fits entirely in the buffer, and it is aligned, then the second reference will be an empty &str.

Example

use st_ring_buffer::{StRingBuffer, StringBuffer};
let mut buffer = StRingBuffer::<5>::new();
buffer.push_str("ABCDE");
assert_eq!(buffer.as_slices().0, "ABCDE");
assert_eq!(buffer.as_slices().1, "");

buffer.push_char('F');
assert_eq!(buffer.as_slices().0, "BCDE");
assert_eq!(buffer.as_slices().1,"F");

fn align(&mut self)

Copies data as required to make the head the start of the buffer. This allocates a temporary buffer the size of the smaller &str given by as_slices.

This is required to represent the entire buffer as a single &str.

Example

use st_ring_buffer::{StRingBuffer, StringBuffer};
let mut buffer = StRingBuffer::<5>::new();
buffer.push_str("ABCDE");
buffer.push_char('F');
assert_eq!(buffer.as_slices().0, "BCDE");
assert_eq!(buffer.as_slices().1, "F");
buffer.align();
assert_eq!(buffer.as_slices().0, "BCDEF");

fn align_no_alloc(&mut self)

Aligns the head of the buffer to the start via rotation. Compared to align this function does not allocate any memory; however, it works in O(buffer.len()) time.

This is required to represent the entire buffer as a single &str.

Example

use st_ring_buffer::{StRingBuffer, StringBuffer};
let mut buffer = StRingBuffer::<5>::new();
buffer.push_str("ABCDE");
buffer.push_char('F');
assert_eq!(buffer.as_slices().0, "BCDE");
assert_eq!(buffer.as_slices().1, "F");
buffer.align_no_alloc();
assert_eq!(buffer.as_slices().0, "BCDEF");

fn len(&self) -> usize

Returns the length of this buffer, in bytes, not chars or graphemes

Example

use st_ring_buffer::{StRingBuffer, StringBuffer};
let mut buffer = StRingBuffer::<5>::new();
buffer.push_str("ABCDEF");
assert_eq!(buffer.len(), 5);

fn is_empty(&self) -> bool

Returns true if there is no data in the buffer.

fn capacity(&self) -> usize

The number of bytes this buffer can hold. Not the number of chars or graphemes.

Example

use st_ring_buffer::{StRingBuffer, StringBuffer};
let mut buffer = StRingBuffer::<5>::new();
assert_eq!(buffer.capacity(), 5);

fn remaining_size(&self) -> usize

Convenience function to return the number of bytes remaining in the buffer before data is overwritten. This is roughly equivalent to self.capacity() - self.len(), but takes into account any padding required along the edge of the buffer.

fn clear(&mut self)

Empties the buffer

Provided Methods

fn push_str(&mut self, s: &str)

Adds a &str to the buffer. Overwrites the start if the buffer is full.

This will never panic nor fail.

Example

use st_ring_buffer::{StRingBuffer, StringBuffer};
let mut buffer = StRingBuffer::<5>::new();
buffer.push_str("ABCDE");
buffer.push_char('F');
assert_eq!(buffer.as_slices().0,"BCDE");
assert_eq!(buffer.as_slices().1, "F");

fn try_push_all(&mut self, s: &str) -> Result<(), StringBufferError>

Try to push the entire string into the buffer. If the string is too long or the buffer is full then nothing is written and Err(NotEnoughSpaceForStr) or Err(BufferFull) is returned respectively.

Example

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

let mut buffer = StRingBuffer::<5>::new();
assert_eq!(buffer.try_push_all("ABCDE"), Ok(()));
assert_eq!(buffer.try_push_all("Z"), Err(StringBufferError::BufferFull));

buffer.clear();
let res = buffer.try_push_all("ABCDEFGHIJKLMNO"); // too long
assert_eq!(res, Err(StringBufferError::NotEnoughSpaceForStr));

fn chars(&self) -> Chain<Chars<'_>, Chars<'_>>

Returns an iterator over the characters in the buffer. This includes both slices, in order, if the buffer is currently split.

Example

use st_ring_buffer::{StRingBuffer, StringBuffer};

let mut buffer = StRingBuffer::<5>::new();
//Fill up the buffer
buffer.push_str("ABCDE");
//add one more so that the buffer is looped
buffer.push_char('F');
assert_eq!(buffer.as_slices().0, "BCDE");
assert_eq!(buffer.as_slices().1, "F");

//iterator doesn't care about loop and still gives all chars in order
let mut iter = buffer.chars();
assert_eq!(Some('B'), iter.next());
assert_eq!(Some('C'), iter.next());
assert_eq!(Some('D'), iter.next());
assert_eq!(Some('E'), iter.next());
assert_eq!(Some('F'), iter.next());
assert_eq!(None, iter.next());

Implementors

impl StringBuffer for HeapStRingBuffer

impl<const SIZE: usize> StringBuffer for StRingBuffer<SIZE>