feat: add COBS/R in-place decode

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

Author: ajsb85

cobs/src/main/kotlin/dev/firechip/cobs/Cobsr.kt

@@ -148,4 +148,78 @@ public object Cobsr {
         }
         return decode(src)
     }
+
+    /**
+     * Decodes COBS/R data in place, overwriting [buffer] with the decoded output
+     * and returning its length; the decoded bytes occupy the first `len` elements
+     * of [buffer].
+     *
+     * This needs no output buffer: a COBS/R encoding is never shorter than its
+     * decoding, so the write position always trails the read position. A length
+     * code that points past the end of the input is not an error here but the
+     * reduced final block, whose data byte is the code value itself; appending it
+     * lands on a byte that has already been read, so decoding never clobbers
+     * unread input.
+     *
+     * @throws CobsDecodeException if [buffer] contains a `0x00` byte.
+     */
+    @JvmStatic
+    public fun decodeInPlace(buffer: ByteArray): Int = decodeInPlace(buffer, COBS_DELIMITER)
+
+    /**
+     * Decodes COBS/R data that was encoded with an arbitrary [sentinel] byte in
+     * place, overwriting [buffer] with the decoded output and returning its
+     * length. A [sentinel] of `0` is identical to [decodeInPlace].
+     *
+     * When [sentinel] is non-zero the buffer is first XORed back to its
+     * `0x00`-based form in place, then decoded in place.
+     *
+     * @throws CobsDecodeException if [buffer] is not valid encoded data.
+     */
+    @JvmStatic
+    public fun decodeInPlace(buffer: ByteArray, sentinel: Byte): Int {
+        val srcLen = buffer.size
+        if (srcLen == 0) return 0
+
+        val s = sentinel.toInt() and 0xFF
+        if (s != 0) {
+            for (i in 0 until srcLen) {
+                buffer[i] = (buffer[i].toInt() xor s).toByte()
+            }
+        }
+
+        var writeIndex = 0
+        var index = 0
+
+        while (true) {
+            val code = buffer[index].toInt() and 0xFF
+            if (code == 0) {
+                throw CobsDecodeException("zero byte in COBS/R input", index)
+            }
+            index++
+            val blockEnd = index + code - 1
+            val copyEnd = if (blockEnd < srcLen) blockEnd else srcLen
+            while (index < copyEnd) {
+                val b = buffer[index].toInt() and 0xFF
+                if (b == 0) {
+                    throw CobsDecodeException("zero byte in COBS/R input", index)
+                }
+                // writeIndex < index throughout, so this never clobbers unread input.
+                buffer[writeIndex++] = b.toByte()
+                index++
+            }
+            if (blockEnd > srcLen) {
+                // Reduced encoding: the length code was the final data byte. The
+                // append overwrites a byte already consumed, so it is safe here.
+                buffer[writeIndex++] = code.toByte()
+                break
+            } else if (blockEnd < srcLen) {
+                if (code < 0xFF) buffer[writeIndex++] = 0
+            } else {
+                break
+            }
+        }
+
+        return writeIndex
+    }
 }

cobs/src/test/kotlin/dev/firechip/cobs/FeaturesTest.kt

@@ -69,6 +69,85 @@ class FeaturesTest {
         }
     }
 
+    // Golden COBS/R encodings ported from the reference suite: valid wire
+    // sequences, including reduced final blocks (e.g. `bytes(0x02)`), embedded
+    // zeros, and maximal `0xFF` length codes.
+    private val cobsrGolden: List<ByteArray> = listOf(
+        bytes(0x01),
+        bytes(0x02, 0x01),
+        bytes(0x02),
+        bytes(0x03),
+        bytes(0x7E),
+        bytes(0x7F),
+        bytes(0x80),
+        bytes(0xD5),
+        bytes(0xFE),
+        bytes(0xFF),
+        cat(bytes(0x03), ascii("a"), bytes(0x02)),
+        cat(bytes(0x03), ascii("a")),
+        cat(bytes(0xFF), ascii("a")),
+        bytes(0x06, 0x05, 0x04, 0x03, 0x02, 0x01),
+        cat(bytes(0x35), ascii("1234")),
+        cat(bytes(0x06), ascii("12345"), bytes(0x05, 0x04, 0x03, 0x02, 0x01)),
+        cat(bytes(0x06), ascii("12345"), ascii("9678")),
+        cat(bytes(0x01, 0x06), ascii("12345"), ascii("9678")),
+        cat(bytes(0x06), ascii("12345"), bytes(0x05), ascii("6789"), bytes(0x01)),
+        bytes(0x01, 0x01),
+        bytes(0x01, 0x01, 0x01),
+        bytes(0x01, 0x01, 0x01, 0x01),
+        cat(bytes(0xFE), range(1, 254)),
+        cat(bytes(0xFF), range(1, 255)),
+        cat(bytes(0xFF), range(1, 255), bytes(0xFF)),
+        cat(bytes(0x01, 0xFF), range(1, 255), bytes(0xFF)),
+        cat(bytes(0xFF), range(2, 255)),
+    )
+
+    /**
+     * The in-place COBS/R decoder must be byte-identical to the slice decoder on
+     * every input and agree on accept/reject. Checked over the golden vectors and
+     * a large seeded-random corpus: half well-formed encodings of random payloads
+     * (including reduced final blocks) and half arbitrary bytes, which stress the
+     * reject paths with embedded zeros and length codes running past the end.
+     */
+    @Test
+    fun cobsrDecodeInPlaceMatchesDecode() {
+        for (encoded in cobsrGolden) {
+            for (s in sentinels) assertCobsrInPlaceMatchesSlice(encoded, s)
+        }
+
+        val rng = Random(0x0C0B5A17)
+        repeat(20000) {
+            val wire = if (rng.nextBoolean()) {
+                val len = rng.nextInt(0, 701)
+                Cobsr.encode(ByteArray(len) { rng.nextInt(0, 256).toByte() })
+            } else {
+                val len = rng.nextInt(0, 40)
+                ByteArray(len) { rng.nextInt(0, 256).toByte() }
+            }
+            for (s in sentinels) assertCobsrInPlaceMatchesSlice(wire, s)
+        }
+    }
+
+    /** Asserts in-place COBS/R decode agrees with the slice decoder: value and error. */
+    private fun assertCobsrInPlaceMatchesSlice(wire: ByteArray, sentinel: Byte) {
+        val slice = runCatching { Cobsr.decodeWithSentinel(wire, sentinel) }
+        val buf = wire.copyOf()
+        val inPlace = runCatching { Cobsr.decodeInPlace(buf, sentinel) }
+
+        if (slice.isSuccess) {
+            assertTrue(
+                "in-place must accept what the slice decoder accepts",
+                inPlace.isSuccess,
+            )
+            assertArrayEquals(slice.getOrThrow(), buf.copyOf(inPlace.getOrThrow()))
+        } else {
+            assertTrue(
+                "in-place must reject what the slice decoder rejects",
+                inPlace.exceptionOrNull() is CobsDecodeException,
+            )
+        }
+    }
+
     @Test
     fun framingWithSentinelRoundTrips() {
         val rng = Random(0x57EA9000)