μCOBS

The COBS implementation for Rust.

Consistent Overhead Byte Stuffing (COBS) encodes arbitrary bytes so that 0x00 never appears in the output, allowing 0x00 to serve as an unambiguous frame delimiter. Overhead is exactly 1 byte per 254 input bytes (worst case).

Features

• no_std, zero-alloc — runs anywhere, from 8-bit MCUs to servers
• ~140 lines of implementation — small, auditable, easy to verify
• 100% spec-compliant — Cheshire & Baker, IEEE/ACM Transactions on Networking, 1999
• Proven interoperability — cross-validated against corncobs, cobs, and Python cobs
• Insanely tested — canonical vectors, property-based tests, fuzz targets, cross-crate interop, randomized payloads, and more coming

Performance

Benchmarked against the two other no_std COBS crates using iai-callgrind (instruction counts via Valgrind — deterministic, zero run-to-run variance). Three payload patterns: all zeros (worst case), no zeros, and mixed (0x00–0xFF cycling). Instruction count per call, lower is better. Legend: 🥇 winner, 🥉 last, 🤝 tie (<3%).

Encode

Decode

Code size

Measured from .text section of release-optimized symbols (encode + decode combined). Run just bench-size to reproduce.

All three crates are under 1 KB. μCOBS is the largest because safe const fn encoding with copy_from_slice/memcpy requires split_at bounds checks that generate panic paths — the cost of combining compile-time safety with runtime speed. Embedded users targeting size over speed can build with opt-level = "s" which reduces μCOBS to ~738 B.

Crate properties

[^1]: Requires disabling the default std feature. [^2]: alloc is enabled by default via the std feature.

Benchmarked with iai-callgrind (Valgrind instruction counting) for deterministic, reproducible results. Run just bench to reproduce. Requires valgrind installed.

When to use μCOBS

Choose μCOBS if you want the smallest, most auditable COBS implementation with a const fn encoder, a dead-simple 3-function API, and leading or tied instruction efficiency across most workloads — plus dominant decode performance on zero-heavy data (3–5× fewer instructions than alternatives). Wins or ties 16 of 18 benchmarks.

Choose corncobs if you need in-place encoding, an iterator-based API, or your workload is dominated by small mixed-pattern decoding where it uses ~8% fewer instructions at 64–256 B.

Choose cobs if you need std convenience features or a streaming state machine. Note: cobs uses 50–75× more instructions than μCOBS/corncobs for decoding non-zero data.

Examples

Basic encode and decode

// Encode: [0x11, 0x00, 0x33] → [0x02, 0x11, 0x02, 0x33]
let mut buf = [0u8; 16];
let n = ucobs::encode(&[0x11, 0x00, 0x33], &mut buf).unwrap();
assert_eq!(&buf[..n], &[0x02, 0x11, 0x02, 0x33]);

// Decode reverses it
let mut out = [0u8; 16];
let m = ucobs::decode(&buf[..n], &mut out).unwrap();
assert_eq!(&out[..m], &[0x11, 0x00, 0x33]);

Buffer sizing

Use max_encoded_len to determine the required destination buffer size:

let data = [0x01, 0x02, 0x03];
let max = ucobs::max_encoded_len(data.len()); // 4 bytes

let mut buf = [0u8; 4];
let n = ucobs::encode(&data, &mut buf).unwrap();
assert_eq!(n, 4); // fits exactly

If the destination is too small, encode returns None rather than panicking:

let mut tiny = [0u8; 1];
assert_eq!(ucobs::encode(&[0x01, 0x02], &mut tiny), None);

Framing for transport

Append a 0x00 sentinel after encoding to delimit frames on a wire. Strip it before decoding:

let data = [0x11, 0x00, 0x33];

// Encode and append sentinel
let mut frame = [0u8; 16];
let n = ucobs::encode(&data, &mut frame).unwrap();
frame[n] = 0x00;
let wire = &frame[..n + 1];

// Receive: strip sentinel, then decode
let cobs_data = &wire[..wire.len() - 1];
let mut out = [0u8; 16];
let m = ucobs::decode(cobs_data, &mut out).unwrap();
assert_eq!(&out[..m], &data);

Parsing a stream of frames

