feat: add COBS/R in-place decode

Mirrors basic-COBS in-place; reduced final block appends the code byte.

Author: ajsb85

lib/cobs_codec.dart

@@ -58,6 +58,8 @@ export 'src/cobsr.dart'
         CobsrEncoder,
         cobsr,
         cobsrDecode,
+        cobsrDecodeInPlace,
+        cobsrDecodeInPlaceWithSentinel,
         cobsrDecodeWithSentinel,
         cobsrEncode,
         cobsrEncodeWithSentinel;

lib/src/cobsr.dart

@@ -166,6 +166,81 @@ Uint8List cobsrDecodeWithSentinel(List<int> input, int sentinel) {
   return cobsrDecode(copy);
 }
 
+/// Decodes COBS/R data in place, overwriting [buffer] with the decoded bytes and
+/// returning their length; the decoded output occupies `buffer[0..n]`.
+///
+/// This needs no separate output buffer: the COBS/R decoded length never exceeds
+/// the encoded length, so the write position always trails the read position.
+/// The reduced final block appends its length-code byte onto a position that has
+/// already been read, so unread input is never clobbered. The bytes of [buffer]
+/// beyond the returned length are left in an unspecified (partially overwritten)
+/// state.
+///
+/// As with [cobsrDecode], a length code that points past the end of [buffer] is
+/// not an error: it signals the reduced final block, and the length code itself
+/// is appended as the final data byte.
+///
+/// Throws a [CobsDecodeException] if [buffer] contains a `0x00` byte.
+int cobsrDecodeInPlace(Uint8List buffer) {
+  final srcLen = buffer.length;
+  if (srcLen == 0) return 0;
+
+  var writeIndex = 0;
+  var index = 0;
+
+  while (true) {
+    final code = buffer[index];
+    if (code == 0) {
+      throw CobsDecodeException('zero byte in COBS/R input', buffer, index);
+    }
+    index++;
+    final blockEnd = index + code - 1;
+    final copyEnd = blockEnd < srcLen ? blockEnd : srcLen;
+    for (; index < copyEnd; index++) {
+      final byte = buffer[index];
+      if (byte == 0) {
+        throw CobsDecodeException('zero byte in COBS/R input', buffer, index);
+      }
+      // `writeIndex` trails `index` throughout, so this never clobbers a byte
+      // that has not yet been read.
+      buffer[writeIndex++] = byte;
+    }
+    if (blockEnd > srcLen) {
+      // Reduced encoding: the length code was really the final data byte. The
+      // append lands on an already-read byte (`writeIndex < index == srcLen`),
+      // so it is safe to perform in place.
+      buffer[writeIndex++] = code;
+      break;
+    } else if (blockEnd < srcLen) {
+      if (code < 0xFF) buffer[writeIndex++] = 0;
+    } else {
+      break;
+    }
+  }
+
+  return writeIndex;
+}
+
+/// Decodes COBS/R data that was encoded with an arbitrary [sentinel] byte in
+/// place, overwriting [buffer] with the decoded bytes and returning their
+/// length; the decoded output occupies `buffer[0..n]`.
+///
+/// When [sentinel] is non-zero, [buffer] is first XORed with it (masked to the
+/// low 8 bits) and then decoded in place by [cobsrDecodeInPlace].
+/// `sentinel == 0` is identical to [cobsrDecodeInPlace]. As an in-place
+/// operation this necessarily consumes (overwrites) [buffer].
+///
+/// Throws a [CobsDecodeException] if [buffer] is not valid.
+int cobsrDecodeInPlaceWithSentinel(Uint8List buffer, int sentinel) {
+  final s = sentinel & 0xFF;
+  if (s != 0) {
+    for (var i = 0; i < buffer.length; i++) {
+      buffer[i] ^= s;
+    }
+  }
+  return cobsrDecodeInPlace(buffer);
+}
+
 /// A [Codec] that encodes and decodes bytes with Consistent Overhead Byte
 /// Stuffing — Reduced (COBS/R).
 ///

test/features_test.dart

@@ -92,6 +92,100 @@ void main() {
         expect(Uint8List.sublistView(buf, 0, n), cobsDecode(encoded));
       }
     });
