added comments and better std support

Author: Tim Siemers

examples/reader.rs

@@ -10,7 +10,7 @@ fn main () {
     let mut buffer = Buffer::new(&mut bytes);
 
     // Write some bytes
-    buffer.write_all("abc".as_bytes()).unwrap();
+    buffer.write_all("👌abc".as_bytes()).unwrap();
 
     // try to read to a komma but there is none
     let reader = buffer.create_reader();
@@ -24,7 +24,7 @@ fn main () {
     // try to read to a komma. now there is one
     let reader = buffer.create_reader();
     let result = read_til_komma(&reader);
-    assert_eq!(result, Some("abcdef"));
+    assert_eq!(result, Some("👌abcdef"));
     drop(reader);
 
     assert_eq!(buffer.data(), "1234".as_bytes());
@@ -50,8 +50,10 @@ fn read_til_komma<'a>(reader: &'a impl BufferReader) -> Option<&'a str> {
     if let Some(comma_position) = comma_position {
         let data = &str[..comma_position];
 
+        let bytes_read = data.as_bytes().len() + 1;
+
         // Tell the reader that you have read `data.len() + 1` bytes
-        reader.add_bytes_read(data.len() + 1);
+        reader.add_bytes_read(bytes_read);
         Some(data)
     } else {
         None

examples/stack_buffer.rs

@@ -1,12 +1,12 @@
-use embytes_buffer::new_stack_buffer;
+use embytes_buffer::Buffer;
 use embedded_io::{Read, Write};
 
 
 
 fn main () {
 
     // Create a new buffern with an array as byte source on the stack
-    let mut buffer = new_stack_buffer::<1024>();
+    let mut buffer = Buffer::<[u8; 1024]>::new_stack();
 
     // Write some bytes to buffer
     buffer.write_all("hello world".as_bytes()).unwrap();

examples/writer.rs

@@ -13,14 +13,16 @@ fn main () {
     // Create a writer, write some bytes but do not commit
     // writer implements DerefMut<Target = [u8]> and can be used as a mutable bytes slice
     let mut writer = buffer.create_writer();
-    writer[0] = 36; // ascii '$'
+    writer[0] = '$' as u8;
+
+    // The writer is dropped without committing so the write has no effect
     drop(writer);
 
     // Create a new writer
     let mut writer = buffer.create_writer();
-    writer[0] = 100; // ascii d
-    writer[1] = 101; // ascii e
-    writer[2] = 102; // ascii f
+    writer[0] = 'd' as u8;
+    writer[1] = 'e' as u8;
+    writer[2] = 'f' as u8;
 
     // Commit that 3 bytes are written
     // writing bytes has only an effect if the written bytes are committed

src/lib.rs

@@ -59,6 +59,7 @@ pub struct Buffer<T: AsMut<[u8]> + AsRef<[u8]>> {
 }
 
 /// Creates a new [`Buffer`] that is backed by an owned [`u8`] array with size `N`
+#[deprecated]
 pub fn new_stack_buffer<const N: usize>() -> Buffer<[u8; N]> {
     Buffer::<[u8; N]> {
         source: [0; N],
@@ -67,6 +68,49 @@ pub fn new_stack_buffer<const N: usize>() -> Buffer<[u8; N]> {
     }
 }
 
+impl <const N: usize> Buffer<[u8; N]> {
+
+    /// Creates a new [`Buffer`] that is backed by an owned [`u8`] array with size `N`
+    pub fn new_stack() -> Self {
+        Self {
+            source: [0; N],
+            read_position: 0,
+            write_position: 0,
+        }
+    }
+}
+
+#[cfg(feature = "std")]
+impl Buffer<Vec<u8>> {
+
+    /// Creates a new [`Buffer`] that is backed by an owned [`Vec<u8>`]
+    pub fn new_heap(size: usize) -> Self {
+        Self {
+            source: vec![0; size],
+            read_position: 0,
+            write_position: 0,
+        }
+    }
+
+    /// Grows the buffer capacity by `grow_by` bytes
+    pub fn grow(&mut self, grow_by: usize) {
+        self.source.extend(
+            std::iter::repeat_n(0, grow_by)
+        );
+    }
+
+    /// Shrink the buffer capacity by `shrink_by` bytes.
+    /// If this would remove written data, an [`BufferError::NoCapacity`] is returned.
+    pub fn shrink(&mut self, shrink_by: usize) -> Result<(), BufferError> {
+        if self.remaining_capacity() < shrink_by {
+            Err(BufferError::NoCapacity)
+        } else {
+            self.source.truncate(self.source.len().saturating_sub(shrink_by));
+            Ok(())
+        }
+    }
+}
+
 #[cfg(feature = "defmt")]
 impl <T: AsMut<[u8]> + AsRef<[u8]>> defmt::Format for Buffer<T> {
     fn format(&self, fmt: defmt::Formatter) {
@@ -377,7 +421,7 @@ impl <T: AsMut<[u8]> + AsRef<[u8]> + Clone> Clone for Buffer<T> {
 #[cfg(test)]
 mod tests {
 
-    use crate::{new_stack_buffer, Buffer, BufferError};
+    use crate::{Buffer, BufferError};
 
     #[test]
     fn test_std_write_high_cap() {
@@ -472,10 +516,12 @@ mod tests {
     #[test]
     fn test_stack_buffer() {
 
-        let mut buf = new_stack_buffer::<4>();
+        let mut buf = Buffer::<[u8; 4]>::new_stack();
 
         buf.write_base(&[1, 2, 3, 4]).unwrap();
 
+        assert!(! buf.has_remaining_capacity());
+        assert_eq!(buf.remaining_len(), 4);
     }
 
     #[test]
@@ -506,4 +552,37 @@ mod tests {
         let res = buf.skip(5);
         assert_eq!(res, Err(BufferError::NoData));
     }
+
+    #[cfg(feature = "std")]
+    #[test]
+    fn test_vec_source_grow() {
+        use std::io::Write;
+
+        let mut buffer = Buffer::new_heap(8);
+        buffer.write_all(&[1, 2, 3, 4, 5, 6, 7, 8]).unwrap();
+
+        assert!(buffer.write_all(&[9]).is_err());
+
+        buffer.grow(1);
+        buffer.write_all(&[9]).unwrap();
+        assert!(buffer.write_all(&[10]).is_err());
+
+    }
+
+    #[cfg(feature = "std")]
+    #[test]
+    fn test_vec_source_shrink() {
+        use std::io::Write;
+
+        let mut buffer = Buffer::new_heap(8);
+        buffer.write_all(&[1, 2, 3, 4]).unwrap();
+        assert_eq!(buffer.remaining_capacity(), 4);
+
+        buffer.shrink(4).unwrap();
+        assert_eq!(buffer.remaining_capacity(), 0);
+        assert!(buffer.write_all(&[5]).is_err());
+
+        assert!(buffer.shrink(1).is_err());
+
+    }
 }