Split a byte stream on 0x00 to extract individual COBS frames:

// Two frames separated by 0x00 sentinels
let stream = [
    0x02, 0x11, 0x02, 0x33, 0x00,  // frame 1: [0x11, 0x00, 0x33]
    0x03, 0xAA, 0xBB, 0x00,        // frame 2: [0xAA, 0xBB]
];

let mut out = [0u8; 16];
let frames: Vec<&[u8]> = stream.split(|&b| b == 0x00)
    .filter(|f| !f.is_empty())
    .collect();

let n = ucobs::decode(frames[0], &mut out).unwrap();
assert_eq!(&out[..n], &[0x11, 0x00, 0x33]);

let n = ucobs::decode(frames[1], &mut out).unwrap();
assert_eq!(&out[..n], &[0xAA, 0xBB]);

Compile-time encoding

encode is const fn, so you can build COBS-encoded tables at compile time with zero runtime cost:

const PING: [u8; 2] = {
    let mut buf = [0u8; 2];
    match ucobs::encode(&[0x01], &mut buf) {
        Some(_) => buf,
        None => panic!("buffer too small"),
    }
};

const ACK: [u8; 3] = {
    let mut buf = [0u8; 3];
    match ucobs::encode(&[0x06, 0x00], &mut buf) {
        Some(_) => buf,
        None => panic!("buffer too small"),
    }
};

// Baked into the binary — no runtime encoding needed
assert_eq!(PING, [0x02, 0x01]);
assert_eq!(ACK, [0x02, 0x06, 0x01]);

Error handling

Both encode and decode return Option<usize> — None on failure, never panic:

let mut buf = [0u8; 8];

// Destination too small
assert_eq!(ucobs::encode(&[1, 2, 3], &mut buf[..1]), None);

// Malformed input (zero byte in encoded stream)
assert_eq!(ucobs::decode(&[0x00], &mut buf), None);

// Truncated frame (code byte promises more data than exists)
assert_eq!(ucobs::decode(&[0x05, 0x11], &mut buf), None);

// Empty input is valid
assert_eq!(ucobs::encode(&[], &mut buf), Some(1)); // encodes to [0x01]
assert_eq!(ucobs::decode(&[], &mut buf), Some(0)); // decodes to []

API

Note: The encoder does not append a trailing 0x00 sentinel. Append it yourself when framing for transport.

Minimum Supported Rust Version

The default build requires Rust 1.93+ (for const copy_from_slice).

legacy-msrv feature

If you're targeting a toolchain older than 1.93 (e.g. Xtensa), enable the legacy-msrv feature to fall back to a manual byte copy in the encoder:

[dependencies]
ucobs = { version = "0.3", features = ["legacy-msrv"] }

All other optimizations (sub-slice scan, zero fast path, decode batch fill) are available regardless of this feature. Only the encode copy phase is affected — it uses a byte loop instead of copy_from_slice/memcpy.

Testing

μCOBS has one of the most thorough test suites of any COBS implementation — 106 tests across 8 categories:

• Canonical vectors — every example from Cheshire & Baker 1999 (the original COBS paper), plus the full Wikipedia vector set
• External corpora — vectors drawn from cobs-c, nanocobs, cobs2-rs, Jacques Fortier's C implementation, and the Python cobs package
• Cross-crate interop — byte-for-byte validation against both corncobs and cobs crates on randomized payloads up to 4 KB
• Property-based tests — 6 proptest suites covering round-trip correctness, no-zero-in-output invariants, encoding properties, decoding properties, structural/algebraic properties, and boundary-region behavior
• Fuzz targets — 3 cargo-fuzz harnesses (decode, round-trip, small-dest) for continuous coverage of edge cases
• Mutation testing — cargo-mutants verifies that the test suite catches injected bugs in every reachable code path
• Boundary tests — exhaustive coverage of 254/255-byte block boundaries, multi-block splits, buffer-exact fits, and off-by-one dest sizes
• Compile-time verification — const assertions that validate encode correctness at compile time

# Unit + property + interop tests
just test-unit

# All quality gates (tests, clippy, fmt, doc, fuzz, miri, mutants)
just test

# Mutation testing only
just test-mutants

License

MIT — Stephen Waits