+
+    test('cobsrDecodeInPlace matches cobsrDecode (differential)', () {
+      // Assert that the in-place COBS/R decoder agrees byte-for-byte with the
+      // slice decoder on valid input, and agrees on acceptance vs rejection for
+      // arbitrary (possibly invalid) input.
+      void checkAgrees(List<int> encoded) {
+        Uint8List? sliceResult;
+        var sliceThrew = false;
+        try {
+          sliceResult = cobsrDecode(encoded);
+        } on CobsDecodeException {
+          sliceThrew = true;
+        }
+
+        final buf = Uint8List.fromList(encoded);
+        Uint8List? inPlaceResult;
+        var inPlaceThrew = false;
+        try {
+          final n = cobsrDecodeInPlace(buf);
+          inPlaceResult = Uint8List.sublistView(buf, 0, n);
+        } on CobsDecodeException {
+          inPlaceThrew = true;
+        }
+
+        expect(inPlaceThrew, sliceThrew,
+            reason: 'accept/reject must match for $encoded');
+        if (!sliceThrew) {
+          expect(inPlaceResult, sliceResult, reason: 'decoding $encoded');
+        }
+      }
+
+      // Golden COBS/R encoded vectors (ported from cobsr_test.dart), chosen to
+      // exercise reduced final blocks, embedded zeros, and maximal (0xFF) codes.
+      final golden = <List<int>>[
+        [0x01],
+        [0x02],
+        [0x7F],
+        [0xFF],
+        [0x02, 0x01],
+        [0x03, ...ascii('a'), 0x02],
+        [0x03, ...ascii('a')],
+        [0xFF, ...ascii('a')],
+        [0x06, 0x05, 0x04, 0x03, 0x02, 0x01],
+        [0x35, ...ascii('1234')],
+        [0x06, ...ascii('12345'), 0x05, 0x04, 0x03, 0x02, 0x01],
+        [0x06, ...ascii('12345'), ...ascii('9678')],
+        [0x01, 0x06, ...ascii('12345'), ...ascii('9678')],
+        [0x06, ...ascii('12345'), 0x05, ...ascii('6789'), 0x01],
+        [0x01, 0x01],
+        [0x01, 0x01, 0x01],
+        [0xFE, ...range(1, 254)],
+        [0xFF, ...range(1, 255)],
+        [0xFF, ...range(1, 255), 0xFF],
+        [0x01, 0xFF, ...range(1, 255), 0xFF],
+      ];
+      for (final encoded in golden) {
+        checkAgrees(encoded);
+      }
+
+      // Large seeded-random corpus.
+      final rng = Random(0xC0B5B12A);
+      for (var t = 0; t < 6000; t++) {
+        // Valid encodings from the reference encoder exercise the reduced-block
+        // path and embedded-zero blocks.
+        checkAgrees(cobsrEncode(randomPacket(rng, 700)));
+
+        // Raw random bytes are mostly invalid (embedded zeros / bad codes) and
+        // pin down accept/reject agreement between the two decoders.
+        final rawLen = rng.nextInt(48);
+        checkAgrees(List<int>.generate(rawLen, (_) => rng.nextInt(256)));
+
+        // Non-zero random bytes are always valid COBS/R and heavily exercise
+        // high length codes and reduced final blocks.
+        final nzLen = 1 + rng.nextInt(48);
+        checkAgrees(List<int>.generate(nzLen, (_) => 1 + rng.nextInt(255)));
+      }
+    });
+
+    test('cobsrDecodeInPlaceWithSentinel matches slice decode (differential)',
+        () {
+      final rng = Random(0x1234C0B5);
+      for (final s in sentinels) {
+        for (var t = 0; t < 4000; t++) {
+          final packet = randomPacket(rng, 700);
+          final encoded = cobsrEncodeWithSentinel(packet, s);
+          final expected = cobsrDecodeWithSentinel(encoded, s);
+
+          final buf = Uint8List.fromList(encoded);
+          final n = cobsrDecodeInPlaceWithSentinel(buf, s);
+          expect(Uint8List.sublistView(buf, 0, n), expected);
+          expect(Uint8List.sublistView(buf, 0, n), packet);
+        }
+      }
+    });
   });
 
   group('framing with a sentinel', () {