feat: add configurable sentinel, in-place decode, no-alloc StreamDecoder

Adds sentinel variants, in-place decode, and a no-alloc StreamDecoder (v1.1.0).

Author: ajsb85

CHANGELOG.md

@@ -3,6 +3,21 @@
 All notable changes to this crate are documented here. This project adheres to
 [Semantic Versioning](https://semver.org).
 
+## 1.1.0
+
+### Added
+
+- **Configurable sentinel**: `encode_with_sentinel` / `decode_with_sentinel`
+  (and `*_to_vec_with_sentinel`) on both `cobs` and `cobsr`, for framing with a
+  delimiter other than `0x00`.
+- **In-place decoding**: `cobs::decode_in_place` and
+  `cobs::decode_in_place_with_sentinel`, which decode without a second buffer.
+- **`framing::StreamDecoder`**: an allocation-free streaming frame decoder that
+  reassembles delimited packets into a caller-provided buffer — the pure
+  `no_std` counterpart of `FrameDecoder`, with `reduced` and `sentinel` options.
+
+All additions are backward compatible.
+
 ## 1.0.0
 
 Initial release.

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "cobs_codec_rs"
-version = "1.0.0"
+version = "1.1.0"
 edition = "2021"
 rust-version = "1.81"
 description = "Consistent Overhead Byte Stuffing (COBS) and COBS/R codec: no_std, zero-dependency, for zero-free framing of serial and packet byte streams."

Cargo.toml

@@ -22,20 +22,26 @@ USB, TCP and other byte streams — ideal for embedded and robotics protocols.
 - **Basic COBS** and **COBS/R (Reduced)** encode/decode.
 - **`no_std` and zero dependencies** — the core `encode`/`decode` work on
   caller-provided slices, allocating nothing.
-- **`alloc` conveniences** (`*_to_vec`) and a streaming
+- **Configurable sentinel** — `*_with_sentinel` variants frame with any
+  delimiter byte, not just `0x00`.
+- **In-place decoding** — `cobs::decode_in_place` decodes without a second
+  buffer.
+- **Allocation-free streaming** — `framing::StreamDecoder` reassembles
+  delimited frames into a fixed buffer in pure `no_std`; the `alloc` feature adds
+  the owned-`Vec`
   [`FrameDecoder`](https://docs.rs/cobs_codec_rs/latest/cobs_codec_rs/framing/struct.FrameDecoder.html)
-  for `0x00`-delimited serial links, behind the default `std`/`alloc` features.
+  and `*_to_vec` conveniences.
 - **`const fn`** size helpers (`max_encoded_len`, `encoding_overhead`) for
   compile-time buffer sizing.
 
 ## Install
 
 ```toml
 [dependencies]
-cobs_codec_rs = "1.0"
+cobs_codec_rs = "1.1"
 
 # no_std, no allocator:
-# cobs_codec_rs = { version = "1.0", default-features = false }
+# cobs_codec_rs = { version = "1.1", default-features = false }
 ```
 
 ## Usage

README.md

@@ -63,6 +63,28 @@ pub fn encode(src: &[u8], dst: &mut [u8]) -> usize {
     write_index
 }
 
+/// Encodes `src` with basic COBS into `dst` using an arbitrary `sentinel` byte
+/// instead of `0x00`, returning the number of bytes written.
+///
+/// The output never contains the `sentinel` byte, so `sentinel` (rather than
+/// `0x00`) may be used to delimit packets. Choosing a sentinel that rarely
+/// occurs in your payload minimises overhead. `sentinel == 0` is identical to
+/// [`encode`].
+///
+/// # Panics
+///
+/// Panics if `dst` is shorter than [`max_encoded_len`]`(src.len())`.
+#[must_use]
+pub fn encode_with_sentinel(src: &[u8], dst: &mut [u8], sentinel: u8) -> usize {
+    let n = encode(src, dst);
+    if sentinel != 0 {
+        for byte in &mut dst[..n] {
+            *byte ^= sentinel;
+        }
+    }
+    n
+}
+
 /// Decodes basic-COBS `src` into `dst`, returning the number of bytes written.
 ///
 /// The empty input decodes to nothing (returns `0`). `src` must be a single
@@ -74,6 +96,23 @@ pub fn encode(src: &[u8], dst: &mut [u8]) -> usize {
 /// not valid COBS, or [`DecodeError::OutputTooSmall`] if `dst` is shorter than
 /// the decoded output (which never exceeds `src.len()`).
 pub fn decode(src: &[u8], dst: &mut [u8]) -> Result<usize, DecodeError> {
+    decode_with_sentinel(src, dst, 0)
+}
+
+/// Decodes basic-COBS `src` that was encoded with an arbitrary `sentinel` byte
+/// (see [`encode_with_sentinel`]) into `dst`, returning the number of bytes
+/// written. `sentinel == 0` is identical to [`decode`].
+///
+/// # Errors
+///
+/// Returns [`DecodeError::ZeroByte`] (the encoded input contained the
+/// `sentinel`) or [`DecodeError::Truncated`] if `src` is not valid, or
+/// [`DecodeError::OutputTooSmall`] if `dst` is shorter than the decoded output.
+pub fn decode_with_sentinel(
+    src: &[u8],
+    dst: &mut [u8],
+    sentinel: u8,
+) -> Result<usize, DecodeError> {
     let src_len = src.len();
     if src_len == 0 {
         return Ok(0);
@@ -83,15 +122,15 @@ pub fn decode(src: &[u8], dst: &mut [u8]) -> Result<usize, DecodeError> {
     let mut index = 0;
 
     loop {
-        let code = src[index];
+        let code = src[index] ^ sentinel;
         if code == 0 {
             return Err(DecodeError::ZeroByte { index });
         }
         index += 1;
         let block_end = index + usize::from(code) - 1;
         let copy_end = block_end.min(src_len);
         while index < copy_end {
-            let byte = src[index];
+            let byte = src[index] ^ sentinel;
             if byte == 0 {
                 return Err(DecodeError::ZeroByte { index });
             }
@@ -119,6 +158,74 @@ pub fn decode(src: &[u8], dst: &mut [u8]) -> Result<usize, DecodeError> {
     Ok(write_index)
 }
 
+/// Decodes basic-COBS data in place, overwriting `buf` with the decoded output
+/// and returning its length. The decoded bytes occupy `buf[..len]`.
+///
+/// This needs no output buffer: COBS decoding never expands, so the write
+/// position always trails the read position.
+///
+/// # Errors
+///
+/// Returns [`DecodeError::ZeroByte`] or [`DecodeError::Truncated`] if `buf` is
+/// not valid COBS. [`DecodeError::OutputTooSmall`] is never returned.
+pub fn decode_in_place(buf: &mut [u8]) -> Result<usize, DecodeError> {
+    decode_in_place_with_sentinel(buf, 0)
+}
+
+/// Decodes basic-COBS data that was encoded with an arbitrary `sentinel` byte in
+/// place, overwriting `buf` with the decoded output and returning its length.
+/// `sentinel == 0` is identical to [`decode_in_place`].
+///
+/// # Errors
+///
+/// Returns [`DecodeError::ZeroByte`] or [`DecodeError::Truncated`] if `buf` is
+/// not valid. [`DecodeError::OutputTooSmall`] is never returned.
+pub fn decode_in_place_with_sentinel(buf: &mut [u8], sentinel: u8) -> Result<usize, DecodeError> {
+    let src_len = buf.len();
+    if src_len == 0 {
+        return Ok(0);
+    }
+
+    let mut write_index = 0;
+    let mut index = 0;
+
+    loop {
+        let code = buf[index] ^ sentinel;
+        if code == 0 {
+            return Err(DecodeError::ZeroByte { index });
+        }
+        index += 1;
+        let block_end = index + usize::from(code) - 1;
+        let copy_end = block_end.min(src_len);
+        while index < copy_end {
+            let byte = buf[index] ^ sentinel;
+            if byte == 0 {
+                return Err(DecodeError::ZeroByte { index });
+            }
+            // write_index < index throughout, so this never clobbers unread
+            // input.
+            buf[write_index] = byte;
+            write_index += 1;
+            index += 1;
+        }
+        if block_end > src_len {
+            return Err(DecodeError::Truncated {
+                index: block_end - usize::from(code),
+            });
+        }
+        if block_end < src_len {
+            if code < 0xFF {
+                buf[write_index] = 0;
+                write_index += 1;
+            }
+        } else {
+            break;
+        }
+    }
+
+    Ok(write_index)
+}
+
 /// Encodes `src` with basic COBS, returning a newly allocated [`Vec`].
 #[cfg(feature = "alloc")]
 #[must_use]
@@ -129,6 +236,17 @@ pub fn encode_to_vec(src: &[u8]) -> Vec<u8> {
     dst
 }
 
+/// Encodes `src` with basic COBS and an arbitrary `sentinel` byte, returning a
+/// newly allocated [`Vec`].
+#[cfg(feature = "alloc")]
+#[must_use]
+pub fn encode_to_vec_with_sentinel(src: &[u8], sentinel: u8) -> Vec<u8> {
+    let mut dst = alloc::vec![0u8; max_encoded_len(src.len())];
+    let n = encode_with_sentinel(src, &mut dst, sentinel);
+    dst.truncate(n);
+    dst
+}
+
 /// Decodes basic-COBS `src`, returning a newly allocated [`Vec`].
 ///
 /// # Errors
@@ -141,3 +259,17 @@ pub fn decode_to_vec(src: &[u8]) -> Result<Vec<u8>, DecodeError> {
     dst.truncate(n);
     Ok(dst)
 }
+
+/// Decodes basic-COBS `src` that was encoded with an arbitrary `sentinel` byte,
+/// returning a newly allocated [`Vec`].
+///
+/// # Errors
+///
+/// Returns a [`DecodeError`] if `src` is not valid.
+#[cfg(feature = "alloc")]
+pub fn decode_to_vec_with_sentinel(src: &[u8], sentinel: u8) -> Result<Vec<u8>, DecodeError> {
+    let mut dst = alloc::vec![0u8; src.len()];
+    let n = decode_with_sentinel(src, &mut dst, sentinel)?;
+    dst.truncate(n);
+    Ok(dst)
+}

src/cobs.rs

@@ -73,6 +73,26 @@ pub fn encode(src: &[u8], dst: &mut [u8]) -> usize {
     write_index
 }
 
+/// Encodes `src` with COBS/R into `dst` using an arbitrary `sentinel` byte
+/// instead of `0x00`, returning the number of bytes written.
+///
+/// The output never contains the `sentinel` byte. `sentinel == 0` is identical
+/// to [`encode`].
+///
+/// # Panics
+///
+/// Panics if `dst` is shorter than [`max_encoded_len`]`(src.len())`.
+#[must_use]
+pub fn encode_with_sentinel(src: &[u8], dst: &mut [u8], sentinel: u8) -> usize {
+    let n = encode(src, dst);
+    if sentinel != 0 {
+        for byte in &mut dst[..n] {
+            *byte ^= sentinel;
+        }
+    }
+    n
+}
+
 /// Decodes COBS/R `src` into `dst`, returning the number of bytes written.
 ///
 /// The empty input decodes to nothing (returns `0`).
@@ -85,6 +105,22 @@ pub fn encode(src: &[u8], dst: &mut [u8]) -> usize {
 /// points past the end of the input is not an error: it signals the reduced
 /// final block.
 pub fn decode(src: &[u8], dst: &mut [u8]) -> Result<usize, DecodeError> {
+    decode_with_sentinel(src, dst, 0)
+}
+
+/// Decodes COBS/R `src` that was encoded with an arbitrary `sentinel` byte (see
+/// [`encode_with_sentinel`]) into `dst`, returning the number of bytes written.
+/// `sentinel == 0` is identical to [`decode`].
+///
+/// # Errors
+///
+/// Returns [`DecodeError::ZeroByte`] if `src` contains the `sentinel` byte, or
+/// [`DecodeError::OutputTooSmall`] if `dst` is shorter than the decoded output.
+pub fn decode_with_sentinel(
+    src: &[u8],
+    dst: &mut [u8],
+    sentinel: u8,
+) -> Result<usize, DecodeError> {
     let src_len = src.len();
     if src_len == 0 {
         return Ok(0);
@@ -94,15 +130,15 @@ pub fn decode(src: &[u8], dst: &mut [u8]) -> Result<usize, DecodeError> {
     let mut index = 0;
 
     loop {
-        let code = src[index];
+        let code = src[index] ^ sentinel;
         if code == 0 {
             return Err(DecodeError::ZeroByte { index });
         }
         index += 1;
         let block_end = index + usize::from(code) - 1;
         let copy_end = block_end.min(src_len);
         while index < copy_end {
-            let byte = src[index];
+            let byte = src[index] ^ sentinel;
             if byte == 0 {
                 return Err(DecodeError::ZeroByte { index });
             }
@@ -143,6 +179,17 @@ pub fn encode_to_vec(src: &[u8]) -> Vec<u8> {
     dst
 }
 
+/// Encodes `src` with COBS/R and an arbitrary `sentinel` byte, returning a newly
+/// allocated [`Vec`].
+#[cfg(feature = "alloc")]
+#[must_use]
+pub fn encode_to_vec_with_sentinel(src: &[u8], sentinel: u8) -> Vec<u8> {
+    let mut dst = alloc::vec![0u8; max_encoded_len(src.len())];
+    let n = encode_with_sentinel(src, &mut dst, sentinel);
+    dst.truncate(n);
+    dst
+}
+
 /// Decodes COBS/R `src`, returning a newly allocated [`Vec`].
 ///
 /// # Errors
@@ -155,3 +202,17 @@ pub fn decode_to_vec(src: &[u8]) -> Result<Vec<u8>, DecodeError> {
     dst.truncate(n);
     Ok(dst)
 }
+
+/// Decodes COBS/R `src` that was encoded with an arbitrary `sentinel` byte,
+/// returning a newly allocated [`Vec`].
+///
+/// # Errors
+///
+/// Returns a [`DecodeError`] if `src` is not valid.
+#[cfg(feature = "alloc")]
+pub fn decode_to_vec_with_sentinel(src: &[u8], sentinel: u8) -> Result<Vec<u8>, DecodeError> {
+    let mut dst = alloc::vec![0u8; src.len()];
+    let n = decode_with_sentinel(src, &mut dst, sentinel)?;
+    dst.truncate(n);
+    Ok(dst)
+}